Reply Handling Exit Program

A reply handling exit program is called when a reply is sent to an inquiry message. The operating system calls the user-written exit program identified through the registration facility. The program is called after the system validates the reply, but before the reply is sent to the inquiry message. For some inquiry messages, a reply handling exit program can indicate that the reply should be rejected. When an exit program indicates that the reply should be rejected, a diagnostic message (CPD2476 Reply rejected by a reply handling exit program) is sent to the caller of the send reply function.

This is followed by an escape message CPF2422 (Reply not valid). An exit program can also replace the reply value to be sent. When an exit program indicates that the reply should be replaced, the send reply function sends a diagnostic message to itself. The message is CPD2479 (Reply handling exit program requested to replace a reply value). After the reply is sent, CPF2458 (Reply replaced by a reply handling exit program) will be sent as a diagnostic message and a status message to the caller of the send reply function. The status message allows the caller to monitor for the condition when a reply value other than what was specified is sent. When the condition occurs, the caller can then receive the diagnostic message to obtain details about the reply replacement.

The first parameter sent to the exit program indicates the various reasons for which the exit program can be called.

The exit point supports an unlimited number of exit programs. If multiple exit programs are defined, all of the exit programs are called for each reply to an inquiry message until one of the exit programs rejects the reply or replaces the reply value. When a reply is rejected or replaced, any exit program that was previously notified of the reply is called again to be informed the reply is now being rejected or replaced. See Required Parameters for details on the types of calls the exit program must handle and the valid return codes that can be specified to return to the exit point. For information about adding or removing an exit program for an exit point, see Registration Facility documentation.

The exit program can use the receive message function to obtain additional information about the message being replied to. For example, the program can obtain the message data, the sender of the message, and so on. If the exit program attempts to obtain information from the sending job, it needs to take into account that the job that sent the inquiry could have ended before the inquiry is replied to, thus requiring the exit program to handle a not-found error. The exit program is executed within the same job as the user that entered a reply. It can use commands or APIs to obtain information about the current job and current user that provided the reply.

Authorities and Locks

User Profile Authority

*ALLOBJ and *SECADM to add or remove exit programs in the registration facility.

Required Parameter Group

Type of call

INPUT; BINARY(4)

The reason the exit program is being called. The valid values are:

0	Reply notification--no action allowed. Informs an exit program that a reply is being sent to an inquiry message. The original reply value has been replaced by another exit program so any remaining exit programs are informed of the reply with this value, but the reply cannot be rejected or replaced. The return code parameter is ignored by the exit point.
1	Reply validation requested. The exit program should set the return code parameter to indicate whether the reply should be accepted, rejected, or replaced. A return code parameter with a value other than 0 or 2 will cause the reply to be accepted.
2	Default reply validation requested. The default reply is being sent to an inquiry message. The exit program should set the return code parameter to indicate whether the reply should be accepted or replaced. The exit program can set the return code parameter to indicate rejected, but this will cause the inquiry message to be left as unanswered (and possibly cause the job to hang). A return code parameter with a value other than 0 or 2 will cause the reply to be accepted.
3	Default reply notification. Informs an exit program that an inquiry message is being replied to with the default reply and the reply cannot be rejected, but the reply value can be replaced by an exit program. A return code parameter value other than 2 is ignored by the exit point and the reply is accepted. If a user or job requested a function that sends a default reply and the reply is not allowed to be rejected, this value would be sent to an exit program. Examples of when this value would be used: deleting a message queue that contains unanswered inquiry messages. sending the default reply to an unanswered inquiry and the parameter to allow default reply rejection was not specified. sending an inquiry to a message queue that is in default mode. sending an inquiry to *EXT so it shows the Display Program Messages screen and the user presses F3, F12 or Enter to exit the screen without entering any reply. sending an inquiry to *EXT in a batch job. a job uses an inquiry message reply job attribute of *DFT. wrapping a message queue.
4	Reply rejected notification. Informs an exit program that another exit program rejected the reply to an inquiry message. The return code parameter is ignored by the exit point and a reply is not sent to the inquiry message. When an exit program rejects a reply, any exit programs that previously accepted the reply are notified that a reply was rejected with the use of this value but any remaining exit programs that have never been informed of the reply will not be called to be notified of the rejection. When a reply is rejected, message CPD2476 (Reply rejected by a reply handling exit program) is sent as a diagnostic message to the caller of the send reply function to indicate the reply they requested to be sent was rejected. The send reply function will also send message CPD2476 a second time. The second time it will be sent to the send reply function instead of to its caller. This will allow an exit program to receive the CPD2476 by specifying to receive the message from the invocation previous to the exit program. So there are not two CPD2476 messages left in the job log, the second CPD2476 will be removed by the send reply function after all the exit programs that accepted the reply are notified of the reply rejection.
5	Replaced reply not valid. Informs an exit program that the reply information it specified for replacement is not valid. The send reply function will send a diagnostic message to itself to indicate the problem with the reply information. One of the following messages could be sent: CPD2477 (Reply replaced by exit program not valid) or CPD2478 (Reply replaced by exit program same as original reply value). The return code parameter will be ignored by the exit point and the original reply value, now specified in parameters 5 though 7, will be used as the reply value for the message. The next reply handling exit program will be called or the reply will be sent if there are no other exit programs to call.
6	Reply replaced notification. Informs an exit program, that has already accepted the reply, that another exit program replaced that reply. When a reply is replaced, the send reply function will send CPD2479 (Reply handling exit program requested to replace a reply value) as a diagnostic message to itself. This will allow an exit program to receive the message from the previous invocation to find out information about the replacement. The return code parameter is ignored by the exit point. The reply cannot be rejected nor replaced. Parameters 5 through 7 contain the new reply value to be sent to the inquiry message.
7	Reply cannot be sent notification. The return code parameter is ignored by the exit point. The reply is not sent to the inquiry message. When an exit program accepts a reply, but then the system is not able to send that reply to the inquiry message, this value will be used to notify all the exit programs. This may indicate that something is wrong with the queue. After exit programs are notified, an error message is sent by the system reply function as it ends or returns.

