inquiry Command

Inquiries can be evaluated to produce a list of objects to be loaded into a table in a JSP application. In general, the idea is to produce a list of business object ids, since they are the fastest way of identifying objects for loading into browsers. Inquiries include code, which is generally defined as a temp query or expand bus command, as well as information on how to parse the returned results into a list of OIDs.

This page discusses:

User Level

Business Administrators can create new inquiry objects if they have the Inquiry administrative access.

Syntax

The command uses this syntax.

[add|copy|modify|evaluate|list|print|delete] inquiry NAME {CLAUSE};
  • NAME is the name of the inquiry you are defining. Inquiry names cannot include asterisks. You must specify a unique name for each inquiry that you create. The name you choose is the name that will be referenced to evaluate this inquiry within a JSP.
  • CLAUSEs provide additional information about the inquiry.

Add Inquiry

To define an inquiry from within MQL use the Add Inquiry command.

Syntax

add inquiry NAME [ADD_ITEM {ADD_ITEM}];
  • ADD_ITEM is an Add Inquiry clause that provides additional information about the inquiry.

The Add Inquiry clauses are:

description STRING_VALUE
 
icon FILENAME
 
pattern VALUE
 
format VALUE
 
code VALUE
 
file FILENAME
 
augument NAME [STRING]
 
property NAME on ADMIN [to ADMIN] [value STRING]
 
history STRING

Pattern Clause

JPOs are another option in addition to inquiries that can be used for building table IDs. In some cases a JPO should be used in place of an inquiry because of inquiry limitations. Multi-value selectables or relationship based selectables should not be used with inquiries since they might not produce a consistent pattern. JPOs should be used in this case because they do not parse and don’t require you to match an explicit pattern. Only attributes and basics should be used with inquiries.

This clause indicates the expected pattern of the results of the evaluated code, and shows how the output should be parsed. It sets the desired field to an RPE variable or macro. Since inquiries are designed to produce a list of business objects, generally the macro that is set is OID.

When you execute a temp query in MQL, the business objects found are returned in a list that includes the type, name and revision, as well as any selectable information specified. For more information, see Temporary Query. For example, the following code:

temp query bus Part * * select id dump;

would return a list like:

Part,PT-6170-01,1,21762.30027.65182.63525 
Part,PT-6180-01,1,21762.30027.50161.30295 
Part,PT-6190-01,1,21762.30027.56625.19298 
Part,PT-6200-01,1,21762.30027.37094.65388

To indicate that there are four fields that will be returned, delimited with a comma, and the last field is the OID, you would use the following pattern:

*,*,*,${OID}

For an expand bus command, even more information is output before the select fields:

expand bus Person "Test Buyer" - from relationship "Assigned Buyer" 
  select businessobject id dump |; 
1|Assigned Buyer|to|Buyer Desk|Buy 001|-|37819.19807.45300.63521

To parse this output, you need to indicate that the first six fields, delimited by “|”, should be ignored, and the seventh field is the OID. You would use:

*|*|*|*|*|*|${OID}

For more information, see Expand Business Object.

Format Clause

This clause defines what part of the output results should be saved in the inquiry’s list. It references variables or macros specified in the Pattern, and can include delimiters.

The syntax is:

format VALUE;

  • VALUE is the part of the output results that should be saved in the inquiry’s list.

For example:

format ${OID};

Code Clause

This clause Code clause of the Add Inquiry command is used to provide the code to be evaluated to produce a list of one or more business objects.

The syntax is:

code VALUE;
  • VALUE is the code commands and commands.

The code provided is generally an MQL temp query or expand bus command that selects the found objects’ ids. It can contain complicated where clauses as needed. For example:

temp query bus "Package" * * 
   where 
     "('Project'==to[Vaulted Documents Rev2].businessobject.to[Workspace Vaults]
         .businessobject.type) 
     &&  ('${USER}'==to[Vaulted Documents Rev2].businessobject.to[Workspace Vaults]
         .businessobject.from[Project Members].businessobject.to[Project Membership].businessobject.name)" 
     select id dump |;

When macros are included in the code (${USER} in example above), they should be surrounded by single or double quotes, in case the substitution contains a space. Quotes around both the macro in the code and the Argument when it contains a space ensures that the macro substitution is handled correctly.

File Clause

This clause does not need to be included in the Add Inquiry command itself. It can be written in an external editor.

The syntax is:

file FILENAME;

  • FILENAME is the name of the file that contains the code for the inquiry.

Argument Clause

This clause is used to provide any input arguments that the inquiry might need. Arguments are name/value pairs that can be added to an Inquiry as necessary to be used by the inquiry code. Depending upon how you write the code in both the Inquiry and the JSP, you might or might not use arguments.

