Retrieve Command Information (QCDRCMDI) API
Required Parameter Group:
| 1 | Receiver variable | Output | Char(*) |
| 2 | Length of receiver variable | Input | Binary(4) |
| 3 | Format name | Input | Char(8) |
| 4 | Qualified command name | Input | Char(20) |
| 5 | Error code | I/O | Char(*) |
Optional Parameter:
| 6 | Follow proxy chain | Input | Char(1) |
Default Public Authority: *USE
Threadsafe: Yes
The Retrieve Command Information (QCDRCMDI) API retrieves information from a command definition object and places it into a single variable in the calling program. The amount of information returned depends on the size of the variable. The information returned is the same information returned by the Display Command (DSPCMD) command.
You can use the QCDRCMDI API to retrieve any operable command. This includes
both interactive (such as Display Program (DSPPGM) and Create Library (CRTLIB))
and non-interactive (such as DO, IF, and ELSE) commands. It does not include
command definition statements that appear in command source, such as CMD, DEP,
ELEM, PARM, PMTCTL, and QUAL.
Authorities and Locks
- Command Definition Object Authority
- *USE
- Library Authority
- *EXECUTE
- Command Definition Object Lock
- *SHRRD
Required Parameter Group
- Receiver variable
- OUTPUT; CHAR(*)
The variable that is to receive the information requested. The minimum size for this area is 8 bytes. You can specify the size of this area to be smaller than the format requested as long as you specify the length parameter correctly. As a result, the API returns only the data that the area can hold.
- Length of receiver variable
- INPUT; BINARY(4)
The length of the receiver variable. If this value is larger than the actual size of the receiver variable, the result may not be predictable. The minimum length is 8 bytes.
- Format name
- INPUT; CHAR(8)
The format of the command information to be returned. One of the following format names may be used:
CMDI0100 Format Basic command information. CMDI0200 Format Complete command information.
- Qualified command name
- INPUT; CHAR(20)
The name of the command whose values are to be retrieved. The first 10 characters contain the name of the command. The second 10 characters contain the name of the library where the command is located.
You can use these special values for the library name:
*CURLIB The job's current library *LIBL The library list
- Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter.
Optional Parameter Group
- Follow proxy chain
- INPUT; CHAR(1)
If the specified command is a proxy command, indicates whether the proxy command chain should be followed or not. If this parameter is omitted, a value of '0' is assumed.
The valid values are as follows:
0 Retrieve the information for the specified command. If the specified command is a proxy command, information retrieved is limited to the proxy command indicator, the target command name and target command's library name, and the command object's text description. 1 If the specified command is a proxy command, follow the proxy command chain to the target non-proxy command and retrieve information for the target command. If the command is not a proxy command, retrieve information for the specified command.
CMDI0100 Format
The following table describes the information that is returned in the receiver variable for the CMDI0100 format. For detailed descriptions of the fields, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | CHAR(10) | Command name |
| 18 | 12 | CHAR(10) | Command library name |
| 28 | 1C | CHAR(10) | Command processing program or proxy target command |
| 38 | 26 | CHAR(10) | Command processing program's or proxy target command's library name |
| 48 | 30 | CHAR(10) | Source file name |
| 58 | 3A | CHAR(10) | Source file library name |
| 68 | 44 | CHAR(10) | Source file member name |
| 78 | 4E | CHAR(10) | Validity check program name |
| 88 | 58 | CHAR(10) | Validity check program library name |
| 98 | 62 | CHAR(10) | Mode information |
| 108 | 6C | CHAR(15) | Where allowed to run |
| 123 | 7B | CHAR(1) | Allow limited user |
| 124 | 7C | BINARY(4) | Maximum positional parameters |
| 128 | 80 | CHAR(10) | Prompt message file name |
| 138 | 8A | CHAR(10) | Prompt message file library name |
| 148 | 94 | CHAR(10) | Message file name |
| 158 | 9E | CHAR(10) | Message file library name |
| 168 | A8 | CHAR(10) | Help panel group name |
| 178 | B2 | CHAR(10) | Help panel group library name |
| 188 | BC | CHAR(10) | Help identifier |
| 198 | C6 | CHAR(10) | Search index name |
| 208 | D0 | CHAR(10) | Search index library name |
| 218 | DA | CHAR(10) | Current library |
| 228 | E4 | CHAR(10) | Product library |
| 238 | EE | CHAR(10) | Prompt override program name |
| 248 | F8 | CHAR(10) | Prompt override program library name |
| 258 | 102 | CHAR(6) | Restricted to target release |
| 264 | 108 | CHAR(50) | Text description |
| 314 | 13A | CHAR(2) | Command processing program call state |
| 316 | 13C | CHAR(2) | Validity check program call state |
| 318 | 13E | CHAR(2) | Prompt override program call state |
| 320 | 140 | BINARY(4) | Offset to help bookshelf information |
| 324 | 144 | BINARY(4) | Length of help bookshelf information |
| 328 | 148 | BINARY(4) | Coded character set ID (CCSID) |
| 332 | 14C | CHAR(1) | Enabled for GUI indicator |
| 333 | 14D | CHAR(1) | Threadsafe indicator |
| 334 | 14E | CHAR(1) | Multithreaded job action |
| 335 | 14F | CHAR(1) | Proxy command indicator |
| 336 | 150 | CHAR(1) | Prompt message file text indicator |
| 337 | 151 | CHAR(13) | Reserved |
CMDI0200 Format
The following table describes the information that is returned in the receiver variable for the CMDI0200 format. For detailed descriptions of the fields, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | Returns everything from format CMDI0100 | |
| 350 | 15E | CHAR(10) | REXX source file name |
| 360 | 168 | CHAR(10) | REXX source file library name |
| 370 | 172 | CHAR(10) | REXX source file member name |
| 380 | 17C | CHAR(10) | REXX command environment name |
| 390 | 186 | CHAR(10) | REXX command environment library name |
| 400 | 190 | CHAR(40) | Reserved |
| 440 | 1B8 | BINARY(4) | Number of REXX exit entries |
| 444 | 1BC | BINARY(4) | Length of a REXX exit entry |
| Format of a REXX exit entry (repeated by the number of REXX exit entries) | |||
| See note | See note | CHAR(10) | REXX exit program name |
| See note | See note | CHAR(10) | REXX exit program library name |
| See note | See note | BINARY(4) | REXX exit code |
| Note: The decimal and hexadecimal offsets to the above 3 fields depend on the number of REXX exit entries and the length of a REXX exit entry. The REXX exit entry fields (currently REXX exit program name, REXX exit program library name, and REXX exit code) repeat, in the order listed, by the number of REXX exit entries defined for this command. | |||
Field Descriptions
For more information about the following fields, see the documentation for the Create Command (CRTCMD) command in the online help.
Allow limited user. Whether or not a user with limited authorities is allowed to run this command. The possible values are 0 (*NO) or 1 (*YES).
Bytes available. The length of all data available for the requested format. All available data is returned if enough space is provided.
Bytes returned. The length of all data actually returned. If the data is truncated because the receiver variable is not large enough to hold the data, this value is less than the bytes available.
Coded character set ID (CCSID). The value of the coded character set ID associated with this command. It is the value of the job coded character set ID when this command was created.
Command library name. The name of the library in which the command description resides.
Command name. The name of the command description about which information is being returned.
Command processing program call state. The state the command processing program is called from. The possible values are:
| *S | The command processing program is called from system state. |
| *U | The command processing program is called from user state. |
Command processing program's or proxy target command's library name. The name of the library in which the command processing program or proxy target command resides. This field is blank if the command processing program name contains the special value *REXX.
Command processing program name or proxy target command name. The name of the program or target command that accepts parameters from the command and processes the command. Consult the proxy command indicator to determine if the value is a program or command name. The possible values are:
| *REXX | The REXX fields returned in the CMDI0200 format contain valid information about the command. |
| CPP-program-name | The command processing program name. |
| Proxy target command name | The proxy target command name. |
Current library. The name of the library used as the current library during the processing of this command. The possible values are:
| *NOCHG | The current library does not change for the processing of this command. If the current library is changed during processing of the command, the change remains in effect after command processing is complete. |
| *CRTDFT | No current library is active during processing of the command. The current library that was active before command processing began is restored when processing is completed. |
| library-name | The name of the library that is used as the current library. When command processing is completed, the current library is restored to its previous value. |
Enabled for GUI indicator. Whether the command prompt panels are enabled for conversion to a graphical user interface. The possible values are:
| 0 | The command prompt panels are not enabled for conversion to a graphical user interface. |
| 1 | The command prompt panels are enabled for conversion to a graphical user interface by including information about the panel content in the 5250 data stream. |
Help identifier. The name of the general help module for the names of the help identifiers for this command. The possible values are:
| *NONE | No help identifier is specified. |
| *CMD | The name of the command is used. |
| help-ID-name | A user-specified help module was used. |
Help panel group library name. The name of the library in which the panel group resides.
Help panel group name. The name of the panel group in which the online help information exists for this command. If *NONE is returned, no help panel group is defined for this command.
Length of a REXX exit entry. The length of one REXX exit entry. This value is currently 24. There are 10 bytes for the REXX exit program name, 10 bytes for the REXX exit library name, and 4 bytes for the REXX exit code.
Length of help bookshelf information. This value will always be zero.
Maximum positional parameters. The maximum number of parameters than can be coded in a positional manner for this command. The possible values are:
| -1 | No maximum positional coding limit was specified for this command. |
| 0 through 75 | The maximum number of parameters that can be coded in a positional manner for this command. |
Message file library name. The name of the library in which the message file resides.
Message file name. The message file from which messages identified on the DEP statements used to define the command are retrieved.
Mode information. The mode of operating environment to which the command applies. The characters of this field are as follows, and they can have a value of 0 (does not apply) or 1 (does apply):
| 1 | Production mode |
| 2 | Debug mode |
| 3 | Service mode |
| 4-10 | Reserved |
Multithreaded job action. The action to take when a command that is not threadsafe is called in a multithreaded job. The possible values are:
| 0 | Use the action specified in QMLTTHDACN system value. |
| 1 | Run the command. Do not send a message. |
| 2 | Send an informational message and run the command. |
| 3 | Send an escape message, and do not run the command. |
If the threadsafe indicator is either threadsafe or conditionally threadsafe, the multithreaded job action value will be returned as 1.
Number of REXX exit entries. The number of times the REXX exit entries are repeated. These fields are REXX exit program name, REXX exit program library name, and REXX exit code.
Offset to help bookshelf information. This value will always be zero.
Product library. The name of the product library that is in effect during the processing of the command. The possible values are:
| *NOCHG | The product library does not change for the processing of this command. |
| *NONE | There is no product library in the job's library list. |
| library-name | The name of the library that is used as the product library during the processing of the command. |
Prompt message file library name. The name of the library in which the prompt message file resides.
Prompt message file name. The name of the message file that contains the prompt text for this command. If *NONE is returned, no message file was specified for prompt text.
Prompt message file text indicator. Whether text messages used by the command are retrieved from the prompt message file when the command is prompted. The possible values are:
| 0 | When the command is prompted, the prompt text will be retrieved from the static copies of the messages stored in the *CMD object when the command was created. |
| 1 | When the command is prompted, the prompt text will be dynamically retrieved from the message file specified for the prompt message file (PMTFILE) parameter when the command was created. If an error occurs locating the message file when the command is prompted, all prompt text will be retrieved from the static copies of prompt messages stored in the *CMD object. If the message file is found, but an individual prompt text message is not found in the message file, the static copy of the prompt text stored in the *CMD object is used for that one message. |
Prompt override program call state. The state the prompt override program is called from. The possible values are:
| *S | The prompt override program is called from the system state. |
| *U | The prompt override program is called from the user state. |
Prompt override program name. This is the name of the prompt override program that replaces default values (on the prompt display) with the current actual values for the parameter. If *NONE is returned, no prompt override program was specified for this command.
Proxy command indicator. Whether the command processing program name and command processing program library name fields contain program or command information. The possible values are:
| 0 | The values specified for the command processing program and library refer to a program. |
| 1 | The values specified for the command
processing program and library refer to a proxy target command.
When true, the fields returned are:
|
Reserved. An ignored field.
Restricted to target release. The version, release, and modification level to which this command is restricted. If this field is blank, the command can be used in the current release. This applies only to a command used in a CL program. It must match the contents of the target release parameter on the Create CL Program (CRTCLPGM) command. See the CRTCLPGM command for more information. This field has the format VvRrMm, where:
| Vv | The character V is followed by a 1-character version number. |
| Rr | The character R is followed by a 1-character release level. |
| Mm | The character M is followed by a 1-character modification level. |
REXX command environment library name. The name of the library in which the REXX command environment program resides.
REXX command environment name. The command environment program that is active when the REXX CPP starts to run. The REXX interpreter calls this program to process commands encountered in the REXX procedure. The possible values are:
| *COMMAND | The IBM® i control language command environment is used. |
| *CPICOMM | The Common Programming Interface (CPI) for Communications command environment is used. CPICOMM is the command environment used for CL commands that are embedded within a REXX procedure. |
| program-name | The name of the program to process commands found in the REXX procedure. |
REXX exit code. A value which controls the conditions in which the REXX exit program is called. The possible values are:
| 2 | The exit program is called whenever an external function or subroutine has been called by the REXX program. The exit program is responsible for locating and calling the requested routine. |
| 3 | The exit program is called whenever the interpreter is going to call a command. The exit program is responsible for locating and calling the command. |
| 4 | The exit program is called whenever a REXX instruction or function attempts an operation on the REXX external data queue. |
| 5 | The exit program is called when session input or output operations are attempted. |
| 7 | The exit program is called after running each clause of the REXX procedure to determine whether it must be stopped. |
| 8 | The exit program is called after running each clause of the REXX program to check if tracing must be turned on or off. |
| 9 | The exit program is called before interpretation of the first instruction of a REXX procedure. |
| 10 | The exit program is called after interpretation of the last instruction of a REXX procedure. |
REXX exit program library name. The name of the library in which the REXX exit program resides.
REXX exit program name. The exit program used when the REXX interpreter is started under the conditions specified by the REXX exit code for this program.
REXX source file library name. The name of the library in which the REXX source file resides.
REXX source file member name. The name of the source file member that contains the REXX procedure that is the command processing program.
REXX source file name. The name of the source file that contains the REXX procedure that is the command processing program. The possible values are:
| QREXSRC | The IBM-supplied source file, QREXSRC, contains the source member that is used. |
| source-file-name | The name of the REXX source file that is used. |
Search index library name. The name of the library in which the help search index resides.
Search index name. The name of the search index for this command. The possible values are:
| *NONE | No help search index is specified. |
| search index name | The name of the help search index that is used. |
Source file library name. The name of the library in which the source file resides.
Source file member name. The name of the source file member that contains the command definition statements used to create the command.
Source file name. The name of the source file that contains the source file member used to create the command.
Text description. The user text, if any, used to briefly describe the command and its function.
Threadsafe indicator. Whether the command can be used safely in a multithreaded job. The possible values are:
| 0 | The command is not threadsafe and should not be used in a multithreaded job. The value for the multithreaded job action field defines the action to be taken by the command analyzer when the command is used in a multithreaded job. |
| 1 | The command is threadsafe and can be used safely in a multithreaded job. |
| 2 | The command is threadsafe under certain conditions. See the documentation for the command to determine the conditions under which the command can be used safely in a multithreaded job. |
Validity check program call state. The state the validity check program is called from. The possible values are:
| *S | The validity check program is called from the system state. |
| *U | The validity check program is called from the user state. |
Validity check program library name. The name of the library in which the validity check program resides.
Validity check program name. The name of a program that performs additional user-defined validity checking on the parameters in the command. If *NONE is returned, no separate user-defined validity checking is done for this command. All validity checking is done by the command analyzer and the command processing program.
Where allowed to run. The environments in which this command is allowed to run. The characters of this field are as follows, and they can have a value of 0 (does not apply) or 1 (does apply):
| 1 | Batch program (*BPGM) |
| 2 | Interactive program (*IPGM) |
| 3 | Can be run using QCMDEXC, QCAEXEC, or QCAPCMD (*EXEC) |
| 4 | Interactive job (*INTERACT) |
| 5 | Batch job (*BATCH) |
| 6 | Batch REXX procedure (*BREXX) |
| 7 | Interactive REXX procedure (*IREXX) |
| 8 | Batch ILE CL module (*BMOD) |
| 9 | Interactive ILE CL module (*IMOD) |
| 10-15 | Reserved |
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPD0196 E | Number of chained proxy commands exceeds &2. |
| CPF2150 E | Object information function failed. |
| CPF2151 E | Operation failed for &2 in &1 type *&3. |
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3C21 E | Format name &1 is not valid. |
| CPF3C24 E | Length of the receiver variable is not valid. |
| CPF3C3A E | Value for parameter &2 for API &1 not valid. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF6250 E | Cannot display or retrieve command &1 in library &2. |
| CPF8103 E | Command &4 in &9 damaged. |
| CPF8122 E | &8 damage on library &4. |
| CPF8123 E | Damage on object information for library &4. |
| CPF9801 E | Object &2 in library &3 not found. |
| CPF9802 E | Not authorized to object &2 in &3. |
| CPF9803 E | Cannot allocate object &2 in library &3. |
| CPF9807 E | One or more libraries in library list deleted. |
| CPF9808 E | Cannot allocate one or more libraries on library list. |
| CPF9810 E | Library &1 not found. |
| CPF9820 E | Not authorized to use library &1. |
| CPF9830 E | Cannot assign library &1. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
API introduced: V2R2
[ Back to top | Program and CL Command APIs | APIs by category ]