Learn how to handle specific inquiry messages.

The recent series of articles on watches prompted quite a bit more email than I have received on any previous topic. Several of these notes were related to watching for a specific set of messages and have prompted this column.

While the earlier articles gave examples of automating certain application processing--managing daylight saving time transitions, re-enabling disabled user profiles, purging deleted records--several of you have implemented watches in order to determine when program failures occur. That is, you are watching for messages such as these:

• RNQ0100--The length or start position is out of range for the string operation.
• RNQ0102--There's been an attempt to divide by 0.
• RNQ0103--The target for a numeric operation is too small to hold the result.
• RNQ0121--An array index is out of range.

These watches are written with the intent of determining when unexpected program failures occur and the end-users neglect to mention it to you. Watches can certainly be used for these types of error conditions, but other approaches may be better-suited. The reason for looking at alternative solutions is related to the four listed messages (and several more RNQ messages that can be found in message file QRNXMSG) all being inquiry messages. And while we may hope that end-users always reply to these messages with a C (Cancel), you just know someone is going to use option G (Continue processing at *GETIN). Perhaps you know how your applications will behave in response to a G, but I anticipate for most shops it's an unknown--and, as static variables are left in their last used state with G, a potentially dangerous unknown. Further, you may have a program (ABC001) that is intermittently experiencing a failure, such as RNQ0100, and it is proving very difficult to re-create the problem. Wouldn't it be nice to tell all the users to reply D (RPG formatted dump) if RNQ0100 is encountered when running that particular program? Watches are ideal for asynchronous processing based on a message being sent, but these inquiry message-related scenarios call for more.

One alternative, if you are using ILE, is to implement a global MONITOR within your application programs. The MONITOR would prevent the inquiry message from being sent, and the ON-ERROR logic could notify the support staff of the program failure with an optional dump of the program when needed. If you're not using ILE today, then you could implement a *PSSR subroutine to trap these types of errors and again notify your support staff of the problem. These approaches, however, as I'm sure you are well aware, have one drawback. You need to go into each program and make the necessary changes. And it's the rare development shop that has the resources to make these types of changes while also addressing the functional needs of the business.

A second approach might be to use the system reply list and have the system automatically respond with a C to the RNQ messages of interest. This can work, but many users find that the system reply list does not provide sufficient granularity in terms of different replies for different users with different messages. That is, it might be OK for end-users to use the system reply list for the RNQ messages, but you may have pre-existing, non-RNQ reply list entries that conflict with various users of your system. To have everyone using the system reply list may not be manageable due to these "other" messages.

What would be nice is if a way existed to trap these error situations, external to the failing program, so that you do not have to change the application, but in such a way that you can examine who is replying and prevent selected users from making potentially dangerous responses, such as a G. There is, needless to say, a way to do this. In this article, you will be introduced to an exit point in the system known as reply-handling. A reply-handling exit program is called when a response to an inquiry message is made and, among other capabilities, allows your program to change the end-user's reply. The exit point has several features worth pointing out.

There is no fixed limit on the number of exit programs that you can register. You do not have to write one huge program to handle every inquiry message of interest. You can write  exit programs to handle specific situations and control the order in which your exit programs are called by the system using the program number (PGMNBR) associated with the exit program when you register it using the Add Exit Program (ADDEXITPGM) command. Your exit program, if called for an inquiry message the program is not interested in, can simply return, and the system then calls the next exit program.

The exit program runs in the job replying to the inquiry message. Your exit program is not running in a separate job as watch programs do. Running in the same job allows your program to easily determine the environment it is running in and, if appropriate, change the environment. Running in the same job does, however, mean that an error in your exit program, or any long and lengthy processing, will impact the end-user.

The exit program runs after any system reply list processing is performed and after the system has validated the reply. This allows you to use the system reply list to set default responses for users and have your exit program focus on the exceptions.

The reply-handling exit point has existed on the system since V5R2. This should allow many of you to take advantage of this capability immediately.

In a subsequent article, you will see another exit point in the system: inquiry-handling. This exit point allows your program to intercept the inquiry message prior to the end-user even seeing the message and respond to the message directly. This exit point is available, however, only with V6R1, which is why we'll start with the reply-handling exit point.

The reply-handling exit point is documented here and defines eight parameters that are passed to your program. The parameters are shown below.

Required Parameter Group:

   Exit Point Name: QIBM_QMH_REPLY_INQ

   Exit Point Format Name: RPYI0100

The first parameter, Type of call, is a 4-byte binary input value that identifies why the exit program has been called. There are currently eight possible values.

