friedkiwi/ibm-information-center
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
8826eae394
ibm-information-center/dist/eclipse/plugins/i5OS.ic.apis_5.4.0.1/qcapcmd.htm

690 lines
22 KiB
HTML
Raw Normal View History

Add readme and dist folders
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>Process Commands (QCAPCMD) 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. -->
<!-- Change History: -->
<!-- YYMMDD USERID Change description -->
<!-- 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>Process Commands (QCAPCMD) 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%">Source command string</td>
<td align="left" valign="top" width="20%">Input</td>
<td align="left" valign="top" width="20%">Char(*)</td>
</tr>
<tr>
<td align="center" valign="top">2</td>
<td align="left" valign="top">Length of source command string</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">3</td>
<td align="left" valign="top">Options control block</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(*)</td>
</tr>
<tr>
<td align="center" valign="top">4</td>
<td align="left" valign="top">Options control block length</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">5</td>
<td align="left" valign="top">Options control block format</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">Changed command string</td>
<td align="left" valign="top">Output</td>
<td align="left" valign="top">Char(*)</td>
</tr>
<tr>
<td align="center" valign="top">7</td>
<td align="left" valign="top">Length available for changed command string</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">8</td>
<td align="left" valign="top">Length of changed command string available to
return</td>
<td align="left" valign="top">Output</td>
<td align="left" valign="top">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">9</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: *EXCLUDE<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Threadsafe: Yes. See <a href="#usage_notes">Usage Notes</a> for command
considerations.<br>
<!-- iddvc RMBR -->
<br>
</div>
<p>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.</p>
<p>You can use the QCAPCMD API to:</p>
<ul>
<li>Check the syntax of a command string prior to running it</li>
<li>Prompt the command and receive the changed command string</li>
<li>Run a command from an HLL</li>
</ul>
<br>
<h3>Authorities and Locks</h3>
<dl>
<dt><em>Command</em></dt>
<dd>*USE</dd>
<dt><em>Command library</em></dt>
<dd>*EXCLUDE</dd>
</dl>
<br>
<h3>Required Parameter Group</h3>
<dl>
<dt><strong>Source command string</strong></dt>
<dd>INPUT; CHAR(*)
<p>The command string to be prompted for or run.</p>
</dd>
<dt><strong>Length of source command string</strong></dt>
<dd>INPUT; BINARY(4)
<p>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.</p>
</dd>
<dt><strong>Options control block</strong></dt>
<dd>INPUT; CHAR(*)
<p>The options that control the handling of the command string. The layout of
this parameter is the <a href="#HDRCPOP1">CPOP0100 Format</a>.</p>
</dd>
<dt><strong>Options control block length</strong></dt>
<dd>INPUT; BINARY(4)
<p>The length of the options control block. A minimum length of 20 is required
for the CPOP0100 format.</p>
</dd>
<dt><strong>Options control block format</strong></dt>
<dd>INPUT; CHAR(8)
<p>The format of the options control block. CPOP0100 is the only valid value.
For more information, see <a href="#HDRCPOP1">CPOP0100 Format</a>.</p>
</dd>
<dt><strong>Changed command string</strong></dt>
<dd>OUTPUT; CHAR(*)
<p>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.</p>
</dd>
<dt><strong>Length available for changed command string</strong></dt>
<dd>INPUT; BINARY(4)
<p>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.</p>
</dd>
<dt><strong>Length of changed command string available to return</strong></dt>
<dd>OUTPUT; BINARY(4)
<p>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.</p>
</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="HDRCPOP1">CPOP0100 Format</a></h3>
<p>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 <a href=
"#HDRLONG">Field Descriptions</a>.</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%">Type of command processing</td>
</tr>
<tr>
<td align="center" valign="top">4</td>
<td align="center" valign="top">4</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">DBCS data handling</td>
</tr>
<tr>
<td align="center" valign="top">5</td>
<td align="center" valign="top">5</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Prompter action</td>
</tr>
<tr>
<td align="center" valign="top">6</td>
<td align="center" valign="top">6</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Command string syntax</td>
</tr>
<tr>
<td align="center" valign="top">7</td>
<td align="center" valign="top">7</td>
<td align="left" valign="top">CHAR(4)</td>
<td align="left" valign="top">Message retrieve key</td>
</tr>
<tr>
<td align="center" valign="top"><img src="v5r4adelta.gif" width="53"
height="9">11</td>
<td align="center" valign="top">4</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">CCSID of command string<img
src="v5r4adeltaend.gif" width="53" height="9"></td>
</tr>
<tr>
<td align="center" valign="top">15</td>
<td align="center" valign="top">B</td>
<td align="left" valign="top">CHAR(5)</td>
<td align="left" valign="top">Reserved</td>
</tr>
</table> <br>
<br>
<h3><a name="HDRLONG">Field Descriptions</a></h3>
<img src="v5r4adelta.gif" width="53" height="9">
<p><strong>CCSID of command string.</strong> CCSID of the command string.
The possible values are:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">Input is in the job CCSID.</td>
</tr>
<tr>
<td align="left" valign="top"><em>1208</em></td>
<td align="left" valign="top">The command string is in UTF8.</td>
</tr>
<tr>
<td align="left" valign="top"><em>1200</em></td>
<td align="left" valign="top">The command string is in UTF16.</td>
</tr>
</table><img src="v5r4adeltaend.gif" width="53" height="9">
<p><strong>Command string syntax.</strong> Whether command processing
should be done in i5/OS mode or System/38 mode. The possible values are:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">Use system syntax. The specification of
qualified objects is in the format library/object.</td>
</tr>
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">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.</td>
</tr>
</table>
<p><strong>DBCS data handling.</strong> 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:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">Ignore DBCS data.</td>
</tr>
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">Handle DBCS data.</td>
</tr>
</table>
<p><strong>Message retrieve key.</strong> 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.</p>
<p><strong>Prompter action.</strong> Indicates whether the prompter should be
called on a command string.</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">Never prompt the command. This will prevent a
command prompt even if selective prompting characters are present in the
command string.
<p><strong>Note:</strong> 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.</p>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">Always prompt the command. This forces a command
prompt even if selective prompting characters are not present in the command
string.</td>
</tr>
<tr>
<td align="left" valign="top"><em>2</em></td>
<td align="left" valign="top">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.</td>
</tr>
<tr>
<td align="left" valign="top"><em>3</em></td>
<td align="left" valign="top">Show help. Provides help display for the
command.</td>
</tr>
</table>
<p><strong>Reserved.</strong> This area must be set to hexadecimal zeros.</p>
<p><strong>Type of command processing.</strong> The type of command processing
to be performed by the system. The following processes can occur:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">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.</td>
</tr>
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">Command syntax check. The processing for this
type is the same as that performed by the QCMDCHK API.</td>
</tr>
<tr>
<td align="left" valign="top"><em>2</em></td>
<td align="left" valign="top">Command line running. This processing is like
that provided by the QCMDEXC API but with the following additions:
<ul>
<li>Limited user checking is performed.</li>
<li>Prompting for missing required parameters is performed.</li>
<li>If the System/36 environment is active and the commands are System/36
commands, the System/36 environment runs the commands.</li>
</ul>
<p>This type processes commands with entry codes of <samp>Job: I</samp> (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 <samp>
Job: B</samp>. Limited user checking and System/36 environment processing is
done while prompting options are ignored.</p>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>3</em></td>
<td align="left" valign="top">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.</td>
</tr>
<tr>
<td align="left" valign="top"><em>4</em></td>
<td align="left" valign="top">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 <samp>Pgm:
B</samp>, <samp>Pgm: I</samp>, or <samp>Pgm: B,I</samp>. They have values of
*BPGM or *IPGM on the ALLOW parameter of the CRTCMD or CHGCMD command.</td>
</tr>
<tr>
<td align="left" valign="top"><em>5</em></td>
<td align="left" valign="top">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.</td>
</tr>
<tr>
<td align="left" valign="top"><em>6</em></td>
<td align="left" valign="top">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.</td>
</tr>
<tr>
<td align="left" valign="top"><em>7</em></td>
<td align="left" valign="top">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.</td>
</tr>
<tr>
<td align="left" valign="top"><em>8</em></td>
<td align="left" valign="top">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.</td>
</tr>
<tr>
<td align="left" valign="top"><em>9</em></td>
<td align="left" valign="top">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 <samp>CLLE:
B</samp>, <samp>CLLE: I</samp>, or <samp>CLLE: B,I</samp>. They have values of
*IMOD or *BMOD on the ALLOW parameter of the CRTCMD or CHGCMD command.</td>
</tr>
<tr>
<td align="left" valign="top"><em>10</em></td>
<td align="left" valign="top">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:<br>
<br>
<ol>
<li>The exit program is not called</li>
<li>The exit program ends in error.</li>
<li>The exit program does not replace the command.</li>
</ol>
</td>
</tr>
</table>
<br>
<h3><a name="usage_notes">Usage Notes</a></h3>
<ol>
<li>
<p>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.</p>
</li>
<li>
<p>The prompt actions controlled by the prompter option field in the option
control block have the following considerations.</p>
<ul>
<li>
<p>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:</p>
<ul>
<li>
<p>Selective prompting is specified in the source command string parameter.</p>
</li>
<li>
<p>The job is running interactively.</p>
</li>
</ul>
</li>
<li>
<p>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:</p>
<ul>
<li>
<p>1 for the prompter option field</p>
</li>
<li>
<p>2 for the prompter option field with selective prompting characters in the
command string</p>
</li>
<li>
<p>3 for help</p>
</li>
</ul>
</li>
</ul>
</li>
<li>
<p>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.</p>
</li>
<li>
<p>The prompter option field in the options control block is ignored if 10 is
specified for the type of command processing field.</p>
</li>
<img src="v5r4adelta.gif" width="53" height="9">
<li>
<P>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.</P>
</li>
<li>
<p>Proxy commands will be resolved before the command exit points QIBM_QCA_CHG_COMMAND and QIBM_QCA_RTV_COMMAND are called.</P>
</li>
<img src="v5r4adeltaend.gif" width="53" height="9">
</ol>
<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">CPF0008 E</td>
<td width="85%" valign="top">Value in option control block not valid.</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">CPF3C1D E</td>
<td align="left" valign="top">Length specified in parameter &amp;1 not
valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C20 E</td>
<td align="left" valign="top">Error found by program &amp;1.</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">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>
<tr>
<td align="left" valign="top">xxxnnnn&nbsp;&nbsp;&nbsp;&nbsp;E</td>
<td align="left" valign="top">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.</td>
</tr>
</table>
<br>
<hr>
API introduced: V2R3
<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>
Reference in New Issue Copy Permalink