Process Commands (QCAPCMD) API

The Process Commands (QCAPCMD) API is used to perform command analyzer processing on command strings. You can check or run CL commands from HLLs as well as check syntax for specific source definition types.

You can use the QCAPCMD API to:

• Check the syntax of a command string prior to running it
• Prompt the command and receive the changed command string
• Run a command from an HLL

Authorities and Locks

Command

*USE

Command library

*EXECUTE

Required Parameter Group

Source command string

INPUT; CHAR(*)

The command string to be prompted for or run.

Length of source command string

INPUT; BINARY(4)

The length of the source command string. Valid values are between 1 and 32 702. Message CPF3C1D will result for values outside this range. This length can include trailing blanks.

Options control block

INPUT; CHAR(*)

The options that control the handling of the command string. The layout of this parameter is the CPOP0100 Format.

Options control block length

INPUT; BINARY(4)

The length of the options control block. A minimum length of 20 is required for the CPOP0100 format.

Options control block format

INPUT; CHAR(8)

The format of the options control block. CPOP0100 is the only valid value. For more information, see CPOP0100 Format.

Changed command string

OUTPUT; CHAR(*)

The rebuilt command string. This is the updated command string, which includes changes from prompting, ordering of parameters, and the addition of keywords. This string may be substantially longer than the source command string. If an error occurs that prevents the command string from being rebuilt, this field is not changed. No padding is performed on the value returned. The length of changed command string available to return parameter should be used to determine how much data is returned.

Length available for changed command string

INPUT; BINARY(4)

The length available to return the updated command string. If an updated command string is not desired, a special value of 0 may be specified. This value must be a positive number or zero.

Length of changed command string available to return

OUTPUT; BINARY(4)

The length of the changed command string returned or available to return. If zero is specified for the length available for changed command string parameter, this value is not set. If an error occurs that prevents the command string from being rebuilt, this field is zero. If the changed command string parameter is not large enough to hold the entire rebuilt command string, this value is the total length available. The changed command string is truncated.

Error code

I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error code parameter.

CPOP0100 Format

The CPOP0100 format includes information on the contents of the options control block parameter. The following table shows how this information is organized. For detailed descriptions of the fields in the list, see Field Descriptions.

Field Descriptions

CCSID of command string. CCSID of the command string. The possible values are:

Command string syntax. Whether command processing should be done in IBM^® i mode or System/38™ mode. The possible values are:

0	Use system syntax. The specification of qualified objects is in the format library/object.
1	Use System/38 syntax. The specification of qualified objects is in the format object.library. The system searches the QUSER38 library (if it exists) and the QSYS38 library for the command even though these libraries are not in the library list. This value is not allowed if the CCSID of the input command string is 1208 (UTF8) or 1200 (UTF16).

DBCS data handling. Whether the command analyzer should handle the SO/SI characters as DBCS delimiters. It is valid with all classes of command processing. This option is the equivalent of specifying the IGC process control parameter on the Execute Command (QCMDEXC) and Check Command Syntax (QCMDCHK) APIs. The possible values are:

0	Ignore DBCS data.
1	Handle DBCS data. This value is not allowed if the CCSID of the input command string is 1208 (UTF8) or 1200 (UTF16).

Message retrieve key. The message retrieve key identifies a request message. If prompting is requested, the request message identified by the message retrieve key is replaced by the updated command string. The updated command can then be logged in the job log. If the message key contains all hexadecimal zeros or all blanks, no request message is updated. The message key is valid for processing command types 0, 1, 2, and 3. The message key is ignored for processing command types 4, 5, 6, 7, 8, and 9. The message key is valid only during the current job.

Prompter action. Indicates whether the prompter should be called on a command string.

0	Never prompt the command. This will prevent a command prompt even if selective prompting characters are present in the command string. Note: When the type of command processing field is 2 or 3 and there are missing required parameters, the command will be prompted, even when the prompter action is set to 0.
1	Always prompt the command. This forces a command prompt even if selective prompting characters are not present in the command string. This value is not allowed if the CCSID of the input command string is 1208 (UTF8) or 1200 (UTF16).
2	Prompt the command if selective prompting characters are present in the command string. A CPF0008 exception is sent if this value is specified with types of command processing values 4 through 8. This value is not allowed if the CCSID of the input command string is 1208 (UTF8) or 1200 (UTF16).
3	Show help. Provides help display for the command.

Reserved. This area must be set to hexadecimal zeros.

Type of command processing. The type of command processing to be performed by the system. The following processes can occur:

