475 lines
14 KiB
HTML
475 lines
14 KiB
HTML
<!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>
|
|
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>
|
|
QSYSINC Member Name: ECARTCMD<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
Exit Point Name: QIBM_QCA_RTV_COMMAND<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
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"> </td>
|
|
<td align="center" valign="top"> </td>
|
|
<td align="left" valign="top">CHAR(*)</td>
|
|
<td align="left" valign="top">Original command string</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top"> </td>
|
|
<td align="center" valign="top"> </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>
|
|
|