Add Reply List Entry (ADDRPYLE)

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:

The entry may also specify the dumping of information associated with the job that is sending the inquiry message.

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 (CHGJOB) command.

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.

Restrictions:

  1. This command is shipped with public *EXCLUDE authority and the QPGMR user profile has private authority to use the command.
  2. To use this command, you must be signed on as QPGMR, or have *USE special authority.

Parameters

Keyword Description Choices Notes
SEQNBR Sequence number 1-9999 Required, Positional 1
MSGID Message identifier Character value, *ANY Optional
CMPDTA Compare data Element list Optional
Element 1: Comparison data Character value, *NONE
Element 2: Message data start position 1-999, *NONE
RPY Message reply Character value, *DFT, *RQD Optional
DUMP Dump the sending job *NO, *YES Optional
CCSID Coded character set ID 1-65535, *HEX, *JOB Optional

Sequence number (SEQNBR)

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.

If more than one reply list entry matches the inquiry message identifier and comparison data, only the first entry that matches is used. If no reply list entry matches the inquiry message, the inquiry is sent, but no automatic reply is sent unless a default reply is sent, and the information associated with the job is not dumped. Default replies are sent when the delivery mode of the message queue is set to *DFT or when the inquiry message is sent to an external message queue in a batch job.

Sequence numbers can range from 0001 to 9999. Duplicate sequence numbers are not allowed.

This is a required parameter.

Message identifier (MSGID)

Specifies the inquiry message identifier 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 against reply list entries. Immediate messages cannot be used for comparison.

If no comparison data is specified, then only the message identifier is used to match the message to this reply list entry. If this is the first message reply list entry that matches the message, the action specified in this entry is taken.

*ANY
This reply list entry matches any message identifier. Unless comparison data is specified for this reply list entry, all reply list entries with a sequence number greater than this one are ignored.
message-identifier
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: pppnnnn

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.

To specify a generic message identifier, enter zeros in the rightmost two or four positions of the numeric field, such as pppnn00 or ppp0000. For example, CPA0000 would match any CPA inquiry message, while CPA4200 would match any CPA42xx inquiry message.

Compare data (CMPDTA)

Specifies the comparison data that is used to determine whether this entry matches an inquiry message. This parameter is made up of comparison data and a message data start value. 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. If a message data start value has not been specified, then the first part of the message data (up through the first 28 characters or less) must exactly match the comparison data specified here before the action requested for this reply list entry is taken. However, if a start value has been specified, then the part of the message data beginning with the character position specified in the start value must exactly match the comparison data before any requested action is taken. If the comparison data is longer than the message data, then no match occurs. If no comparison data is specified, then only the message identifier is used to match the message to this reply list entry. If, in the message reply list, this is the first entry that matches the message, then the action specified in this entry is taken.

Note: Message data for an inquiry message may be specified in the MSGDTA parameter of the SNDUSRMSG or SNDPGMMSG commands for the inquiry message.

Element 1: Comparison data

*NONE
No comparison data is specified. If the inquiry message has the specified identifier, the action specified by this reply list entry is taken.
'comparison-data'
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, beginning with the first character (if no start value has been specified). If the comparison data string matches the inquiry message data string, the action specified by this reply list entry is taken.

Element 2: Message data start position

*NONE
No starting position value is specified. If comparison data is specified for element 1 of this parameter, the default start value is 1.
message-data-start
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.

Coded Character Set Identifier (CCSID) Considerations

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.

Message reply (RPY)

Specifies how to reply to an inquiry message that matches this reply list entry. The reply specified (other than *RQD) in this reply 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.

*DFT
The default reply to the inquiry message is sent. If no default reply is specified in the message description of the inquiry message, the system default reply, *N, is used.
*RQD
The inquiry message requires an explicit reply. If the message queue to which the inquiry is sent is in break mode, the message interrupts and is displayed. If the message queue is in notify mode, the job to which it is allocated is notified. No reply is automatically sent. If the message queue is in hold mode, the message remains on the queue until it is removed.
'message-reply'
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. If this reply is not valid for the inquiry message, the inquiry is sent as if RPY(*RQD) had been specified.

Dump the sending job (DUMP)

Specifies whether the job that sent the inquiry message is to be dumped. The dump is the same as the dump specified by DMPLST(*JOB) on the Add Message Description (ADDMSGD) command or by OUTPUT(*PRINT) on the Display Job (DSPJOB) command for the sending job. A job dump may be requested regardless of the value specified for the RPY parameter.

*NO
The job is not dumped.
*YES
The job is dumped before the control returns to the program that is sending the message.

Coded character set ID (CCSID)

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.

When an inquiry message is sent in a job that is using the system reply list, the *CCHAR replacement data is converted to the CCSID of the CMPDTA that is stored in the system reply list before the comparison is made.

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 i5/OS globalization topic collection in the IBM i Information Center at http://www.ibm.com/systems/i/infocenter/.

Note: 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.

*HEX
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.
*JOB
The CMPDTA that corresponds to the *CCHAR data type field is assumed to be in the CCSID of the job calling this command.
coded-character-set-identifier
Specify the CCSID you want the CMPDTA that corresponds to *CCHAR data type field to be considered in.

Examples

Example 1: Reply Automatically Sent 

ADDRPYLE   SEQNBR(10)  MSGID(RPG1241)  RPY(G)

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.

Example 2: Default Reply is sent; Job Dump Processed 

ADDRPYLE   SEQNBR(25)  MSGID(RPG1200)  RPY(*DFT)  DUMP(*YES)

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.

Example 3: Adding a Generic Reply List Entry 

ADDRPYLE   SEQNBR(30)  MSGID(RPG0000)  RPY(D)  DUMP(*YES)

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.

Example 4: System Reply List for Spooled Output 

ADDRPYLE   SEQNBR(40)  MSGID(CPA5316)
           CMPDTA('QPSPLPRT  QSYS      QSYSPRT')  RPY(*RQD)

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.

When compare value is specified, it is compared to the message data beginning with replacement variable &1. If the significant field appears in replacement variable &3, the compare value must include a value for replacement variables &1 and &2, or a message data start value may be entered to begin the comparison with replacement variable &3.

The message CPA5316 has a replacement data as follows: 

&1        ODP file name        &CHAR  10
&2        ODP library name     &CHAR  10
&3        ODP device name      &CHAR  10

A compare for device name 'QSYSPRT' in replacement variable &3 must be preceded by values for &1 and &2 if a message data start value is not entered. Blanks are significant.

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.

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.

Example 5: Adding Reply List Entry For Any Message Identifier 

ADDRPYLE   SEQNBR(9999)  MSGID(*ANY)  RPY(*RQD)  DUMP(*YES)

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)).

Example 6: Using Comparison Data 

ADDRPYLE   SEQNBR(5) MSGID(CPA5316) CMPDTA(QSYSPRT 21)
           RPY(I) DUMP(*NO)

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.

Error messages

*ESCAPE Messages

CPF2435
System reply list not found.
CPF2436
System Reply List entry not added or changed.
CPF247E
CCSID &1 is not valid.
CPF2499
Message identifier &1 not valid.
CPF2555
Sequence number &1 already defined in system reply list.
CPF2557
System reply list damaged.
CPF2558
System reply list currently in use.