0	Command running. The processing for this type is the same as that performed by the QCMDEXC API. Commands processed must have a value of *EXEC on the ALLOW parameter of the Create Command (CRTCMD) or the Change Command (CHGCMD) command.
1	Command syntax check. The processing for this type is the same as that performed by the QCMDCHK API.
2	Command line running. This processing is like that provided by the QCMDEXC API but with the following additions: Limited user checking is performed. Prompting for missing required parameters is performed. If the System/36™ environment is active and the commands are System/36 commands, the System/36 environment runs the commands. This type processes commands with value *INTERACT specified on the ALLOW parameter of the CRTCMD or CHGCMD command. While this type is meant to implement an interactive command line, it can be used in batch. When used in a batch job, the command must have been created or changed to specify value *BATCH on the ALLOW parameter of the CRTCMD or CHGCMD command. Limited user checking and System/36 environment processing is done while prompting options are ignored.
3	Command line syntax check. This processing provides the check only complement of type 2 (command line running). The check option performs all checks against CL rules. The System/36 environment is not called.
4	CL program statement. The command string is checked according to the rules for CL programs (source entry utility (SEU) member type of CLP). Commands may not be run with this type. Command prompts include a prompt for a command label and comment. Variable names are allowed. Commands processed for this type must be defined with values of *BPGM or *IPGM on the ALLOW parameter of the CRTCMD or CHGCMD command. This value is not allowed if the CCSID of the input command string is 1208 (UTF8) or 1200 (UTF16).
5	CL input stream. The command string is checked according to the rules for CL batch jobs (SEU member type of CL). Commands may not be run. Command prompts include a prompt for comment. Variable names are not allowed.
6	Command definition statements. The command string is checked according to the rules for command definition (SEU member type of CMD). Commands may not be run. The commands are restricted to CMD, PARM, ELEM, QUAL, DEP, and PMTCTL. This value is not allowed if the CCSID of the input command string is 1208 (UTF8) or 1200 (UTF16).
7	Binder definition statements. The command string is checked according to the rules for binder definition (SEU member type of BND). Commands may not be run. The commands are restricted to STRPGMEXP, ENDPGMEXP, and EXPORT. This value is not allowed if the CCSID of the input command string is 1208 (UTF8) or 1200 (UTF16).
8	User-defined option. This option allows a user to create user-defined option command strings similar to those used by the programming development manager (PDM). It allows checking and creating a command string for future use with types 0 through 3 except that variables are allowed. The command string produced may not be directly operable. That is, if CL variables were specified in the command string, the user must perform a substitution prior to using the API with types of 0 or 2. This value is not allowed if the CCSID of the input command string is 1208 (UTF8) or 1200 (UTF16).
9	ILE CL program source. The source is checked according to the rules for ILE CL programs (source entry utility (SEU) member type of CLLE). Commands may not be run with this type. Command prompts include a prompt for a command label and comment. Variable names are allowed. Commands processed for this type must be defined with values *IMOD or *IPGM or *BMOD or *BPGM specified for the ALLOW parameter of the CRTCMD or CHGCMD command. This value is not allowed if the CCSID of the input command string is 1208 (UTF8) or 1200 (UTF16).
10	Command prompt string. The command analyzer prepares the source command for prompting and returns the command string to use for the initial prompt display. If the command has an exit program registered for the QIBM_QCA_CHG_COMMAND exit point, the exit program is called. If the exit program replaces the original command, the changed command string returned by QCAPCMD is the replacement command from the exit program. The returned command string may not be syntactically correct because no syntax checking is done on the replacement command. This value is not allowed if the CCSID of the input command string is 1208 (UTF8) or 1200 (UTF16). The length of changed command string available to return is set to 0 and the changed command string parameter is not changed if any of these conditions are true: The exit program is not called The exit program ends in error. The exit program does not replace the command.

Usage Notes

1. While this API is threadsafe, it should not be used to run a command that is not threadsafe in a job that has multiple threads. Use the Display Command (DSPCMD) command to determine whether a command is threadsafe.

2. The prompt actions controlled by the prompter option field in the option control block have the following considerations.

   • For commands with a value of 0, 1, 2, or 3 for the type of command processing field, a prompt occurs when 2 is specified for the prompter option field if:

     • Selective prompting is specified in the source command string parameter.

     • The job is running interactively.

   • If this API is called in a batch job with a valid prompt request, it is ignored. A valid prompt request is issued by specifying:

     • 1 for the prompter option field

     • 2 for the prompter option field with selective prompting characters in the command string

     • 3 for help

3. Calls of the API in batch jobs with values of 4, 5, 6, or 7 for the type of command processing field are processed. However, prompting requests are ignored.

4. The prompter option field in the options control block is ignored if 10 is specified for the type of command processing field.

5. If the command to be executed is a proxy command, the QCAPCMD API will resolve to the target command. If the target command is also a proxy, the process repeats until either a non-proxy command is found, or the proxy chain becomes greater than the allowed maximum. Once a non-proxy command is found, the resolved command will replace the proxy command in the command string to be executed.

6. Proxy commands will be resolved before the command exit points QIBM_QCA_CHG_COMMAND and QIBM_QCA_RTV_COMMAND are called.

Error Messages

[ Back to top | Program and CL Command APIs | APIs by category ]