11
| 1 | Source command string | Input | Char(*) |
| 2 | Length of source command string | Input | Binary(4) |
| 3 | Options control block | Input | Char(*) |
| 4 | Options control block length | Input | Binary(4) |
| 5 | Options control block format | Input | Char(8) |
| 6 | Changed command string | Output | Char(*) |
| 7 | Length available for changed command string | Input | Binary(4) |
| 8 | Length of changed command string available to return | Output | Binary(4) |
| 9 | Error Code | I/O | Char(*) |
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:
The command string to be prompted for or run.
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.
The options that control the handling of the command string. The layout of this parameter is the CPOP0100 Format.
The length of the options control block. A minimum length of 20 is required for the CPOP0100 format.
The format of the options control block. CPOP0100 is the only valid value. For more information, see CPOP0100 Format.
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.
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.
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.
The structure in which to return error information. For the format of the structure, see Error Code Parameter.
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.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Type of command processing |
| 4 | 4 | CHAR(1) | DBCS data handling |
| 5 | 5 | CHAR(1) | Prompter action |
| 6 | 6 | CHAR(1) | Command string syntax |
| 7 | 7 | CHAR(4) | Message retrieve key |
| 11 |
4 | BINARY(4) | CCSID of command string |
| 15 | B | CHAR(5) | Reserved |
CCSID of command string. CCSID of the command string. The possible values are:
| 0 | Input is in the job CCSID. |
| 1208 | The command string is in UTF8. |
| 1200 | The command string is in UTF16. |
Command string syntax. Whether command processing should be done in i5/OS 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. |
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. |
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. |
| 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. |
| 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:
This type processes commands with entry codes of Job: I (value of *INTERACT 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 entry code for the command must be Job: B. 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 entry codes of Pgm: B, Pgm: I, or Pgm: B,I. They have values of *BPGM or *IPGM on the ALLOW parameter of the CRTCMD or CHGCMD command. |
| 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. |
| 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. |
| 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. |
| 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 entry codes of CLLE: B, CLLE: I, or CLLE: B,I. They have values of *IMOD or *BMOD on the ALLOW parameter of the CRTCMD or CHGCMD command. |
| 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. 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:
|
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.
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
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.
The prompter option field in the options control block is ignored if 10 is specified for the type of command processing field.
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.
Proxy commands will be resolved before the command exit points QIBM_QCA_CHG_COMMAND and QIBM_QCA_RTV_COMMAND are called.
| Message ID | Error Message Text |
|---|---|
| CPF0008 E | Value in option control block not valid. |
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3C1D E | Length specified in parameter &1 not valid. |
| CPF3C20 E | Error found by program &1. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3CF2 E | Error(s) occurred during running of &1 API. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
| xxxnnnn E | Any escape message issued by any command may be returned. The messages listed previously are those issued by this API. Once the API has called the command analyzer, any message issued as an escape may appear. |
| Top | Program and CL Command APIs | APIs by category |