The syntax is:

argument NAME [STRING];

  • NAME is the name of the argument.
  • STRING is the input argument to be added. Include quotes if the value contains a space.

Quotes around both the macro in the code and the Argument when it contains a space ensures that the macro substitution is handled correctly.

History Clause

The history keyword adds a history record marked “custom” to the inquiry that is being added. The STRING argument is a free-text string that allows you to enter some information describing the nature of the addition. For more information, see Adding History to Administrative Objects.

Copy Inquiry

After an inquiry is defined, you can clone the definition with the Copy Inquiry command. Cloning a inquiry definition requires Business Administrator privileges, except that you can copy a inquiry definition to your own context from a group, role or association in which you are defined.

Syntax

This command lets you duplicate defining clauses with the option to change the value of clause arguments:

copy inquiry SRC_NAME DST_NAME [MOD_ITEM {MOD_ITEM}];
  • SRC_NAME is the name of the inquiry definition (source) to be copied.
  • DST_NAME is the name of the new definition (destination).
  • MOD_ITEMs are modifications that you can make to the new definition. For more information, see Modify Inquiry.

History Clause

The history keyword adds a history record marked “custom” to the inquiry that is being copied. The STRING argument is a free-text string that allows you to enter some information describing the nature of the copy operation. For more information, see Adding History to Administrative Objects.

Modify Inquiry

The List Inquiry command displays a list of all inquiries that are currently defined. It is useful in confirming the existence or exact name of an inquiry that you want to modify, since it is case-sensitive.

list inquiry [modified after DATE] NAME_PATTERN [select FIELD_NAME {FIELD_NAME}]
    [DUMP [RECORDSEP]] [tcl] [output FILENAME];

For more information, see List Admintype Command. Use the list of all the existing inquiries along with the Print command to determine the search criteria you want to change.

Use the Modify Inquiry command to add or remove defining clauses and change the value of clause arguments: 

modify inquiry NAME [MOD_ITEM {MOD_ITEM}];

  • NAME is the name of the inquiry you want to modify.
  • MOD_ITEM is the type of modification you want to make. Each is specified in a Modify Inquiry clause, as listed in the following inquiry. You only need to specify the fields to be modified.
    Modify Inquiry Clause Specifies
    name NEW_NAME The current inquiry name is changed to the new name entered.
    description VALUE The current description value, if any, is set to the value entered.
    icon FILENAME The image is changed to the new image in the file specified.
    pattern VALUE The pattern is changed to the new value specified.
    format VALUE The format is changed to the new output results specified by value.
    code VALUE The code associated with the inquiry is replaced by the new code specified.
    file FILENAME The file that contains the inquiry code is changed to the file specified.
    add argument NAME [STRING] The specified argument is added to the inquiry.
    remove argument NAME [STRING] The specified argument is removed from the inquiry.
    property NAME [to ADMINTYPE NAME] [value STRING] The named property is modified.
    add property NAME [to ADMINTYPE NAME] [value STRING] The named property is added.
    remove property NAME [to ADMINTYPE NAME] [value STRING] The named property is removed.
    history STRING Adds a history record marked "custom" to the inquiry that is being modified. The STRING argument is a free-text string that allows you to enter some information describing the nature of the modification. For more information, see Adding History to Administrative Objects.

Each modification clause is related to the arguments that define the inquiry. To change the value of one of the defining clauses or add a new one, use the Modify clause that corresponds to the desired change.

When modifying an inquiry, you can make the changes from a script or while working interactively with MQL.

  • If you are working interactively, perform one or two changes at a time to avoid the possibility of one invalid clause invalidating the entire command.
  • If you are working from a script, group the changes together in a single Modify Inquiry command.

Evaluate Inquiry

You can evaluate the Inquiry to determine if it will parse the output as you have designed the JSP to expect to receive it. Use the evaluate query command to execute the inquiry’s code, parse it, and display the generated list.

To override any specified Arguments, or include input that the inquiry might otherwise receive from the JSP, enter name/value pairs. Include only a space between multiple inputs, using quotes around values that contain spaces.

The syntax is: 

evaluate inquiry NAME [NAME VALUE [NAME VALUE [...]]];

Delete Inquiry

If an inquiry is no longer required, you can delete it using the Delete Inquiry command.

delete inquiry NAME;
  • NAME is the name of the inquiry to be deleted.

Searches the list of defined inquiries. If the name is found, that inquiry is deleted. If the name is not found, an error message is displayed. For example, to delete the inquiry named “sub-assembly parts,” enter the following:

delete inquiry “sub-assembly parts”;

After this command is processed, the inquiry is deleted and you receive an MQL prompt for another command.