• 0--Reply notification: the exit program is informed of a reply made by a previous exit program. The current exit program cannot reject or replace this earlier decision.
• 1--Reply validation requested: the exit program can accept, reject, or replace the reply entered by the user.
• 2--Default reply validation requested: the exit program can accept, reject, or replace the reply entered by the system.
• 3--Default reply notification: the exit program can accept or replace the reply entered by the system.
• 4--Reply rejected notification: the exit program is informed that a reply previously seen, and accepted by the exit program, has been rejected by a subsequent exit program.
• 5--Replaced reply not valid: the exit program is informed that the reply used is not valid.
• 6--Reply replaced notification: the exit program is informed that a reply previously seen, and accepted by the exit program, has been changed by a subsequent exit program
• 7--Reply cannot be sent notification: An error situation has been encountered.

As you can see, several of the Type of call values are associated with allowing an exit program to be aware of the actions of other exit programs. These values will not be used very much in the RNQ handler but for other applications may be quite important. For RNQ-type messages, Type of call values 1, 2, and 3 will be the focus.

The second parameter, Qualified message queue name, is a 20-byte character input value identifying the message queue and library containing the inquiry message. The special value *EXT is used to represent a job's external message queue. *EXT is where you would expect the RNQ type messages to appear.

The third parameter, Message key, is a 4-byte character input value identifying the specific message on the message queue.

The fourth parameter, Message identifier, is a 7-byte character input value providing the message identifier. This is where you would see message identifiers such as RNQ0100, RNQ0103, etc. This parameter is set to blanks if an impromptu inquiry message is being replied to.

The fifth parameter, Reply, is a variable-length character input/output value where your exit program can supply a value to replace the value originally used when replying to the message. The maximum length of this parameter is 132 bytes. This parameter is defined as input/output as the system presets the parameter to the value entered by the user (or set by the system).

The sixth parameter, Length of the reply, is a 4-byte binary input/output value where your exit program indicates the length of the reply provided for the fifth parameter. This parameter is defined as input/output as the system presets the parameter to the length of the reply given you in the fifth parameter. If the exit program replaces the value of the fifth parameter with a longer or shorter replacement value, then the program must also update this parameter in order to reflect the actual length of the new reply. The special value of 0 can be used to have the system use the default value for the inquiry message.

The seventh parameter, CCSID of the reply, is a 4-byte binary input/output value where your exit program can specify the CCSID used for the value of the fifth parameter. The special value 0 indicates that the system should use the job CCSID. This parameter is defined as input/output as the system presets the value to 65535: use the value of the fifth parameter as is with no CCSID conversion.

The eighth parameter, Reply action return code, is a 4-byte binary output value where your exit program indicates if the current reply should be rejected (0), accepted (1), or replaced (2).

Below is the RPG prototype for a reply-handling exit program named RNQMGR.

dRNQMgr           pr                  extpgm('RNQMGR') 

d CallType                      10i 0 const            

d QualMsgQ                      20    const            

d MsgKey                         4    const            

d MsgID                          7    const            

d Reply                        132    options(*varsize)

d LenReply                      10i 0                   

d ReplyCCSID                    10i 0                  

d ReplyAcnCode                  10i 0                  

Subsequent articles will fill in details such as these:

• Changing the reply to a RNQ message--In general changing any non-C reply value to a C. For program ABC001, changing any reply value to a D.
• Obtaining the name of the program experiencing the RNQ failure
• Sending appropriate messages to a message queue that support personnel monitor for notification of application failures. These messages will identify the failing program and job, indicate if an RPG dump was taken, indicate if a non-default reply value was changed by the exit program.

Meanwhile, if you have other API questions, send them to me at This email address is being protected from spambots. You need JavaScript enabled to view it.. I'll see what I can do about answering your burning questions in future columns.

Bruce Vining is president and co-founder of Bruce Vining Services, LLC, a firm providing contract programming and consulting services to the System i community. He began his career in 1979 as an IBM Systems Engineer in St. Louis, Missouri, and then transferred to Rochester, Minnesota, in 1985, where he continues to reside. From 1992 until leaving IBM in 2007, Bruce was a member of the System Design Control Group responsible for OS/400 and i5/OS areas such as System APIs, Globalization, and Software Serviceability. He is also the designer of Control Language for Files (CLF).A frequent speaker and writer, Bruce can be reached at This email address is being protected from spambots. You need JavaScript enabled to view it.. 

---

MC Press books written by Bruce Vining available now on the MC Press Bookstore.

		IBM System i APIs at Work Leverage the power of APIs with this definitive resource. List Price $89.95 Now On Sale

Also Read

The API Corner: Moving Jobs Within and Across Job Queues

The API Corner: What Time Zone Do You Want That Date and Time In?

The API Corner: How Do You Want That Date and Time?