| 1 | Qualified command name | Input | Char(20) |
| 2 | Destination information | Input | Char(*) |
| 3 | Destination format name | Input | Char(8) |
| 4 | Receiver variable | Output | Char(*) |
| 5 | Receiver format name | Input | Char(8) |
| 6 | Error Code | I/O | Char(*) |
The Retrieve Command Definition (QCDRCMDD) API retrieves information from a CL command (*CMD) object and generates XML (Extensible Markup Language) source statements which describe the command. The generated command information XML source is called Command Definition Markup Language or CDML. The CDML source can be stored in either a receiver variable or a stream file, depending on the destination format name specified.
The CDML source is stored in UTF-8. UTF-8 (CCSID 1208) is a Unicode format which resembles ASCII, but allows the data to be stored compactly and shared easily between System i® products and any other system that supports the UTF-8 format.
The CDML elements and attributes closely resemble the command definition statements used to create CL commands:
See the Document Type Definition (DTD) in /QIBM/XML/DTD/QcdCLCmd.dtd for the definition of the CDML tag language returned by this API.
If the default value for an optional command parameter has been changed using the Change Command Default (CHGCMDDFT) command, the returned command information will reflect the default currently in effect rather than the default specified when the command was created.
Additional object-level information for a command (*CMD) object can be retrieved by using the QCDRCMDI (Retrieve Command Information) API.
The library-qualified command name for which to retrieve the command definition information. The first 10 characters contain the command name, while the second 10 characters identify the library name. The following special values are supported for the library name:
| *CURLIB | The job's current library |
| *LIBL | The library list |
Provides information about the destination for the generated CDML source. If DEST0100 is specified for the destination format name, this parameter contains a 4-byte integer which is the size of the receiver variable (parameter 4). If DEST0200 is specified for the destination format name, this parameter contains a structure which gives the path name of the stream file where the generated CDML source is to be stored.
The destination format to determine where the generated CDML source will be stored. Possible values are:
| DEST0100 | Return the CDML source in the receiver variable. |
| DEST0200 | Return the CDML source in a stream file using the path name coded in the destination information parameter. |
The variable that is to receive the generated CDML source. The variable is used only when the destination format name is DEST0100. If the receiver variable is not large enough to hold all of the generated CDML source, no CDML source is returned.
The format of the command definition information to be returned. You must use one of the following format names:
| CMDD0100 | CDML source is returned that describes the CL command information needed to build a valid command string for the command. |
| CMDD0200 | CDML source is returned that describes all of the command definition statements used to create the command. This is a superset of the information returned by receiver format CMDD0100. |
The structure in which to return error information. For the format of the structure, see Error code parameter.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Length of receiver variable |
Length of receiver variable. The length of the receiver variable. If the length is larger than the size of the receiver variable, the results may not be predictable. The minimum length is 8 bytes.
The destination information parameter (parameter 2) specifies the file path name where the generated CDML source is to be returned. See Path name format for information on specifying the output stream file path name.
The following information is returned for both CMDD0100 and CMDD0200 formats.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | CHAR(*) | Generated CDML source |
Bytes returned. The number of bytes of data returned.
Generated CDML source. The CDML source for the command. If the receiver variable is not large enough to hold the entire CDML source or if an unexpected error occurs while writing to the receiver variable, no data will be returned.
The output file path name is represented by the 'Path name' field in the 'Path Name Format' structure when using the DEST0200 destination format. The output file path name is used to store the generated CDML source. The output stream file is opened for writing only, in text-only mode, in CCSID 1208, and allows sharing with readers only. If the output stream file exists, the file is truncated to zero length before writing any data. If the output stream file already exists, it should have been created with a CCSID of 1208; otherwise, the resulting XML output may not be usable. If the output file does not exist, it will be created with a CCSID of 1208 before attempting to write the CDML source to it. The output file is created so that the file owner has read and write permission to it. The output file can be replaced if the user has the authority to do so. For more information on authority requirements for stream files, see the open()--Open File API.
If the CCSID of the command is 65535, the API uses the job default CCSID as the CCSID for the command.
| Message ID | Error Message Text |
|---|---|
| CPE3006 E | Input/output error. |
| CPE3014 E | The object name is not correct. |
| CPE3021 E | The value specified for the argument is not correct. |
| CPE3025 E | No such path or directory. |
| CPE3027 E | Operation not permitted. |
| CPE3029 E | Resource busy. |
| CPE3401 E | Permission denied. |
| CPE3403 E | Not a directory. |
| CPE3404 E | No space available. |
| CPE3406 E | Operation would have caused the process to be suspended. |
| CPE3407 E | Interrupted function call. |
| CPE3408 E | The address used for an argument was not correct. |
| CPE3436 E | There is not enough buffer space for the requested operation. |
| CPE3440 E | Operation not supported. |
| CPE3450 E | Descriptor not valid. |
| CPE3452 E | Too many open files for this process. |
| CPE3453 E | Too many open files in the system. |
| CPE3460 E | Storage allocation request failed. |
| CPE3470 E | Function not implemented. |
| CPE3471 E | Specified target is a directory. |
| CPE3474 E | Unknown system state. |
| CPE3484 E | A damaged object was encountered. |
| CPE3485 E | A loop exists in the symbolic links. |
| CPE3486 E | A path name is too long. |
| CPE3489 E | System resources not available to complete request. |
| CPE3490 E | Conversion error. |
| CPE3499 E | Object is suspended. |
| CPE3500 E | Object is a read only object. |
| CPE3507 E | Object too large. |
| CPE3511 E | File ID conversion of a directory failed. |
| CPE3512 E | A File ID could not be assigned when linking an object to directory. |
| CPE3513 E | File handle rejected by server. |
| CPE3524 E | Function not allowed. |
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3C19 E | Error occurred with receiver variable specified. |
| CPF3C21 E | Format name &1 is not valid. |
| CPF3C24 E | Length of the receiver variable is not valid. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3CF2 E | Error(s) occurred during running of &1 API. |
| 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. |
| 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. |
[ Back to top | Program and CL Command APIs | APIs by category ]