602 lines
19 KiB
HTML
602 lines
19 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 Change 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 ========================================== -->
|
|
<!-- XCACHG45 SCRIPT A converted by B2H R4.1 (346) (CMS) by V2DCIJB -->
|
|
<!-- at RCHVMW2 on 28 Sep 1999 at 15:14:17 -->
|
|
<!--File Edited by Kersten Nov 2001 -->
|
|
<!--End Header Records -->
|
|
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
|
|
</head>
|
|
<body>
|
|
|
|
<!-- Java sync-link -->
|
|
<script language="Javascript" src="../rzahg/synch.js" type="text/javascript">
|
|
</script>
|
|
|
|
<a name="Top_Of_Page"></a>
|
|
|
|
<h2>Command Analyzer Change 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%">Change command exit information</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">Replacement command</td>
|
|
<td align="left" valign="top">Output</td>
|
|
<td align="left" valign="top">Char(*)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">3</td>
|
|
<td align="left" valign="top">Length of replacement command string</td>
|
|
<td align="left" valign="top">Output</td>
|
|
<td align="left" valign="top">Binary(4)</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
QSYSINC Member Name: ECACHCMD<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
Exit Point Name: QIBM_QCA_CHG_COMMAND<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
Exit Point Format Name: CHGC0100<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
</div>
|
|
|
|
<p>The Command Analyzer Change exit program is called when the command for
|
|
which it is registered is processed. The command analyzer calls the Change
|
|
Command exit program for a command once through the registration facility
|
|
before performing any of the following steps:</p>
|
|
|
|
<ul>
|
|
<li>Prompting the command,</li>
|
|
|
|
<li>Performing interparameter checks,</li>
|
|
|
|
<li>Calling the validity checking program, and</li>
|
|
|
|
<li>Transferring control to the command processing program.</li>
|
|
</ul>
|
|
|
|
<p>The exit program is not called if the command analyzer was called to syntax
|
|
check the command, but not run it. The exit point supports one change command
|
|
exit program for each command.</p>
|
|
|
|
<a name="SPTCACXNOCH"></a>
|
|
|
|
<p>The exit program is called, but the command cannot be changed if any of the
|
|
following occur:</p>
|
|
|
|
<ul>
|
|
<li>The command was qualified with a specific library name.</li>
|
|
|
|
<li>The command has a parameter defined as RTNVAL(*YES), which allows the
|
|
command processing program (CPP) to return a value to the calling program.</li>
|
|
|
|
<li>The command has a parameter defined as either DSPINPUT(*NO) or
|
|
DSPINPUT(*PROMPT), which does not allow the value to be shown in the
|
|
prompt display or joblog.</li>
|
|
|
|
<li>The command was used in a program running in system state.</li>
|
|
</ul>
|
|
|
|
<p>If changing the command is allowed, the exit program can change the command
|
|
string so that the command analyzer processes a command from a different
|
|
library or a completely different command. It also can change any or all of the
|
|
parameters specified on the command. When a changed command string is returned
|
|
to the command analyzer, the command analyzer will not prompt the replaced
|
|
command or call the validity checking program, any exit programs registered for
|
|
the QIBM_QCA_RTV_COMMAND exit point, or the command processing program for the
|
|
replaced command. The command analyzer will start over with the changed command
|
|
instead of the original one. It will do a full validation of the new command,
|
|
including prompting if prompting was requested for the replaced command. If the
|
|
changed command string specifies a different command in a different library and
|
|
there is an exit program registered for the QIBM_QCA_CHG_COMMAND exit point for
|
|
the new command, it will be called, but it will not be allowed to change the
|
|
command. Exit programs registered for the QIBM_QCA_RTV_COMMAND exit point for
|
|
the new command will be called. If the command is not changed, the command
|
|
analyzer will continue with normal processing of the original command,
|
|
including calling any exit programs registered for the QIBM_CA_RTV_COMMAND exit
|
|
point.</p>
|
|
|
|
<p>The replaced command string will be logged to the job log only when the
|
|
original command was logged. For commands entered on a command line, the
|
|
original command will be logged as a request message, and the substitute will
|
|
be logged as a command message. This will allow users to retrieve their
|
|
original command with the Retrieve function key.</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. The
|
|
command analyzer will continue processing the original command.</p>
|
|
|
|
<p><a name="SPTCACXLST"></a> 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 may also 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_CHG_COMMAND exit point.</p>
|
|
|
|
<br>
|
|
|
|
|
|
<h3>Required Parameter Group</h3>
|
|
|
|
<dl>
|
|
<dt><strong>Change command exit information</strong></dt>
|
|
|
|
<dd>INPUT; CHAR(*)
|
|
|
|
<p>Information about the command that the command analyzer was called to
|
|
process.</p>
|
|
</dd>
|
|
|
|
<dt><strong>Replacement command</strong></dt>
|
|
|
|
<dd>OUTPUT; CHAR(*)
|
|
|
|
<p>A string containing the command string that is to be substituted for the one
|
|
the command analyzer was called to process. This will be ignored if the command
|
|
is not allowed to be changed. The maximum length of the changed command string
|
|
is 32000 bytes.</p>
|
|
|
|
<p>Commands that should not be specified as the replacement command by an exit
|
|
program include:</p>
|
|
|
|
<ul>
|
|
<li>System commands that are used only in CL programs. See the list of <a href=
|
|
"#SPTCACXLST">system commands</a>.</li>
|
|
|
|
<li>Commands that have a parameter that is used as a return value
|
|
(RTNVAL(*YES)).</li>
|
|
|
|
<li>Commands that are restricted to use by the CL compiler when compiling for a
|
|
previous release.</li>
|
|
</ul>
|
|
|
|
<p>If any of these commands are used as replacement commands, the command
|
|
analyzer will send a diagnostic message, followed by escape message CPF0001,
|
|
and processing of the command will end.</p>
|
|
</dd>
|
|
|
|
<dt><strong>Length of replacement command string</strong></dt>
|
|
|
|
<dd>OUTPUT; BINARY(4)
|
|
|
|
<p>The length of the replacement command string (0 - 32000) in bytes. If the
|
|
length is 0, the original command string will be run, and the replacement
|
|
command will be ignored.</p>
|
|
</dd>
|
|
</dl>
|
|
|
|
<br>
|
|
|
|
|
|
<h3><a name="HDRCACXIN">CHGC0100 Format</a></h3>
|
|
|
|
The following table shows the format of the information supplied to a change
|
|
command exit program. For a description of the fields in this format, see <a
|
|
href="#HDRCACXFD">Field Descriptions</a>.
|
|
|
|
<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(1)</td>
|
|
<td align="left" valign="top">Change allowed indicator</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">49</td>
|
|
<td align="center" valign="top">31</td>
|
|
<td align="left" valign="top">CHAR(1)</td>
|
|
<td align="left" valign="top">Prompt indicator</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">50</td>
|
|
<td align="center" valign="top">32</td>
|
|
<td align="left" valign="top">CHAR(2)</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">BINARY(4)</td>
|
|
<td align="left" valign="top">Offset to command string</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">56</td>
|
|
<td align="center" valign="top">38</td>
|
|
<td align="left" valign="top">BINARY(4)</td>
|
|
<td align="left" valign="top">Length of command string</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top"><img src="delta.gif" alt="Start of change">60</td>
|
|
<td align="center" valign="top">3C</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">64</td>
|
|
<td align="center" valign="top">41</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">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<img src="deltaend.gif" alt="End of change"></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="HDRCACXFD">Field Descriptions</a></h3>
|
|
|
|
<strong>Change allowed indicator.</strong> Whether or not the exit program is
|
|
allowed to change the command string that will be run. See the conditions where
|
|
<a href="#SPTCACXNOCH">change is not allowed</a>. Possible values are:<br>
|
|
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="5 95" -->
|
|
<tr>
|
|
<td align="left" valign="top"><em>1</em></td>
|
|
<td align="left" valign="top">The command may be changed.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>0</em></td>
|
|
<td align="left" valign="top">The command may not be changed.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p>If a replacement command is returned to the command analyzer, it will be
|
|
ignored.</p>
|
|
|
|
<p><strong>Command name.</strong> The name of the command that is being
|
|
processed.</p>
|
|
|
|
<p><strong>Command string.</strong> The command string that the command
|
|
analyzer is 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 was defined as DSPINPUT(*NO) or DSPINPUT(*PROMPT)
|
|
when the command was created will be formatted without the parameter value (for
|
|
example, "PASSWORD()") to prevent the exit programs from getting passwords and
|
|
similar secure data. This command string may not be correct syntactically
|
|
because required parameters may be missing, interparameter checking has not
|
|
been done, and the validity checking program for the command has not been
|
|
called.</p>
|
|
|
|
<p><strong>Exit point name.</strong> The name of the exit point that calls the
|
|
exit program.</p>
|
|
|
|
<p><strong>Exit point format name.</strong> The format name for the Change
|
|
Command exit program. The possible format name is:</p>
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="15 85" -->
|
|
<tr>
|
|
<td align="left" valign="top"><em>CHGC0100</em></td>
|
|
<td align="left" valign="top">The format name that is used to supply the exit
|
|
information.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><strong>Length of command string.</strong> The length of the command string
|
|
being processed.</p>
|
|
|
|
<p><strong>Library name.</strong> The name of the library for 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 command string.</strong> The offset to the beginning of
|
|
the 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>Prompt indicator.</strong> Whether prompting was requested on the
|
|
original command string. 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">Prompting was not requested for the original
|
|
command.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>1</em></td>
|
|
<td align="left" valign="top">Prompting was requested for the original
|
|
command.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><strong>Proxy command name.</strong> Name of the proxy command.</p>
|
|
|
|
<p><strong>Proxy command library name.</strong> Name of the proxy command library.</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 API (QUSADDEP,
|
|
QusAddExitProgram) 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.</p>
|
|
|
|
<p>Any exit programs registered for commands in library 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 also must have an exit program registered using the new command
|
|
and library names.</p>
|
|
|
|
<p>Only one exit program can be registered for each command for the
|
|
QIBM_QCA_CHG_COMMAND exit point. If two applications on the same system,
|
|
however, need to replace the same command, they can do it by registering a
|
|
single exit program, which replaces the command with one that is qualified with
|
|
*LIBL instead of replacing it with their own specific commands. The QCARPLCM
|
|
program in library QSYS may be used to do this. Applications using QCARPLCM
|
|
must ensure that their application library is at the beginning of the system
|
|
part of the library list.</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>
|
|
|
|
<br>
|
|
|
|
|
|
<h4>Runtime considerations.</h4>
|
|
|
|
<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>
|
|
|
|
<p>If a command is qualified with special value *SYSTEM, only library QSYS will
|
|
be searched for the command. The change exit program will be allowed to change
|
|
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. The change exit program will be allowed to change 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 also should 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>
|
|
|