Note: For values 0, 4, 5, and 6, parameter 8 will be ignored. For values 4 and 7, parameter 5 will be blank and parameters 6 and 7 will be zero.

Qualified message queue name

INPUT; CHAR(20)

The name of the message queue and library containing the inquiry message. The message queue name is a 10-character field that is left-justified and padded with blanks if the name is less than 10 characters. The 10-character message queue name is followed by the 10-character library name that is padded with blanks to the right, if necessary. A special value of *EXT will be used for the message queue name with blanks for the library name to indicate the inquiry message was sent to the job's external message queue.

Message key

INPUT; CHAR(4)

The message reference key of the inquiry message that is being replied to.

Message identifier

INPUT; CHAR(7)

The message identifier of the inquiry message that is being replied to. This value will be blank for an impromptu message.

Reply

I/O; CHAR(*)

The reply to be sent to an inquiry message. If a reply is being replaced by an exit program, the new reply value is specified in this parameter.

Length of the reply

I/O; BINARY(4)

The length of the specified reply. The maximum value is 132. If a reply is being replaced by an exit program, the length of the new reply value is specified in this parameter. If a reply is being replaced with a default reply value, a value of 0 can be specified.

CCSID of the reply

I/O; BINARY(4)

The coded character set identifier of the specified reply. If a reply is being replaced, the CCSID of the reply is specified in this parameter. The valid values are:

0	The message reply text is assumed to be in the CCSID of the job running the exit program.
65535	The message reply text will not be converted.
CCSID	Specify a valid CCSID that your message reply text is in. Valid values are between 1 and 65535.

For a list of valid CCSIDs, see CCSIDs: Message Support in the Globalization topic.

Coded Character Set Identifier (CCSID) Considerations

If the inquiry message that this reply is being sent to is an impromptu message, the text supplied on the reply parameter is assumed to be in the CCSID of the job running this exit program unless the coded character set identifier is supplied in the CCSID parameter. If the inquiry message that this reply is being sent to is a predefined message, then the text supplied on the reply text parameter is considered 65535 and is not converted. For more information about message handler and its use of CCSIDs, see CCSIDs: Message Support in the Globalization topic.

Reply action return code

OUTPUT; BINARY(4)

The return code to indicate whether the reply should be rejected, accepted, or replaced. The valid values are:

