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/qusaddep.htm

769 lines
21 KiB
HTML
Raw Blame History

<!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>Add Exit Program (QUSADDEP, QusAddExitProgram) 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 -->
<!-- File cleanup completed Sept 2001 by v2cdijab -->
<!-- End Header Records -->
<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>Add Exit Program (QUSADDEP, QusAddExitProgram) 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%">Exit point 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">Exit point 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">3</td>
<td align="left" valign="top">Exit program number</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">4</td>
<td align="left" valign="top">Qualified exit program name</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(20)</td>
</tr>
<tr>
<td align="center" valign="top">5</td>
<td align="left" valign="top">Exit program data</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(*)</td>
</tr>
<tr>
<td align="center" valign="top">6</td>
<td align="left" valign="top">Length of exit program data</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">7</td>
<td align="left" valign="top">Exit program attributes</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(*)</td>
</tr>
<tr>
<td align="center" valign="top">8</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;Service Program Name: QUSRGFA1<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Default Public Authority: *EXCLUDE<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Threadsafe: Yes<br>
<!-- iddvc RMBR -->
<br>
</div>
<p>The Add Exit Program (OPM, QUSADDEP; ILE, QusAddExitProgram) API adds an
exit program entry to a specific exit point or replaces an existing exit
program. Each exit point can have a single entry, or multiple entries. The exit
program number indicates the sequence in which the exit programs should be run.
The exit point provider determines the maximum number of exit programs that are
allowed for the exit point. The API does not verify that the exit program
exists.</p>
<p>If the exit point to which the exit program is being added does not exist,
the registration facility creates the exit point and adds the exit program.
This exit point will be considered unregistered until it is explicitly
registered with the Register Exit Point API. The Add Exit Program, Remove Exit
Program, Retrieve Exit Information, and Deregister Exit Point APIs can be
performed against an unregistered exit point. This capability allows exit
programs to be added to an exit point that will be supported in the future but
is not currently registered with the registration facility.</p>
<p>This API provides support similar to the Add Exit Program (ADDEXITPGM)
command.</p>
<br>
<h3>Authorities and Locks</h3>
<dl>
<dt><em>API Public Authority</em></dt>
<dd>*EXCLUDE</dd>
<dt><em>Exit Registration Lock</em></dt>
<dd>*EXCL</dd>
</dl>
<br>
<h3>Required Parameter Group</h3>
<dl>
<dt><strong>Exit point name</strong></dt>
<dd>INPUT; CHAR(20)
<p>The exit point name to which the exit program is being added.</p>
</dd>
<dt><strong>Exit point format name</strong></dt>
<dd>INPUT; CHAR(8)
<p>The format name of the exit point to which the exit program is being
added.</p>
</dd>
<dt><strong>Exit program number</strong></dt>
<dd>INPUT; BINARY(4)
<p> The sequence in which the exit programs are to be run when multiple exit
point entries for a specific exit point are retrieved. The valid range is 1
through 2&nbsp;147&nbsp;483&nbsp;647 where the processing sequence is from the
lowest number to the highest number. Exit program numbers do not need to be
consecutive. The following special values are allowed:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>-1</em></td>
<td align="left" valign="top">The API assigns the next lowest available number
for that specific exit point.</td>
</tr>
<tr>
<td align="left" valign="top"><em>-2</em></td>
<td align="left" valign="top">The API assigns the highest available number for
that specific exit point.</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Qualified exit program name</strong></dt>
<dd>INPUT; CHAR(20)
<p> The exit program name and library that is being added. The first 10
characters contain the exit program name, and the second 10 characters contain
the library name in which the exit program resides. The exit program does not
need to exist when it is added to the exit point. A specific library name must
be specified. The special values *LIBL and *CURLIB are not supported.</p>
</dd>
<dt><strong>Exit program data</strong></dt>
<dd>INPUT; CHAR(*)
<p> The exit point provider describes what needs to be supplied for this
parameter. It is not an error to supply more information than the exit point
calls for. Pointer data will not be preserved, and the API does not perform any
validation of this parameter.</p>
</dd>
<dt><strong>Length of exit program data</strong></dt>
<dd>INPUT; BINARY(4)
<p> The length of the exit program data. The valid length is 0 through
2048.</p>
</dd>
<dt><strong>Exit program attributes</strong></dt>
<dd>INPUT; CHAR(*)
<p> The specified information for the exit program. Refer to <a href=
"#HDREPATT">Exit Program Attribute Keys</a> for more information. Any key not
specified will be given the default value. The information must be in the
following format:</p>
<dl>
<dt><em>Number of variable length records</em></dt>
<dd>BINARY(4)</dd>
<dd>Total number of all of the variable length records.</dd>
<dt><em>Variable length records</em></dt>
<dd>The exit program attributes and their values. Refer to <a href=
"#HDRFMTVAR1">Format for Variable Length Record</a> for the format of this
field.</dd>
</dl>
<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="HDRFMTVAR1">Format for Variable Length Record</a></h3>
<p>The following table shows the format for the variable length record. For a
detailed description of each field, see <a href="#HDRFDESC1">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%">Length of variable length record</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">Exit program attribute key</td>
</tr>
<tr>
<td align="center" valign="top">8</td>
<td align="center" valign="top">8</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Length of data</td>
</tr>
<tr>
<td align="center" valign="top">12</td>
<td align="center" valign="top">C</td>
<td align="left" valign="top">CHAR(*)</td>
<td align="left" valign="top">Data</td>
</tr>
</table>
<p>If the length of the data is longer than the key field's data length, the
data is truncated at the right. No message is issued.</p>
<p>If the length of the data is shorter than the key field's data length and
the key contains binary data, an error message is issued. If the key does not
contain binary data, the field is padded with blanks.</p>
<p>It is not an error to specify a key more than once. If duplicate keys are
specified, the last specified value for that key is used.</p>
<p>Each variable length record must be 4-byte aligned. If not, unpredictable
results may occur.</p>
<br>
<h3><a name="HDRFDESC1">Field Descriptions</a></h3>
<p><strong>Data.</strong> The value to which a specific exit program attribute
is to be set.</p>
<p><strong>Exit program attribute key.</strong> The exit program attribute to
be set. Refer to <a href="#HDREPATT">Exit Program Attribute Keys</a> for more
information.</p>
<p><strong>Length of data.</strong> The length of the exit program attribute
value.</p>
<p><strong>Length of variable length record.</strong> The length of the
record.</p>
<br>
<h3><a name="HDREPATT">Exit Program Attribute Keys</a></h3>
<p>The following table shows the valid exit program attribute keys for the key
field area of the variable length record. For a detailed description of each
field, see <a href="#HDRFDESC2">Field Descriptions</a>.</p>
<table border width="80%">
<tr>
<th align="center" valign="top">Key</th>
<th align="left" valign="top">Type</th>
<th align="left" valign="top">Field</th>
</tr>
<tr>
<td align="center" valign="top" width="10%">1</td>
<td align="left" valign="top" width="25%">CHAR(27)</td>
<td align="left" valign="top" width="65%">Qualified message file name and
message identifier for exit program description</td>
</tr>
<tr>
<td align="center" valign="top">2</td>
<td align="left" valign="top">CHAR(50)</td>
<td align="left" valign="top">Exit program text description</td>
</tr>
<tr>
<td align="center" valign="top">3</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Exit program data CCSID</td>
</tr>
<tr>
<td align="center" valign="top">4</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Replace</td>
</tr>
<tr>
<td align="center" valign="top">5</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Threadsafe</td>
</tr>
<tr>
<td align="center" valign="top">6</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Multithreaded job action</td>
</tr>
</table>
<br>
<br>
<h3><a name="HDRFDESC2">Field Descriptions</a></h3>
<p><strong>Exit program data CCSID.</strong> The coded character set identifier
(CCSID) used for working with the exit program data. The default value is
0.</p>
<table cellpadding="5">
<!-- cols="10 90" -->
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">Use the current job default CCSID.</td>
</tr>
<tr>
<td align="left" valign="top"><em>CCSID</em></td>
<td align="left" valign="top">A valid CCSID number. The valid CCSID range is 1
through 65&nbsp;535 but not 65&nbsp;534. The CCSID will be validated by the
API.</td>
</tr>
</table>
<p><strong>Exit program text description.</strong> The text for the exit
program description. When this key is specified, the qualified message file
name and message identifier for exit program description field must not be
specified. The default value is blanks.</p>
<p><strong>Multithreaded job action.</strong> The action to take in a
multithreaded job. This key has no direct relationship with the threadsafe key;
however, the value for the threadsafe key can be used to determine the
multithreaded job action. The default value is 0. Valid values for this key
are:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">Use the QMLTTHDACN system value to determine the
action to take.</td>
</tr>
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">Run the exit program in a multithreaded job.</td>
</tr>
<tr>
<td align="left" valign="top"><em>2</em></td>
<td align="left" valign="top">Run the exit program in a multithreaded job, but
send an informational message. CPI3C80 can be used as the informational
message.</td>
</tr>
<tr>
<td align="left" valign="top"><em>3</em></td>
<td align="left" valign="top">Do not run the exit program in a multithreaded
job. Depending on the exit point, do one of the following:
<ol>
<li>Send an escape message and do not call the exit program. CPF3C80 can be
used as the escape message.</li>
<li>Send an informational message and do not call the exit program. CPF3C80 can
be used as the informational message.</li>
<li>Call the exit program in a non-multithreaded job.</li>
</ol>
</td>
</tr>
</table>
<p>If you use the threadsafe value to determine the value for the multithreaded
job action, consider the following recommendations:</p>
<ol>
<li>If the threadsafe value is 0, the multithreaded job action should be set to
3.</li>
<li>If the threadsafe value is 1, the multithreaded job action should be set to
0.</li>
<li>If the threadsafe value is 2, the multithreaded job action should be set to
1.</li>
</ol>
<p><strong>Qualified message file name and message identifier for exit program
description.</strong> A message file and message identifier that contains the
exit program description. When this key is specified, the exit program text
description key must not be specified. The message file and message identifier
do not have to exist at the time the exit program is added. The default value
is blanks. Refer to <a href="#HDRMSGFIL2">Qualified Message File Format</a> for
more information.</p>
<p><strong>Replace.</strong> Whether to replace an existing exit program entry.
The combination of the exit program name and exit program number define an exit
program entry. The default value is 0. Valid values for this key are:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">Do not replace an existing exit program
entry.</td>
</tr>
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">Replace an existing exit program entry.</td>
</tr>
</table>
<p><strong>Threadsafe.</strong> Whether the exit program entry is threadsafe.
This key has no direct relationship with the multithreaded job action key. It
is intended for documentation purposes only. The default value is 1. Valid
values for this key are:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">The exit program entry is not threadsafe.</td>
</tr>
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">The threadsafe status of the exit program entry
is not known.</td>
</tr>
<tr>
<td align="left" valign="top"><em>2</em></td>
<td align="left" valign="top">The exit program entry is threadsafe.</td>
</tr>
</table>
<br>
<br>
<h3><a name="HDRMSGFIL2">Qualified Message File Format</a></h3>
<p>The following table shows the layout of the qualified message file name and
message identifier for exit program description field. For a detailed
description of each field, see <a href="#HDRFDESC3">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(10)</td>
<td align="left" valign="top" width="60%">Message file name</td>
</tr>
<tr>
<td align="center" valign="top">10</td>
<td align="center" valign="top">10</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">Message file library name</td>
</tr>
<tr>
<td align="center" valign="top">20</td>
<td align="center" valign="top">14</td>
<td align="left" valign="top">CHAR(7)</td>
<td align="left" valign="top">Message identifie</td>
</tr>
</table>
<br>
<br>
<h3><a name="HDRFDESC3">Field Descriptions</a></h3>
<p><strong>Message file library name.</strong> The library name in which the
message file resides. The special value *CURLIB is not supported. The possible
values are:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>*LIBL</em></td>
<td align="left" valign="top">Search the library list for the message file.
This value uses the first message file in the library list that contains the
message identifier.</td>
</tr>
<tr>
<td align="left" valign="top"><em>library name</em></td>
<td align="left" valign="top">The name of the message library the message file
resides in.</td>
</tr>
</table>
<p><strong>Message file name.</strong> The name of the message file that
contains the exit program text description.</p>
<p><strong>Message identifier.</strong> The message identifier for the
description.</p>
<br>
<h3>Error Messages</h3>
<table width="100%" cellpadding="5">
<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">CPF24B4 E</td>
<td width="85%" valign="top">Severe error while addressing parameter list.</td>
</tr>
<tr>
<td valign="top">CPF3C1E E</td>
<td valign="top">Required parameter &amp;1 omitted.</td>
</tr>
<tr>
<td valign="top">CPF3C36 E</td>
<td valign="top">Number of parameters, &amp;1, entered for this API was not
valid.</td>
</tr>
<tr>
<td valign="top">CPF3C4D E</td>
<td valign="top">Length &amp;1 for key &amp;2 not valid.</td>
</tr>
<tr>
<td valign="top">CPF3C81 E</td>
<td valign="top">Value for key &amp;1 not valid.</td>
</tr>
<tr>
<td valign="top">CPF3C82 E</td>
<td valign="top">Key &amp;1 not valid for API &amp;2.</td>
</tr>
<tr>
<td valign="top">CPF3C85 E</td>
<td valign="top">Value for key &amp;1 not allowed with value for key
&amp;2.</td>
</tr>
<tr>
<td valign="top">CPF3C90 E</td>
<td valign="top">Literal value cannot be changed.</td>
</tr>
<tr>
<td valign="top">CPF3CD2 E</td>
<td valign="top">Exit point name &amp;1 not valid.</td>
</tr>
<tr>
<td valign="top">CPF3CD3 E</td>
<td valign="top">Exit point format name &amp;1 not valid.</td>
</tr>
<tr>
<td valign="top">CPF3CD4 E</td>
<td valign="top">Maximum number of exit programs reached for exit point &amp;1
with format &amp;2.</td>
</tr>
<tr>
<td valign="top">CPF3CD6 E</td>
<td valign="top">Length of exit program data &amp;1 not valid.</td>
</tr>
<tr>
<td valign="top">CPF3CD9 E</td>
<td valign="top">Requested function cannot be performed at this time.</td>
</tr>
<tr>
<td valign="top">CPF3CDA E</td>
<td valign="top">Registration facility repository not available for use.</td>
</tr>
<tr>
<td valign="top">CPF3CDE E</td>
<td valign="top">Exit program name &amp;1 library &amp;2 not valid.</td>
</tr>
<tr>
<td valign="top">CPF3CDF E</td>
<td valign="top">Exit program number &amp;1 already assigned for exit point
&amp;2 with format &amp;3.</td>
</tr>
<tr>
<td valign="top">CPF3CE1 E</td>
<td valign="top">Exit program number &amp;1 not valid.</td>
</tr>
<tr>
<td valign="top">CPF3CE5 E</td>
<td valign="top">Exit point &amp;1 with format &amp;2 will not allow exit
program &amp;3 library &amp;4 to be added.</td>
</tr>
<tr>
<td valign="top">CPF3CF1 E</td>
<td valign="top">Error code parameter not valid.</td>
</tr>
<tr>
<td valign="top">CPF3CF2 E</td>
<td valign="top">Error(s) occurred during running of &amp;1 API.</td>
</tr>
<tr>
<td valign="top">CPF8100 E</td>
<td valign="top">All CPF81xx messages could be returned. xx is from 01 to
FF.</td>
</tr>
<tr>
<td valign="top">CPF9802 E</td>
<td valign="top">Not authorized to object &amp;2 in &amp;3.</td>
</tr>
<tr>
<td valign="top">CPF9810 E</td>
<td valign="top">Library &amp;1 not found.</td>
</tr>
<tr>
<td valign="top">CPF9811 E</td>
<td valign="top">Program &amp;1 in library &amp;2 not found.</td>
</tr>
<tr>
<td valign="top">CPF9820 E</td>
<td valign="top">Not authorized to use library &amp;1.</td>
</tr>
<tr>
<td valign="top">CPF9872 E</td>
<td valign="top">Program or service program &amp;1 in library &amp;2 ended.
Reason code &amp;3.</td>
</tr>
</table>
<br>
<hr>
API introduced: V3R1
<hr>
<center>
<table cellpadding="2" cellspacing="2">
<tr align="center">
<td valign="middle" align="center"><a href="#top_of_page">Top</a> | <a href=
"reg1.htm">Registration Facility APIs</a> | <a href="aplist.htm">APIs by
category</a></td>
</tr>
</table>
</center>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink