This is the second in a series of articles related to detecting when an inquiry message has been sent on your system and then making processing decisions based on the inquiry message. The underlying technology being used is known as the reply-handling exit program and has been available since V5R2.

 

The first article, "Beyond Watches," introduced the reply-handling exit point QIBM_QMH_REPLY_INQ documented here, provided a program prototype for an exit program and an explanation of the parameters passed to the exit program from the operating system, and reviewed our requirements for the exit program. The complete source for the RNQMGR exit program is provided below:

 

 

 

Assuming that the QSYSINC library (option 13 of the operating system) is installed on your system, you can create the program RNQMGR into library VINING using the CRTBNDRPG command:

 

 

The RNQMGR exit program manages the handling of four RPG run-time RNQ inquiry messages:

 

 

To have the RNQMGR program in library VINING called whenever an inquiry message is sent on the system, you use the Add Exit Program (ADDEXITPGM) command:

 

 

To stop the system from calling the RNQMGR program, you can use the Work with Registration Information (WRKREGINF) command:

 

 

Option 8 (Work with exit programs) from the displayed panel will then show you all exit programs that are called for inquiry messages. From here, you can then use option 4 (Remove) for the entry showing the exit program RNQMGR in library VINING.

 

When the system calls RNQMGR, a MONITOR group is first established. While it is unlikely that any inquiry message will be sent during the running of the RNQMGR program, it's better to be safe rather than sorry. We would not want an inquiry message issued from RNQMGR to cause RNQMGR to be called in order to handle its own run-time error. This would, as currently created, cause RNQMGR to be called recursively and possibly hide the underlying error(s) related to the initial inquiry message. The monitor group encompasses all statements within the program, up to setting on LR and returning. If any unexpected error is encountered while running, RNQMGR will send a message to the message queue PGMR in library QGPL indicating an internal failure. This message queue is presumably monitored by support personnel within the organization. The actual sending of the message is done in the ON-ERROR block located near the end of the source program.

 

Having established the monitor group, RNQMGR then determines if any of the four RNQ messages listed above are the cause of the exit program being called. If some other inquiry message has been sent, the program ends immediately. When the RNQMGR program ends, the i operating system will then determine if any additional exit programs are registered to the reply-handling exit point. If there are, the system will call the next exit program; if not, the system will process the current reply for the inquiry message.

 

Having verified that the inquiry message is one of the four RNQ messages of interest, RNQMGR then performs additional processing. This processing is done only after verifying the message so that we do not add unnecessary processing within the job. Remember that RNQMGR will be called for every inquiry message within a job on the system. We want to make sure the program does no unnecessary processing until we know we are in an error path of interest.

 

The next check made by RNQMGR is to determine if the job is being run by the user JOE_PGMR. JOE_PGMR represents a developer on the system, and we most likely do not want to be notifying support personnel of program failures that may be part of Joe's normal application development and testing efforts. RNQMGR examines the user profile portion of the current job name, which is available with the Program Status Data Structure (PSDS) variable JobUsr, and if the job is initiated by JOE_PGMR, RNQMGR ends.

 

In practice, it is unlikely we would want to make such a check using a hard-coded name (JOE_PGMR) within the RNQMGR program source. Every time we added a developer, removed a developer, or changed the profile name of a developer, we would need to modify, recompile, and retest the RNQMGR program. A more general-purpose approach would be to have a database file, keyed by *USRPRF name, with one record for each developer. RNQMGR could then CHAIN to the file using the user profile name and, if a record is found (for instance, a record entry for JOE_PGMR), end the program. Then any changes in the development staff could be handled with simple record maintenance to the file and not require any change to the RNQMGR exit program. This database file should be defined as USROPN and only opened after verifying that the inquiry message is one of interest. USROPN should be used in order to avoid having the program automatically open, and close, the file for every inquiry message in the job.

 

Having determined that the inquiry message is one of interest, and that the message is not related to one of the developers, RNQMGR then starts constructing a message (using variable MsgTxt) that will be sent to support personnel, notifying them of the program failure. The message first identifies the job experiencing the failure by logging the inquiry message ID (parameter MsgID, which was passed to RNQMGR by the system) and the qualified job name (determined from the PSDS, as RNQMGR is running in the same job as the program sending the inquiry message).

 

