Inquiry Handling Exit Program

An inquiry handling exit program is called in an interactive job when an inquiry message has been sent to *EXT and the job would be interrupted by the Display Program Messages screen to obtain a reply. The exit program can send a reply to the inquiry message, so the interactive user is not interrupted to provide a reply to the inquiry message.

When an inquiry message is sent to *EXT in an interactive job, the job does not continue until a reply has been sent to the inquiry message. The job attribute inquiry message reply (INQMSGRPY) can be used to automatically provide a reply to an inquiry message. If the inquiry message is not replied via the job attribute, then the Display Program Messages screen is shown to obtain a reply from an interactive user. An inquiry handling exit program is another alternative to provide a reply to an inquiry message to eliminate interrupting a user to provide a reply. The operating system calls the user-written exit program identified through the registration facility. The exit program is called after the system has sent the inquiry message, sent its associated sender copy message and processed the system reply or default values for job attribute INQMSGRPY. This means, at the point an interactive job would be interrupted by the Display Program Messages screen, then any inquiry handling exit programs would be called. If exit programs did not provide a reply to the inquiry message, then the Display Program Messages screen would be shown to obtain a reply from the interactive user.

Note: The exit point should not be confused with nonprogram message queues like QSYSOPR or user profile message queues that are in break mode where the Display Messages screen would interrupt an interactive job to obtain a reply to an inquiry message. The handle inquiry to *EXT exit point only affects inquiry messages sent to *EXT (the external message queue) associated with an interactive job. It does not handle notify messages.

The exit program should use the Send Reply Message (QMHSNDRM) API to send a reply to the inquiry message. The exit program can use the receive message function to obtain additional information about the inquiry message needing a reply. For example, the program can obtain the message data, the sender of the message, the message file and so on. For a predefined message, the exit program could also retrieve valid reply values from the message file obtained from the receive message function. The exit program is executed within the same job as the program that sent the inquiry message.

Anyone creating or using an inquiry handling exit program should be aware of the reply handling exit point QIBM_QMH_REPLY_INQ. A reply handling exit program can reject or replace a reply value sent to an inquiry message by an inquiry handling exit program. For example, when an inquiry handling exit program sends a reply to an inquiry message, before the reply is sent, the send reply function will call any reply handling exit programs to inform them that a reply is about to be sent to an inquiry message.

• If a reply handling exit program rejects a reply, diagnostic message CPD2476 (Reply rejected by a reply handling exit program) is sent to the caller of the send reply function followed by escape message CPF2422 (Reply not valid). The escape message could be monitored and the inquiry handling exit program could attempt to send a different reply value to the inquiry message. If a reply handling exit program rejects a reply sent by an inquiry handling exit program and the inquiry remains unanswered, the Display Program Messages screen will be shown to obtain a reply.
• If a reply handling exit program replaces a reply, CPF2458 (Reply replaced by a reply handling exit program) is issued as a diagnostic message and a status message to the caller of the send reply function. An inquiry handling exit program could monitor for the status message to be aware that their reply value was changed, but the replaced reply has been sent so the reply value can no longer be changed.

The exit point supports an unlimited number of exit programs. If multiple exit programs are defined, exit programs are called until an exit program sends a reply to the inquiry message. Once the inquiry has a reply, no remaining exit programs will be called and any exit program that was previously notified of the inquiry needing a reply, will not be called again to be informed of the reply value. The final notification is not done because the inquiry could have been removed so there would be no detail information available about the inquiry message. See Required Parameter Group for details on the parameters the exit program must handle. For information about adding or removing an exit program for an exit point, see Registration Facility APIs.

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:

1

Inquiry needs reply. The exit program can send a reply to the inquiry message. If the inquiry remains unanswered, the next inquiry handling exit program will be called. Once the inquiry has a reply, no remaining exit programs will be called because the inquiry could have been removed so there would be no detail information available about the inquiry message. After all exit programs are called, if the inquiry is still unanswered, then the Display Program Messages screen will be shown to obtain a reply to the inquiry from the interactive user. After calling an exit program, if the inquiry message cannot be found it is assumed the inquiry was replied (via sending a reply or deleting the inquiry), so no remaining exit programs would be called.