0	The reply should be rejected. Any exit program that previously accepted the reply will be notified of the reply rejection. Any remaining exit programs will not be called.
1	The reply should be accepted. The next exit program will be called or the reply will be sent if there are no other exit programs.
2	The reply should be replaced using the values provided in parameters 5 through 7, reply, length of the reply, and CCSID of the reply. If the replaced reply value is not valid, or if the reply value is the same as the original reply value, the send reply function will send one of these messages as a diagnostic message to itself: CPD2477 (Reply replaced by exit program not valid) or CPD2478 (Reply replaced by exit program same as original reply value). Then it will notify the exit program of the the error with a type of call value of 5 and then act as if the exit program accepted the original value and the next exit program will be called or the original reply will be sent if there are no other exit programs. If the replaced reply is valid, any exit program that previously accepted the reply will be notified of the reply replacement. The remaining reply handling exit programs will be called but they will not be allowed to reject or replace the reply. If there are no remaining exit programs to call, the new reply value will be sent.

Note: A value other than 0 or 2 will cause the reply to be accepted.

Usage Notes

1. System debug breakpoints in reply handling exit programs will be ignored while processing the reply handling exit point. When sending a reply and a reply handling exit program is called, message CPF195A (Breakpoint already run when notification received) will be generated for any breakpoints set in the exit program.
   
2. A reply handling exit program can send a message other than an inquiry and reply, but the program will get into a recursive loop if it tries to do functions like the following that affect inquiry messages and their reply:
   • send a reply to the inquiry message that it is being called to handle.
   • send a reply to any other inquiry message.
   • receive an unanswered inquiry message with the remove option set to yes.
   • remove an unanswered inquiry message.
   • send an inquiry message to *EXT.

   For example, a user enters a reply, so a reply handling exit program is called. The exit program sends a reply to the inquiry (or tries to remove the message, but the default reply must be sent first); this calls the exit program again, causing a loop.

3. The time between checking if there is a reply for an inquiry and actually sending the reply to the inquiry message will be greater with the use of reply handling exit programs. If the message queue is not already allocated to the job in which the reply is being sent, when the reply is sent it is implicitly allocated internally for the duration of the send. This means that if there are a number of exit programs to call or if an exit program runs for a long time, other users or jobs trying to use the message queue can see CPF2477 (message queue in use) more often if the exit programs could not complete during the internal lock wait time built into message handling functions.
   
   
4. Messages that provide information about reply rejection or replacement should not be removed by an exit program. When an exit program is receiving one of these messages, the program should specify parameter values on the receive such that it allows the messages to remain in the job log so they are available to be received by other exit programs.
   
   
5. If an exit program uses a receive function to receive additional information about the inquiry message on a nonprogram (standard) message queue, it should:
   • use the receive nonprogram message API, QMHRCVM, and
   • specify *SAME for the message action parameter.
   Using this value on the API will not change the status of the message so other exit programs can still receive the message, but it will also allow the receive to occur even if the queue is implicitly locked due to a break handling program or a receive message with a wait time specified.
6. Error situations:
   • If an error occurs while retrieving the list of exit programs for the reply handling exit point, the error will be left in the joblog and the reply will be accepted as if no exit programs were specified for the exit point.
   • A reply will be accepted if a reply handling exit program:
     • cannot be found
     • specifies a return code that is not valid
     • sends any error messages
     • tries to replace a reply value with a reply that is not valid
   • Any message resulting from calling the exit program (such as program not found) or any message issued by the exit program will be left in the joblog. No new or additional message will be sent to indicate that an error occurred or that the return code was not valid.
   
   
7. The send reply function is threadsafe. A reply handling exit program can be called from within a multithreaded job. When a reply handling exit program is added to the registration facility, it can specify a multithreaded job action. One of the following actions will be taken in a multithreaded job, depending on the value indicated by the registration facility:
   
   

   1	The exit program will be called.
   2	The exit program will be called and then CPI3C80 (an exit program was called in a multithreaded job) will be issued as an informational message to the caller of the send reply function for each exit program with this value. If an exit program is called again for a reply being rejected by another exit program, the CPI3C80 will not be resent.
   3	The exit program will NOT be called and CPF3C80 (an exit program was not called in a multithreaded job) will be issued as an informational message to the caller of the send reply function for each exit program with this value. For exit programs with this value, the exit point will act as if the reply was accepted by the exit program and continue the function of calling the next exit program or sending the reply.