RNQMGR then uses the Receive Program Message (QMHRCVPM) API, documented here, to receive the inquiry message and the message replacement data associated with the message. All four of the RNQ messages return the same initial forty bytes of information; the first 10 bytes are the name of the RPG procedure causing the inquiry message to be sent, the next 10 bytes the name of the RPG program causing the message to be sent, then the library where the RPG program is located, and finally the RPG statement number that caused the inquiry message to be sent. Some of this replacement data will be used in subsequent processing.

 

For demonstration purposes, RNQMGR uses the two-call technique first introduced in the article "Retrieving Information, Part II" in order to ensure that all available message information is returned to the program. This two-call technique is not actually needed by the example program RNQMGR as we could simply define the receiver variable for the QMHRCVPM API with a size sufficient for these 40 bytes, but not all inquiry messages that you may want to track will be as accommodating as these four RNQ messages, so we will go with the more general-purpose approach of retrieving the message replacement data.

 

Having successfully accessed the message replacement data, RNQMGR now adds the name of the failing program to the message being constructed (MsgTxt). The program name is provided by the message replacement data associated with the message (variable PgmName of the BASED data structure RNQ_Msg). It is worth pointing out that RNQMGR is not using the name of the program sending the inquiry message. The program actually sending the message will often be a language run-time program (such as QRNXIE in the case of ILE RPG). Using the RNQ message replacement data gives RNQMGR access to the program that caused the inquiry message, not sent it.

 

RNQMGR now enters a SELECT group. The first WHEN statement determines if the current reply to the inquiry message can be changed by the exit program (a CallType of 1, 2, or 3). If so, the program enters another SELECT group.

 

Within this second SELECT group, when the program causing the inquiry message is 'ABC001', RNQMGR ensures that an RPG formatted dump is requested in response to the inquiry message. If the current message reply (parameter Reply) is not equal to 'D', RNQMGR changes the message reply to 'D', sets the message reply length to 1 byte (the length of the literal 'D'), appends to the message text stored in variable MsgTxt that a response of 'D' was made by the exit program, and sets the Reply action return code parameter (ReplyAcnCode) to the value '2'. A Reply action return code value of 2 tells the system that the current inquiry message reply should be replaced by the new value of the Reply parameter.

 

If the program causing the inquiry message is not ABC001 (the OTHER statement of the inner select group), RNQMGR ensures that the program is canceled. If the current message reply is not equal to 'C', RNQMGR appends to the message text stored in variable MsgTxt the response that was found (variable Reply), indicates that a response of 'C' was requested by the exit program, changes the message reply to 'C', sets the message reply length to 1 byte, and sets the Reply action return code parameter to the value of '2' (the reply provided by RNQMGR should replace the current inquiry message reply). In addition, RNQMGR determines if the initial inquiry message response was entered by the user (a call type value of 1) as opposed to being a default value. If the user explicitly entered the response (as opposed to simply using the Enter key when the inquiry message was shown), RNQMGR appends the text 'Initial reply was not provided by the system'.

 

If RNQMGR is not able to change the message reply (the OTHER statement of the outer select group), RNQMGR appends to the MsgTxt variable the call type encountered and the message reply being used by the system. This is to document to the support personnel when RNQMGR is unable to alter the reply to the inquiry message.

 

RNQMGR then does some general cleanup: deallocates any storage previously allocated when receiving the inquiry message replacement data, appends error text to the MsgTxt variable if any anticipated errors were encountered, and sends a message containing the MsgTxt variable to the message queue PGMR in library QGPL.

 

The program then ends.

 

Hopefully, this example program gives you a rough idea of the things you can do in terms of being aware of inquiry messages that may be occurring on your system, ways to change the responses being made to these inquiry messages, and some of the considerations you will want to keep in mind in order to minimize the impact of running an exit program within your jobs. When your exit program receives control, only your imagination (and of course your authorization!) limit what you can do within the exit program.

 

One usage note should be made prior to concluding this article. When you are developing a reply-handling exit program, be aware that debug breakpoints within the exit program will not be processed. Any breakpoints you set in the exit program will be ignored, and, after the exit program completes, the message CPF195A (Breakpoint already run when notification received) will be found in the job log. When developing your reply-handling exit program, you may find the RPG DSPLY opcode to be your friend. Additional usage notes can be found in the exit point documentation.

 

In the next article, we'll look at another exit program capability: the inquiry-handling exit point QIBM_QMH_HDL_INQEXT. This exit, available only with V6R1, allows your exit program to run and reply to an inquiry message, preventing the end user from even seeing the inquiry message.