Message queue name

INPUT; CHAR(20)

The name of the message queue containing the inquiry message. A special value of *EXT will be specified. *EXT indicates 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 needs a reply.

Message identifier

INPUT; CHAR(7)

The message identifier of the inquiry message that needs a reply. This value will be blank for an impromptu message.

Usage Notes

1. System debug breakpoints in inquiry handling exit programs will be ignored while processing the handle inquiry to *EXT exit point. When sending an inquiry and an inquiry 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. An inquiry handling exit program can send a reply to an inquiry message, but the program will get into a recursive loop if it tries to send another inquiry message to *EXT. For example, an inquiry is sent to *EXT and the exit program sends another inquiry to *EXT, this calls the exit program again, causing a loop.
3. If an exit program uses a receive function to receive additional information about the inquiry message on a program message queue, it should ensure it does not remove the inquiry message. If the message is removed, it will be sent the default reply. Note, the default on the Receive Message (RCVMSG) CL command is to remove the message.
4. The send inquiry function will send a CPI2516 (Reply sent by inquiry handling exit program) to itself when an inquiry handling exit program provides a reply to an inquiry message. The exit program could specifically send a reply to the inquiry or even if it removes the inquiry, a reply will be sent before the inquiry is removed. Either way the CPI2516 will be generated. If the inquiry was removed, the exit point will act as if a reply was sent to the inquiry and the interactive user will not be interrupted by the Display Program Messages screen.

   If a user is expecting to see an inquiry in the joblog, they should be aware this could change. There are a couple ways to remove the inquiry message. One is the send reply function has an option to remove the inquiry and its reply. Another is deleting the unanswered inquiry, which would result in the default reply being sent before the inquiry is removed. Both conditions allow the sender of the inquiry to obtain the reply via the sender copy message. If the sender copy is on a nonprogram message queue, instead of the joblog, the CPI2516 could be the only indication in the joblog that an inquiry was sent and replied.

   
   
5. The time between an inquiry being sent and the job obtaining a reply to continue processing will be greater with the use of an inquiry handling exit program. The extra processing time is due to calling the user-exit programs and after each exit program is called the inquiry message must be relocated then re-checked to determine if a reply was sent.
6. Error situations:
   • If an error occurs while retrieving the list of exit programs for the handle inquiry to *EXT exit point, the error will remain in the joblog and the inquiry will be treated as if no reply was entered, so the Display Program Messages screen will interrupt an interactive user to obtain a reply.
   • An inquiry message will remain unanswered if an inquiry handling exit program cannot be found. The next exit program will be called or the Display Program Messages screen will be shown.
   • Any message resulting from calling the exit program (such as program not found) or any message issued by the exit program will remain in the joblog. No new or additional message will be sent to indicate that an error occurred.
   
   
7. The Add Exit Program (ADDEXITPGM) CL command has a multithreaded job action keyword. One of the following actions will be taken in a multithreaded job, depending on value indicated by the registration facility (value 1-3 below are values allowed for the multithreaded job action system value QMLTTHDACN):
   
   

   1 or *RUN	The exit program will be called.
   2 or *MSG	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 inquiry function for each exit program with this value. (The caller of the send inquiry function is not the user program that performed a send inquiry message operation. There are a couple different IBM® programs that process the send inquiry function for the user. When control returns to the user program that sent the inquiry message, the CPI3C80 will exist on a call message queue of a program or procedure that has ended, so it can only be received by using its message key.)
   3 or *NORUN	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 inquiry function for each exit program with this value. For exit programs with this value, the exit point will act as if the inquiry message was left unanswered and call the next exit program or show the Display Program Messages screen to obtain a reply for the inquiry message. (The caller of the send inquiry function is not the user program that performed a send inquiry message operation. There are a couple different IBM programs that process the send inquiry function for the user. When control returns to the user program that sent the inquiry message, the CPF3C80 will exist on a call message queue of a program or procedure that has ended, so it can only be received by using its message key.)

[ Back to top | Message Handling APIs | APIs by category ]