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

475 lines
14 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>Command Analyzer Retrieve Exit Program</title>
<!-- 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. -->
<!-- Begin Header Records ========================================== -->
<!-- XCARTV45 SCRIPT A converted by B2H R4.1 (346) (CMS) by V2DCIJB -->
<!-- at RCHVMW2 on 28 Sep 1999 at 15:13:31 -->
<!--End Header Records -->
<!--Edited by Kersten Nov 2001 -->
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
</head>
<body>
<!-- Java sync-link -->
<script type="text/javascript" language="Javascript" src="../rzahg/synch.js">
</script>
<a name="Top_Of_Page"></a>
<h2>Command Analyzer Retrieve Exit Program</h2>
<div class="box" style="width: 70%;">
<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%">Retrieve command exit
information</td>
<td align="left" valign="top" width="20%">Input</td>
<td align="left" valign="top" width="20%">Char(*)</td>
</tr>
</table>
<br>
&nbsp;&nbsp;QSYSINC Member Name: ECARTCMD<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Exit Point Name: QIBM_QCA_RTV_COMMAND<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Exit Point Format Name: RTVC0100<br>
<!-- iddvc RMBR -->
<br>
</div>
<p>The Command Analyzer Retrieve exit program is called when the command for
which it is registered is processed. This program is called by the command
analyzer through the registration facility immediately before transferring
control to the command processing program. Exit programs will not be called if
the command analyzer was called to syntax-check the command without running it.
The exit point supports a maximum of ten retrieve command exit programs for
each command.</p>
<p>If the exit program sends any escape messages to the command analyzer, the
message will be left in the job log and ignored by the command analyzer.</p>
<p>Exit programs may not be registered for the following system commands:</p>
<ul>
<li>CALLPRC</li>
<li>
<img src="delta.gif" alt="Start of change">
CALLSUBR
<img src="deltaend.gif" alt="End of change">
</li>
<li>CHGVAR</li>
<li>CNLRCV</li>
<li>COPYRIGHT</li>
<li>DCL</li>
<li>DCLF</li>
<li>DO</li>
<li>DOFOR</li>
<li>DOUNTIL</li>
<li>DOWHILE</li>
<li>ENDDO</li>
<li>ENDPGM</li>
<li>ENDRCV</li>
<li>ENDSELECT</li>
<li>
<img src="delta.gif" alt="Start of change">
ENDSUBR
<img src="deltaend.gif" alt="End of change">
</li>
<li>GOTO</li>
<li>IF</li>
<li>ITERATE</li>
<li>LEAVE</li>
<li>MONMSG</li>
<li>OTHERWISE</li>
<li>PGM</li>
<li>RCVF</li>
<li>RETURN</li>
<li>
<img src="delta.gif" alt="Start of change">
RTNSUBR
<img src="deltaend.gif" alt="End of change">
</li>
<li>SELECT</li>
<li>SNDF</li>
<li>SNDRCVF</li>
<li>
<img src="delta.gif" alt="Start of change">
SUBR
<img src="deltaend.gif" alt="End of change">
</li>
<li>TFRCTL</li>
<li>WAIT</li>
<li>WHEN</li>
</ul>
<p>In addition, exit programs may not be registered for these commands:</p>
<ul>
<li>CALL command</li>
<li>Commands that are restricted to use by the CL compiler when compiling for a
previous release.</li>
<li>Commands in libraries QSYS38 and QUSER38.</li>
</ul>
<p>If the exit program uses the registered CL command, a recursive loop may
occur. Recursive loops also may occur if two or more exit programs use each
other's CL commands. For example, if the exit program for CMDA uses CMDB and
the exit program for CMDB uses CMDA, a recursive loop will occur.</p>
<br>
<h3>Authorities and Locks</h3>
<p>You must have *ALLOBJ and *SECADM special authorities to register an exit
program for the QIBM_QCA_RTV_COMMAND exit point.</p>
<br>
<h3>Required Parameter Group</h3>
<dl>
<dt><strong>Retrieve command exit information</strong></dt>
<dd>INPUT; CHAR(*)
<p>Information about the command that the command analyzer was called to
process.</p>
</dd>
</dl>
<br>
<h3><a name="HDRCARXIN">RTVC0100 Format</a></h3>
<p>The following table shows the format of the information supplied to a
retrieve command exit program. For a description of the fields in this format,
see <a href="#HDRCARXFD">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%">CHAR(20)</td>
<td align="left" valign="top" width="60%">Exit point name</td>
</tr>
<tr>
<td align="center" valign="top">20</td>
<td align="center" valign="top">14</td>
<td align="left" valign="top">CHAR(8)</td>
<td align="left" valign="top">Exit point format name</td>
</tr>
<tr>
<td align="center" valign="top">28</td>
<td align="center" valign="top">1C</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">Command name</td>
</tr>
<tr>
<td align="center" valign="top">38</td>
<td align="center" valign="top">26</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">Library name</td>
</tr>
<tr>
<td align="center" valign="top">48</td>
<td align="center" valign="top">30</td>
<td align="left" valign="top">CHAR(4)</td>
<td align="left" valign="top">Reserved</td>
</tr>
<tr>
<td align="center" valign="top">52</td>
<td align="center" valign="top">34</td>
<td align="left" valign="top">BIN(4)</td>
<td align="left" valign="top">Offset to original command string</td>
</tr>
<tr>
<td align="center" valign="top">56</td>
<td align="center" valign="top">38</td>
<td align="left" valign="top">BIN(4)</td>
<td align="left" valign="top">Length of original command string</td>
</tr>
<tr>
<td align="center" valign="top">60</td>
<td align="center" valign="top">3C</td>
<td align="left" valign="top">BIN(4)</td>
<td align="left" valign="top">Offset to replacement command string</td>
</tr>
<tr>
<td align="center" valign="top">64</td>
<td align="center" valign="top">40</td>
<td align="left" valign="top">BIN(4)</td>
<td align="left" valign="top">Length of replacement command string</td>
</tr>
<tr>
<td align="center" valign="top">
<img src="delta.gif" alt="Start of change">
68</td>
<td align="center" valign="top">44</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Offset to proxy chain
<img src="deltaend.gif" alt="End of change">
</td>
</tr>
<tr>
<td align="center" valign="top">
<img src="delta.gif" alt="Start of change">
72</td>
<td align="center" valign="top">48</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Number of entries in proxy chain
<img src="deltaend.gif" alt="End of change">
</td>
</tr>
<tr>
<td align="center" valign="top">&nbsp;</td>
<td align="center" valign="top">&nbsp;</td>
<td align="left" valign="top">CHAR(*)</td>
<td align="left" valign="top">Original command string</td>
</tr>
<tr>
<td align="center" valign="top">&nbsp;</td>
<td align="center" valign="top">&nbsp;</td>
<td align="left" valign="top">CHAR(*)</td>
<td align="left" valign="top">Replacement command string</td>
</tr>
<tr>
<td align="center" valign="bottom" rowspan="2" colspan="2">
<img src="delta.gif" alt="Start of change">
Proxy commands and libraries. These fields repeat in the order listed.</td>
<td align="left" valign="bottom">CHAR(10)</td>
<td align="left" valign="bottom">Proxy command name</td>
</tr>
<tr>
<td align="left" valign="bottom">CHAR(10)</td>
<td align="left" valign="bottom">Proxy command library name<img src="deltaend.gif" alt="End of change"></td>
</tr>
</table>
<br>
<br>
<h3><a name="HDRCARXFD">Field Descriptions</a></h3>
<p><strong>Command name.</strong> The name of the command that is being
processed.</p>
<p><strong>Exit point format name.</strong> The format name for the Retrieve
Command exit program. The possible format name is:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>RTVC0100</em></td>
<td align="left" valign="top">The format name that is used to supply the exit
information.</td>
</tr>
</table>
<p><strong>Exit point name.</strong> The name of the exit point that calls the
exit program (QIBM_QCA_RTV_COMMAND).</p>
<p><strong>Length of original command string.</strong> The length of the
original command string being processed.</p>
<p><strong>Length of replacement command string.</strong> The length of the
replacement command string from the user exit program that was called at exit
point QIBM_QCA_CHG_COMMAND. This will be 0 if there is no exit program for exit
point QIBM_QCA_CHG_COMMAND or if the exit program did not change the
command.</p>
<p><strong>Library name.</strong> The name of the library of the command being
processed.</p>
<p>
<img src="delta.gif" alt="Start of change">
<strong>Number of entries in proxy chain.</strong> The number of proxy commands chained to
this command.
<img src="deltaend.gif" alt="End of change">
</p>
<p><strong>Offset to original command string.</strong> The offset to the
beginning of the original command string.</p>
<p>
<img src="delta.gif" alt="Start of change">
<strong>Offset to proxy chain.</strong> The offset to the beginning of
the proxy chain information.
<img src="deltaend.gif" alt="End of change">
</p>
<p><strong>Offset to replacement command string.</strong> The offset to the
beginning of the replacement command string. This will be 0 if there is no exit
program for exit point QIBM_QCA_CHG_COMMAND or if the exit program did not
change the command.</p>
<p><strong>Original command string.</strong> The command string that was
originally submitted to the command analyzer for processing. The command name
will be library qualified and the parameter values will be enclosed in
parentheses and preceded by the keyword names. Any parameter that has
DSPINPUT(*NO) or DSPINPUT(*PROMPT) will be formatted without the parameter
value (for example, "PASSWORD()") to prevent exit programs from getting
passwords and similar secure data. If the original command string was replaced
by an exit program called at the QIBM_QCA_CHG_COMMAND exit point, this may not
be syntactically correct because required parameters may be missing,
interparameter checks have not been done, and the validity checking program has
not been called.</p>
<p><strong>Replacement command string.</strong> The replacement command string
from the user exit program that was called at exit point QIBM_QCA_CHG_COMMAND.
The command name will be library qualified and the parameter values will be
enclosed in parentheses and preceded by the keyword names.</p>
<p><strong>Reserved.</strong> Reserved area.</p>
<br>
<h3>Usage Notes</h3>
<h4>Registration considerations.</h4>
<p>Use the Add Exit Program command (ADDEXITPGM) or the Add Exit Program (OPM,
QUSADDEP; ILE, QusAddExitProgram) API to register an exit program for a
command. You must specify 20 bytes of exit program data. The first 10
characters specify the command name; the second 10 characters specify the
library name. Any exit programs registered for commands in QSYS also will be
called for commands in the secondary language libraries. For example, if an
exit program is registered for the DSPJOB command in library QSYS, it will also
be called for the DSPJOB command in library QSYS2962.</p>
<p>If you rename the command or the library or move the command to another
library, you must have an exit program registered for the new command and
library names.</p>
<p>Any exit program registered for this exit point must be threadsafe if it
will be called in a job that has multiple threads.</p>
<p>This exit point is a command analyzer exit point that is called during the
processing of individual commands. This does not imply that command usage by
the system or by individual applications will not change or even be eliminated
in the future. For example, if some system function, X, uses the CRTLIB CL
command, you should not assume that X will always use the CRTLIB command. X's
use of CL commands may change without any warning to use an API or some other
interface. Therefore, you should not create any dependencies based on the
assumption that a specific function is implemented using a CL command.</p>
<br>
<h4>Runtime considerations.</h4>
<p>If a command is qualified with special value *SYSTEM, only library QSYS will
be searched for the command.</p>
<p>If a command is qualified with special value *NLVLIBL, only the national
language version (NLV) libraries in the library list and QSYS will be searched
for the command.</p>
<p>Adopted authority from previous call levels will be used to determine
authority to the exit program, but will not be propagated to the exit program.
The exit program will have all of the authorities available to the user profile
under which the job is currently running; this may be a profile which has been
swapped to, rather than the user profile under which a job was started.</p>
<p>All users with at least *USE authority to the command should also have
*OBJOPR and *EXECUTE authority to the exit program and *EXECUTE authority to
the exit program's library. The command will fail if the user does not have
sufficient authority to the exit program.</p>
<hr>
Exit program introduced: V4R5
<hr>
<table align="center" 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>
</body>
</html>
Reference in New Issue Copy Permalink