ibm-information-center/dist/eclipse/plugins/i5OS.ic.apis_5.4.0.1/qcdrcmdd.htm

677 lines
18 KiB
HTML
Raw Permalink Normal View History

2024-04-02 14:02:31 +00:00
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta name="Copyright" content="Copyright (c) 2006 by IBM Corporation">
<title>Retrieve Command Definition (QCDRCMDD) API</title>
<!-- Begin Header Records -->
<!-- All rights reserved. Licensed Materials Property of IBM -->
<!-- US Government Users Restricted Rights -->
<!-- Use, duplication or disclosure restricted by -->
<!-- GSA ADP Schedule Contract with IBM Corp. -->
<!-- QCDRCMDD SCRIPT A created by MBAILEY -->
<!-- RCHVMW2 on 7 Oct 1998 at 22:35:08 -->
<!-- Change History: -->
<!-- YYMMDD USERID Change description -->
<!--Edited by Kersten Nov 2001 -->
<!--End Header Records -->
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
</head>
<body>
<a name="Top_Of_Page"></a>
<!-- Java sync-link -->
<script type="text/javascript" language="Javascript" src="../rzahg/synch.js">
</script>
<h2>Retrieve Command Definition (QCDRCMDD) API</h2>
<div class="box" style="width: 80%;">
<br>
&nbsp;&nbsp;Required Parameter Group:<br>
<!-- iddvc RMBR -->
<br>
<table width="100%">
<tr>
<td align="center" valign="top" width="10%">1</td>
<td align="left" valign="top" width="50%">Qualified command name</td>
<td align="left" valign="top" width="20%">Input</td>
<td align="left" valign="top" width="20%">Char(20)</td>
</tr>
<tr>
<td align="center" valign="top">2</td>
<td align="left" valign="top">Destination information</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(*)</td>
</tr>
<tr>
<td align="center" valign="top">3</td>
<td align="left" valign="top">Destination format name</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(8)</td>
</tr>
<tr>
<td align="center" valign="top">4</td>
<td align="left" valign="top">Receiver variable</td>
<td align="left" valign="top">Output</td>
<td align="left" valign="top">Char(*)</td>
</tr>
<tr>
<td align="center" valign="top">5</td>
<td align="left" valign="top">Receiver format name</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(8)</td>
</tr>
<tr>
<td align="center" valign="top">6</td>
<td align="left" valign="top">Error Code</td>
<td align="left" valign="top">I/O</td>
<td align="left" valign="top">Char(*)</td>
</tr>
</table>
<br>
&nbsp;&nbsp;Default Public Authority: *USE<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Threadsafe: Yes<br>
<!-- iddvc RMBR -->
<br>
</div>
<p>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.</p>
<p>
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
iSeries systems and any other system which supports the UTF-8 format.</p>
<p>
The CDML elements and attributes closely resemble the
command definition statements used to create CL commands:
<ul>
<li>CMD (Command) statement</li>
<li>PARM (Parameter) statement</li>
<li>ELEM (Element) statement</li>
<li>QUAL (Qualifier) statement</li>
<li>DEP (Dependency) statement</li>
<li>PMTCTL (Prompt Control) statement</li>
</ul>
<p>
See the Document Type Definition (DTD) in
/QIBM/XML/DTD/QcdCLCmd.dtd for the definition of the CDML tag
language returned by this API.</p>
<p>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.</p>
<p>Additional object-level information for a command (*CMD) object
can be retrieved by using the QCDRCMDI (Retrieve Command Information) API.</p>
<br>
<h3>Authorities and Locks</h3>
<dl>
<dt><em>API Public Authority</em></dt>
<dd>*USE</dd>
<dt><em>Command Library Authority</em></dt>
<dd>*EXECUTE</dd>
<dt><em>Command Authority</em></dt>
<dd>*USE</dd>
<dt><em>Command Lock</em></dt>
<dd>*SHRNUP</dd>
<dt><em>Output File Authority (if output stored in a stream file)</em></dt>
<dd>Authority to the path and file are determined by the open() API. For
details, see the Authorities section of the <a href="open.htm">open()</a>--Open
File API for files opened with an access mode of O_WRONLY and O_TRUNC.</dd>
<dt><em>Output File Lock</em></dt>
<dd>*SHRNUP</dd>
</dl>
<br>
<h3>Required Parameter Group</h3>
<dl>
<dt><strong>Qualified command name</strong></dt>
<dd>INPUT; CHAR(20)
<p>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:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>*CURLIB</em></td>
<td align="left" valign="top">The job's current library</td>
</tr>
<tr>
<td align="left" valign="top"><em>*LIBL</em></td>
<td align="left" valign="top">The library list</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Destination information</strong></dt>
<dd>INPUT; CHAR(*)
<p>
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.
</p>
<br>
</dd>
<dt><strong>Destination format name</strong></dt>
<dd>INPUT; CHAR(8)
<p>The destination format to determine where the generated CDML source will be stored.
Possible values are:</p>
<table cellpadding="5">
<!-- cols="25 75" -->
<tr>
<td align="left" valign="top"><em><a href="#dest0100">DEST0100</a></em></td>
<td align="left" valign="top">Return the CDML source in the receiver
variable.</td>
</tr>
<tr>
<td align="left" valign="top"><em><a href="#dest0200">DEST0200</a></em></td>
<td align="left" valign="top">Return the CDML source in a stream file using the path name
coded in the destination information parameter.</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Receiver variable</strong></dt>
<dd>OUTPUT; CHAR(*)
<p>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.</p>
</dd>
<dt><strong>Receiver format name</strong></dt>
<dd>INPUT; CHAR(8)
<p>The format of the command definition information to be returned.
You must use one of the following format names:</p>
<table cellpadding="5">
<!-- cols="25 75" -->
<tr>
<td align="left" valign="top"><em><a href="#cmdd0100">CMDD0100</a></em></td>
<td align="left" valign="top">CDML source is returned that describes the CL
command information needed to build a valid command string for the command.</td>
</tr>
<tr>
<td align="left" valign="top"><em><a href="#cmdd0200">CMDD0200</a></em></td>
<td align="left" valign="top">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.
</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Error code</strong></dt>
<dd>I/O; CHAR(*)
<p>The structure in which to return error information. For the format of the
structure, see <a href="../apiref/error.htm#hdrerrcod">Error Code Parameter</a>.</p>
</dd>
</dl>
<br>
<h3><a name="dest0100">DEST0100 Format</a></h3>
The following information needs to be supplied in the destination information
parameter (parameter 2) for the DEST0100 format.
<table border width="80%">
<tr>
<th align="center" valign="bottom" colspan="2">Offset</th>
<th align="left" valign="bottom" rowspan="2">Type</th>
<th align="left" valign="bottom" rowspan="2">Field</th>
</tr>
<tr>
<th align="center" valign="bottom">Dec</th>
<th align="center" valign="bottom">Hex</th>
</tr>
<tr>
<td align="center" valign="top" width="10%">0</td>
<td align="center" valign="top" width="10%">0</td>
<td align="left" valign="top" width="20%">BINARY(4)</td>
<td align="left" valign="top" width="60%">Length of receiver variable</td>
</tr>
</table>
<br>
<br>
<h3>Field Descriptions</h3>
<p><strong>Length of receiver variable.</strong> 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.</p>
<br>
<h3><a name="dest0200">DEST0200 Format</a></h3>
<p>The destination information parameter (parameter 2) specifies the
file path name where the generated CDML source is to be returned.
See <a href="../apiref/pns.htm">Path name format</a> for information on specifying the
output stream file path name.</p>
<br>
<h3><a name="cmdd0100_cmdd0200">Output Information Format (for CMDD0100 and CMDD0200 formats)</a></h3>
<p>
The following information is returned for both CMDD0100 and CMDD0200 formats.
</p>
<table border width="80%">
<tr>
<th align="center" valign="bottom" colspan="2">Offset</th>
<th align="left" valign="bottom" rowspan="2">Type</th>
<th align="left" valign="bottom" rowspan="2">Field</th>
</tr>
<tr>
<th align="center" valign="bottom">Dec</th>
<th align="center" valign="bottom">Hex</th>
</tr>
<tr>
<td align="center" valign="top" width="10%">0</td>
<td align="center" valign="top" width="10%">0</td>
<td align="left" valign="top" width="20%">BINARY(4)</td>
<td align="left" valign="top" width="60%">Bytes returned</td>
</tr>
<tr>
<td align="center" valign="top">4</td>
<td align="center" valign="top">4</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Bytes available</td>
</tr>
<tr>
<td align="center" valign="top">8</td>
<td align="center" valign="top">8</td>
<td align="left" valign="top">CHAR(*)</td>
<td align="left" valign="top">Generated CDML source</td>
</tr>
</table>
<br>
<br>
<h3>Field Descriptions</h3>
<strong>Bytes available.</strong> The number of bytes of data available to be
returned. All available data is returned if enough space is provided.
<p><strong>Bytes returned.</strong> The number of bytes of data returned.</p>
<p><strong>Generated CDML source.</strong> 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.</p>
<br>
<h3>Usage Notes</h3>
<p>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 <a href="open.htm">open()</a>--Open
File API in the Integrated File System section of the i5/OS APIs in the
Information Center.</p>
<p>If the CCSID of the command is 65535, the API uses the job default CCSID as
the CCSID for the command.</p>
<br>
<h3>Error Messages</h3>
<table width="100%" cellpadding="5">
<!-- cols="15 85" -->
<tr>
<th align="left" valign="top">Message ID</th>
<th align="left" valign="top">Error Message Text</th>
</tr>
<tr>
<td width="15%" valign="top">CPE3006 E</td>
<td width="85%" valign="top">Input/output error.</td>
</tr>
<tr>
<td align="left" valign="top">CPE3014 E</td>
<td align="left" valign="top">The object name is not correct.</td>
</tr>
<tr>
<td align="left" valign="top">CPE3021 E</td>
<td align="left" valign="top">The value specified for the argument is not
correct.</td>
</tr>
<tr>
<td align="left" valign="top">CPE3025 E</td>
<td align="left" valign="top">No such path or directory.</td>
</tr>
<tr>
<td align="left" valign="top">CPE3027 E</td>
<td align="left" valign="top">Operation not permitted.</td>
</tr>
<tr>
<td align="left" valign="top">CPE3029 E</td>
<td align="left" valign="top">Resource busy.</td>
</tr>
<tr>
<td align="left" valign="top">CPE3401 E</td>
<td align="left" valign="top">Permission denied.</td>
</tr>
<tr>
<td align="left" valign="top">CPE3403 E</td>
<td align="left" valign="top">Not a directory.</td>
</tr>
<tr>
<td align="left" valign="top">CPE3404 E</td>
<td align="left" valign="top">No space available.</td>
</tr>
<tr>
<td align="left" valign="top">CPE3406 E</td>
<td align="left" valign="top">Operation would have caused the process to be
suspended.</td>
</tr>
<tr>
<td align="left" valign="top">CPE3407 E</td>
<td align="left" valign="top">Interrupted function call.</td>
</tr>
<tr>
<td align="left" valign="top">CPE3408 E</td>
<td align="left" valign="top">The address used for an argument was not
correct.</td>
</tr>
<tr>
<td align="left" valign="top">CPE3436 E</td>
<td align="left" valign="top">There is not enough buffer space for the
requested operation.</td>
</tr>
<tr>
<td align="left" valign="top">CPE3440 E</td>
<td align="left" valign="top">Operation not supported.</td>
</tr>
<tr>
<td align="left" valign="top">CPE3450 E</td>
<td align="left" valign="top">Descriptor not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPE3452 E</td>
<td align="left" valign="top">Too many open files for this process.</td>
</tr>
<tr>
<td align="left" valign="top">CPE3453 E</td>
<td align="left" valign="top">Too many open files in the system.</td>
</tr>
<tr>
<td align="left" valign="top">CPE3460 E</td>
<td align="left" valign="top">Storage allocation request failed.</td>
</tr>
<tr>
<td align="left" valign="top">CPE3470 E</td>
<td align="left" valign="top">Function not implemented.</td>
</tr>
<tr>
<td align="left" valign="top">CPE3471 E</td>
<td align="left" valign="top">Specified target is a directory.</td>
</tr>
<tr>
<td align="left" valign="top">CPE3474 E</td>
<td align="left" valign="top">Unknown system state.</td>
</tr>
<tr>
<td align="left" valign="top">CPE3484 E</td>
<td align="left" valign="top">A damaged object was encountered.</td>
</tr>
<tr>
<td align="left" valign="top">CPE3485 E</td>
<td align="left" valign="top">A loop exists in the symbolic links.</td>
</tr>
<tr>
<td align="left" valign="top">CPE3486 E</td>
<td align="left" valign="top">A path name is too long.</td>
</tr>
<tr>
<td align="left" valign="top">CPE3489 E</td>
<td align="left" valign="top">System resources not available to complete
request.</td>
</tr>
<tr>
<td align="left" valign="top">CPE3490 E</td>
<td align="left" valign="top">Conversion error.</td>
</tr>
<tr>
<td align="left" valign="top">CPE3499 E</td>
<td align="left" valign="top">Object is suspended.</td>
</tr>
<tr>
<td align="left" valign="top">CPE3500 E</td>
<td align="left" valign="top">Object is a read only object.</td>
</tr>
<tr>
<td align="left" valign="top">CPE3507 E</td>
<td align="left" valign="top">Object too large.</td>
</tr>
<tr>
<td align="left" valign="top">CPE3511 E</td>
<td align="left" valign="top">File ID conversion of a directory failed.</td>
</tr>
<tr>
<td align="left" valign="top">CPE3512 E</td>
<td align="left" valign="top">A File ID could not be assigned when linking an
object to directory.</td>
</tr>
<tr>
<td align="left" valign="top">CPE3513 E</td>
<td align="left" valign="top">File handle rejected by server.</td>
</tr>
<tr>
<td align="left" valign="top">CPE3524 E</td>
<td align="left" valign="top">Function not allowed.</td>
</tr>
<tr>
<td align="left" valign="top">CPF24B4 E</td>
<td align="left" valign="top">Severe error while addressing parameter
list.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C19 E</td>
<td align="left" valign="top">Error occurred with receiver variable
specified.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C21 E</td>
<td align="left" valign="top">Format name &amp;1 is not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C24 E</td>
<td align="left" valign="top">Length of the receiver variable is not
valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C90 E</td>
<td align="left" valign="top">Literal value cannot be changed.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3CF1 E</td>
<td align="left" valign="top">Error code parameter not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3CF2 E</td>
<td align="left" valign="top">Error(s) occurred during running of &amp;1
API.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9801 E</td>
<td align="left" valign="top">Object &amp;2 in library &amp;3 not found.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9802 E</td>
<td align="left" valign="top">Not authorized to object &amp;2 in &amp;3.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9803 E</td>
<td align="left" valign="top">Cannot allocate object &amp;2 in library
&amp;3.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9810 E</td>
<td align="left" valign="top">Library &amp;1 not found.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9820 E</td>
<td align="left" valign="top">Not authorized to use library &amp;1.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9830 E</td>
<td align="left" valign="top">Cannot assign library &amp;1.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9872 E</td>
<td align="left" valign="top">Program or service program &amp;1 in library
&amp;2 ended. Reason code &amp;3.</td>
</tr>
</table>
<br>
<hr>
API introduced: V5R1
<hr>
<center>
<table cellpadding="2" cellspacing="2">
<tr align="center">
<td valign="middle" align="center"><a href="#Top_Of_Page">Top</a> | <a href=
"pgm1.htm">Program and CL Command APIs</a> | <a href="aplist.htm">APIs by
category</a></td>
</tr>
</table>
</center>
</body>
</html>