Retrieve Command Definition (QCDRCMDD) API

  Required Parameter Group:

  Default Public Authority: *USE

  Threadsafe: Yes

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.

Authorities and Locks

API Public Authority
Command Library Authority
Command Authority
Command Lock
Output File Authority (if output stored in a stream file)
Authority to the path and file are determined by the open() API. For details, see the Authorities section of the open()--Open File API for files opened with an access mode of O_WRONLY and O_TRUNC.
Output File Lock

Required Parameter Group

Qualified command name

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:

Destination information

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.

Destination format name

The destination format to determine where the generated CDML source will be stored. Possible values are:

Receiver variable

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.

Receiver format name

The format of the command definition information to be returned. You must use one of the following format names:

Error code
I/O; CHAR(*)

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

DEST0100 Format

The following information needs to be supplied in the destination information parameter (parameter 2) for the DEST0100 format.

Field Descriptions

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.

DEST0200 Format

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.

Output Information Format (for CMDD0100 and CMDD0200 formats)

The following information is returned for both CMDD0100 and CMDD0200 formats.

Field Descriptions

Bytes available. The number of bytes of data available to be returned. All available data is returned if enough space is provided.

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.

Usage Notes

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.

Error Messages

API introduced: V5R1

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