ibm-information-center/dist/eclipse/plugins/i5OS.ic.cl_5.4.0.1/addrpyle.htm

352 lines
18 KiB
HTML
Raw Permalink Normal View History

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">
<title>Add Reply List Entry (ADDRPYLE)</title>
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
</head>
<body bgcolor="white">
<script language="Javascript" src="../rzahg/synch.js" type="text/javascript"></script>
<a name="ADDRPYLE.Top_Of_Page"></a>
<h2>Add Reply List Entry (ADDRPYLE)</h2>
<table width="100%">
<tr>
<td valign="top" align="left"><b>Where allowed to run: </b>All environments (*ALL)<br>
<b>Threadsafe: </b>No
</td>
<td valign="top" align="right">
<a href="#ADDRPYLE.PARAMETERS.TABLE">Parameters</a><br>
<a href="#ADDRPYLE.COMMAND.EXAMPLES">Examples</a><br>
<a href="#ADDRPYLE.ERROR.MESSAGES">Error messages</a></td>
</tr>
</table>
<div> <a name="ADDRPYLE"></a>
<p>The Add Reply List Entry (ADDRPYLE) command is used to add an entry to the system-wide automatic inquiry message reply list. The automatic message reply list is the source for default responses to inquiry messages. Each entry in the inquiry message list specifies both a message identifier and the reply that is sent when that message is sent as an inquiry message. The entry may also include comparison data, which further qualifies the message identifier. The message identifier may be specific or generic in scope. One of the following actions may be taken when one of the specific inquiry messages is issued:
</p>
<ul>
<li>The default reply specified in the inquiry message file is sent to the message reply queue specified when the inquiry message was sent.
</li>
<li>A specific reply to the inquiry message is sent to the message reply queue specified when the inquiry message was sent.
</li>
<li>A manual reply to the inquiry message may be required from the operator.
</li>
</ul>
<p>The entry may also specify the dumping of information associated with the job that is sending the inquiry message.
</p>
<p>The reply list is used only when an inquiry message is sent by a job that has the inquiry message reply attribute specified as INQMSGRPY(*SYSRPYL). The INQMSGRPY attribute can be changed by using the Change Job Description (CHGJOBD) command.
</p>
<p>Specific attributes of a reply list entry can be changed by using the Change Reply List Entry (CHGRPYLE) command. Each reply list entry remains in the list until it is removed by the Remove Reply List Entry (RMVRPYLE) command. The list can be shown by using the Work with Reply List Entry (WRKRPYLE) command.
</p>
<p><b>Restrictions:</b>
</p>
<ol>
<li>This command is shipped with public *EXCLUDE authority and the QPGMR user profile has private authority to use the command.
</li>
<li>To use this command, you must be signed on as QPGMR, or have *USE special authority.
</li>
</ol>
</div>
<table width="100%">
<tr><td align="right"><a href="#ADDRPYLE.Top_Of_Page">Top</a></td></tr>
</table>
<hr size="2" width="100%">
<div>
<h3><a name="ADDRPYLE.PARAMETERS.TABLE">Parameters</a></h3>
<table border="1" cellpadding="4" cellspacing="0">
<!-- col1="10" col2="15" col3="30" col4="10" -->
<tr>
<th bgcolor="aqua" valign="bottom" align="left">Keyword</th>
<th bgcolor="aqua" valign="bottom" align="left">Description</th>
<th bgcolor="aqua" valign="bottom" align="left">Choices</th>
<th bgcolor="aqua" valign="bottom" align="left">Notes</th>
</tr>
<tr>
<td valign="top"><a href="#ADDRPYLE.SEQNBR"><b>SEQNBR</b></a></td>
<td valign="top">Sequence number</td>
<td valign="top">1-9999</td>
<td valign="top">Required, Positional 1</td>
</tr>
<tr>
<td valign="top"><a href="#ADDRPYLE.MSGID"><b>MSGID</b></a></td>
<td valign="top">Message identifier</td>
<td valign="top"><i>Character value</i>, <b><u>*ANY</u></b></td>
<td valign="top">Optional</td>
</tr>
<tr>
<td valign="top" rowspan="3"><a href="#ADDRPYLE.CMPDTA"><b>CMPDTA</b></a></td>
<td valign="top">Compare data</td>
<td valign="top"><i>Element list</i></td>
<td valign="top" rowspan="3">Optional</td>
</tr>
<tr>
<td valign="top">Element 1: Comparison data</td>
<td valign="top">
<i>Character value</i>, <b><u>*NONE</u></b></td>
</tr>
<tr>
<td valign="top">Element 2: Message data start position</td>
<td valign="top">
1-999, <b><u>*NONE</u></b></td>
</tr>
<tr>
<td valign="top"><a href="#ADDRPYLE.RPY"><b>RPY</b></a></td>
<td valign="top">Message reply</td>
<td valign="top"><i>Character value</i>, <b><u>*DFT</u></b>, *RQD</td>
<td valign="top">Optional</td>
</tr>
<tr>
<td valign="top"><a href="#ADDRPYLE.DUMP"><b>DUMP</b></a></td>
<td valign="top">Dump the sending job</td>
<td valign="top"><b><u>*NO</u></b>, *YES</td>
<td valign="top">Optional</td>
</tr>
<tr>
<td valign="top"><a href="#ADDRPYLE.CCSID"><b>CCSID</b></a></td>
<td valign="top">Coded character set ID</td>
<td valign="top">1-65535, <b><u>*HEX</u></b>, *JOB</td>
<td valign="top">Optional</td>
</tr>
</table>
<table width="100%">
<tr><td align="right"><a href="#ADDRPYLE.Top_Of_Page">Top</a></td></tr>
</table>
</div>
<div> <a name="ADDRPYLE.SEQNBR"></a>
<h3>Sequence number (SEQNBR)</h3>
<p>Specifies the sequence number of the reply list entry being added to the reply list. The message identifier and message data of an inquiry message are matched against the reply list entry message identifiers and comparison data in ascending sequence number order. The search ends when a match occurs or the last reply list entry is passed.
</p>
<p>Sequence numbers can range from 0001 to 9999. Duplicate sequence numbers are not allowed.
</p>
<p>This is a required parameter.
</p>
</div>
<table width="100%">
<tr><td align="right"><a href="#ADDRPYLE.Top_Of_Page">Top</a></td></tr>
</table>
<div> <a name="ADDRPYLE.MSGID"></a>
<h3>Message identifier (MSGID)</h3>
<p>Specifies the inquiry message identifiers for which automatic system action is taken. The message identifier can be specific or generic in scope. Only predefined messages (messages known to the system by a message identifier) can be matched by reply list entries. Immediate messages cannot be used for comparison.
</p>
<dl>
<dt><b><u>*ANY</u></b></dt>
<dd>This reply list entry matches any message identifier.
</dd>
<dt><b><i>message-identifier</i></b></dt>
<dd>Specify a message identifier that is compared with the message identifier of an inquiry message. The message identifier must be 7 characters in length and in the following format: <i>pppnnnn</i>
<p>The first 3 characters (ppp) must be a code consisting of one alphabetic character followed by two alphanumeric (alphabetic or decimal) characters; the last 4 characters (nnnn) must consist of the decimal numbers 0 through 9 and the characters A through F.
</p>
</dd>
</dl>
</div>
<table width="100%">
<tr><td align="right"><a href="#ADDRPYLE.Top_Of_Page">Top</a></td></tr>
</table>
<div> <a name="ADDRPYLE.CMPDTA"></a>
<h3>Compare data (CMPDTA)</h3>
<p>Specifies the comparison data that is used to determine whether this entry matches an inquiry message. If the identifier of the inquiry message matches the message identifier of this reply list entry, then the message data specified for the inquiry message is compared to this data.
</p>
<p><b>Element 1: Comparison data</b>
</p>
<dl>
<dt><b><u>*NONE</u></b></dt>
<dd>No comparison data is specified. If the inquiry message has the specified identifier, the action specified by this reply list entry is taken.
</dd>
<dt><b><i>'comparison-data'</i></b></dt>
<dd>Specify a character string of no more than 28 characters (enclosed in apostrophes if blanks or other special characters are included). This string is compared with a string of the same length in the message data portion of the inquiry message.
</dd>
</dl>
<p><b>Element 2: Message data start position</b>
</p>
<dl>
<dt><b><u>*NONE</u></b></dt>
<dd>No starting position value is specified. If comparison data is specified for element 1 of this parameter, the default start value is 1.
</dd>
<dt><b><i>message-data-start</i></b></dt>
<dd>Specify the character position in the message's replacement text (maximum value is 999) where the comparison data will start being compared to the replacement text. A start value is not valid without a specification of comparison data.
</dd>
</dl>
<p><b>Coded Character Set Identifier (CCSID) Considerations</b>
</p>
<p>The text supplied for the CMPDTA parameter that corresponds to the *CCHAR type field is assumed to be in the CCSID of the job running this command unless, the CCSID parameter is coded. If the CCSID parameter is coded, the text is assumed to be in the CCSID specified. For more information about the *CCHAR type field, see the Add Message Description (ADDMSGD) command.
</p>
</div>
<table width="100%">
<tr><td align="right"><a href="#ADDRPYLE.Top_Of_Page">Top</a></td></tr>
</table>
<div> <a name="ADDRPYLE.RPY"></a>
<h3>Message reply (RPY)</h3>
<p>Specifies how to reply to an inquiry message that matches this reply list entry. The reply specified is automatically sent by the system without requiring user intervention. The inquiry message does not cause the job to be interrupted or notified when the message has arrived at the message queue.
</p>
<dl>
<dt><b><u>*DFT</u></b></dt>
<dd>The default reply to the inquiry message is sent.
</dd>
<dt><b>*RQD</b></dt>
<dd>The inquiry message requires an explicit reply. No reply is automatically sent.
</dd>
<dt><b><i>'message-reply'</i></b></dt>
<dd>Specify a character string of no more than 32 characters, enclosed in apostrophes (if blanks or other special characters are included) that is sent as a reply to the inquiry message.
</dd>
</dl>
</div>
<table width="100%">
<tr><td align="right"><a href="#ADDRPYLE.Top_Of_Page">Top</a></td></tr>
</table>
<div> <a name="ADDRPYLE.DUMP"></a>
<h3>Dump the sending job (DUMP)</h3>
<p>Specifies whether the job that sent the inquiry message is to be dumped.
</p>
<dl>
<dt><b><u>*NO</u></b></dt>
<dd>The job is not dumped.
</dd>
<dt><b>*YES</b></dt>
<dd>The job is dumped before the control returns to the program that is sending the message.
</dd>
</dl>
</div>
<table width="100%">
<tr><td align="right"><a href="#ADDRPYLE.Top_Of_Page">Top</a></td></tr>
</table>
<div> <a name="ADDRPYLE.CCSID"></a>
<h3>Coded character set ID (CCSID)</h3>
<p>Specifies the coded character set identification (CCSID) that the text specified for the CMPDTA parameter that corresponds to the *CCHAR type field is to be considered in.
</p>
<dl>
<dt><b><u>*HEX</u></b></dt>
<dd>The CMPDTA that corresponds to the *CCHAR data type field is assumed to be 65535. No conversion occurs before the replacement data is compared with the CMPDTA.
<p>When an inquiry message is sent in a job that is using the system reply list, the *CCHAR replacement data is counted to the CCSID of the CMPDTA that is stored in the system reply list before the comparison is made.
</p>
<p>All other compare data is not converted before a comparison is made. For more information about the message handler and its use of CCSIDs, see the Globalization topic in the iSeries Information Center at http://www.ibm.com/eserver/iseries/infocenter.
</p>
<p>
<b>Note: </b>When specifying a CCSID other than *HEX, all the CMPDTA specified is converted from that CCSID to the job CCSID when displayed on the Work with Reply List Entries panel. This occurs even when all CMPDTA does not correspond with *CCHAR data; therefore, when using a CCSID other than *HEX, specifying the length of the *CCHAR data or any other data field is not recommended.
</p>
</dd>
<dt><b>*JOB</b></dt>
<dd>The CMPDTA that corresponds to the *CCHAR data type field is assumed to be in the CCSID of the job calling this command.
</dd>
<dt><b><i>coded-character-set-identifier</i></b></dt>
<dd>Specify the CCSID you want the CMPDTA that corresponds to *CCHAR data type field to be considered in.
</dd>
</dl>
</div>
<table width="100%">
<tr><td align="right"><a href="#ADDRPYLE.Top_Of_Page">Top</a></td></tr>
</table>
<hr size="2" width="100%">
<div><h3><a name="ADDRPYLE.COMMAND.EXAMPLES">Examples</a> </h3>
<p><b>Example 1: Reply Automatically Sent</b>
</p>
<p>
<pre>
ADDRPYLE SEQNBR(10) MSGID(RPG1241) RPY(G)
</pre>
</p>
<p>This command adds a reply list entry to the reply list for message identifier RPG1241 (database record not found). Whenever a RPG1241 inquiry message is sent by a job that is using the reply list, a reply of 'G' is automatically sent. The inquiry does not cause a job that has allocated the message queue to be interrupted or notified when the inquiry arrives, and no opportunity is given to reply to the message. The sending job does not have a job dump processed.
</p>
<p><b>Example 2: Default Reply is sent; Job Dump Processed</b>
</p>
<p>
<pre>
ADDRPYLE SEQNBR(25) MSGID(RPG1200) RPY(*DFT) DUMP(*YES)
</pre>
</p>
<p>This command adds a generic reply list entry to the reply list for all RPG12xx messages. Whenever an RPG12xx inquiry message is sent by a job that is using the reply list, the equivalent to DSPJOB OUTPUT (*PRINT) is automatically generated. The default reply will automatically be sent. This is either the default reply specified in the message description or (if none is specified in the message description) the system default reply. The inquiry does not cause a job that has allocated the message queue to be interrupted or notified when the inquiry arrives, and no opportunity is given to reply to the message. The sending job is dumped before control returns to the sending program. Note that because of the sequence numbers, the entry added by the previous example overrides this entry for message identifier RPG1241.
</p>
<p><b>Example 3: Adding a Generic Reply List Entry</b>
</p>
<p>
<pre>
ADDRPYLE SEQNBR(30) MSGID(RPG0000) RPY(D) DUMP(*YES)
</pre>
</p>
<p>This command adds a generic reply list entry to the reply list for all RPG messages. Whenever an RPG inquiry message is sent by a job that is using the reply list, a reply of 'D' is sent automatically. The inquiry does not cause a job that has allocated the message queue to be interrupted or notified when the inquiry arrives, and no opportunity is given to reply to the message. (If a value of D is not valid for a particular RPGxxxx message, the user must reply as if *RQD were specified for the RPY parameter.) The sending job is dumped before control returns to the sending program. Note that the entries added by the previous two examples will override this entry for all RPG12xx messages.
</p>
<p><b>Example 4: System Reply List for Spooled Output</b>
</p>
<p>
<pre>
ADDRPYLE SEQNBR(40) MSGID(CPA5316)
CMPDTA('QPSPLPRT QSYS QSYSPRT') RPY(*RQD)
</pre>
</p>
<p>This command illustrates how to use the system reply list for spooled output for device QSYSPRT. The file and library name for spooled output is QSYS/QPSPLPRT.
</p>
<p>When compare value is specified, it is compared to the message data beginning with replacement variable &amp;1. If the significant field appears in replacement variable &amp;3, the compare value must include a value for replacement variables &amp;1 and &amp;2, or a message data start value may be entered to begin the comparison with replacement variable &amp;3.
</p>
<p>The message CPA5316 has a replacement data as follows:
</p>
<p>
<pre>
&amp;1 ODP file name &amp;CHAR 10
&amp;2 ODP library name &amp;CHAR 10
&amp;3 ODP device name &amp;CHAR 10
</pre>
</p>
<p>A compare for device name 'QSYSPRT' in replacement variable &amp;3 must be preceded by values for &amp;1 and &amp;2 if a message data start value is not entered. Blanks are significant.
</p>
<p>The message data of QSYSPRT is the DEVICE name as defined in the CPA5316 message. Whenever a CPA5316 inquiry message with comparison data of QSYSPRT is sent by a job that is using the reply list, the operator must make a manual reply to the inquiry. If the message queue to which the inquiry is sent is in break mode, the inquiry message interrupts. A reply is not sent (unless the queue is in the default mode or the message is sent to an external message queue in a batch job), and no job dump is taken.
</p>
<p>Another reply list entry identical to the one listed above could be added, but with a different sequence number and with CMPDTA(WSPR01) specified. This would allow a unique response to a message based on the type of printer.
</p>
<p><b>Example 5: Adding Reply List Entry For Any Message Identifier</b>
</p>
<p>
<pre>
ADDRPYLE SEQNBR(9999) MSGID(*ANY) RPY(*RQD) DUMP(*YES)
</pre>
</p>
<p>This command adds a reply list entry to the reply list for any message identifier. This entry applies to any predefined inquiry message that is not matched by an entry with a lower sequence number. A manual reply to the inquiry message is required for any predefined inquiry message not matched by a previous entry. If the message queue to which the inquiry message is sent is in break mode, the message interrupts. The job that sent the inquiry message is dumped (equivalent to DSPJOB OUTPUT(*PRINT)).
</p>
<p><b>Example 6: Using Comparison Data</b>
</p>
<p>
<pre>
ADDRPYLE SEQNBR(5) MSGID(CPA5316) CMPDTA(QSYSPRT 21)
RPY(I) DUMP(*NO)
</pre>
</p>
<p>Assume that the message CPA5316 is sent to QSYSOPR with the message replacement text of TESTEDFILETSTLIBRARYQSYSPRT; because there is a match for MSGID, the message replacement text starting in position 21 (message data start) is tested by comparing it with the comparison data (for the length of the comparison data). This is a match because QSYSPRT = QSYSPRT, and therefore the reply of 'I' is sent.
</p>
</div>
<table width="100%">
<tr><td align="right"><a href="#ADDRPYLE.Top_Of_Page">Top</a></td></tr>
</table>
<hr size="2" width="100%">
<div><h3><a name="ADDRPYLE.ERROR.MESSAGES">Error messages</a> </h3>
<p><b><u>*ESCAPE Messages</u></b>
</p>
<dl>
<dt><b>CPF2435</b></dt>
<dd>System reply list not found.
</dd>
<dt><b>CPF2436</b></dt>
<dd>System Reply List entry not added or changed.
</dd>
<dt><b>CPF247E</b></dt>
<dd>CCSID &amp;1 is not valid.
</dd>
<dt><b>CPF2499</b></dt>
<dd>Message identifier &amp;1 not allowed.
</dd>
<dt><b>CPF2555</b></dt>
<dd>Sequence number &amp;1 already defined in system reply list.
</dd>
<dt><b>CPF2557</b></dt>
<dd>System reply list damaged.
</dd>
<dt><b>CPF2558</b></dt>
<dd>System reply list currently in use.
</dd>
</dl>
</div>
<table width="100%">
<tr><td align="right"><a href="#ADDRPYLE.Top_Of_Page">Top</a></td></tr>
</table>
</body>
</html>