AS/400-iSeries Starter Kit

What makes the OS/400 operating system tick? You could argue that messages are really at the heart of the AS/400. The system uses messages to communicate between processes. It sends messages noting the completion of jobs or updating the status of ongoing jobs. Messages tell when a job needs some attention or intervention. The computer dispatches messages to a problem log so the operator can analyze any problems the system may be experiencing. You send requests in the form of messages to the command processor when you execute AS/400 commands. OfficeVision uses a message to sound an alarm when a calendar event is imminent. You can design screens and reports that use messages instead of constants, thus enabling multilingual support. And, of course, users can send impromptu messages to and receive them from other workstation users on the system.

With hundreds of messages flying around your computer at any given moment, it's important to have some means of catching those that relate to you -- and that might require some action. IBM provides several facilities to organize and handle messages, and you can create programs to further define how to process messages. In this chapter, I'll explore three methods of message processing: the system reply list, break handling programs, and default replies.

The system reply list lets you specify that the operating system is to respond automatically to certain predefined inquiry messages without requiring that the user reply to them. A break handling program lets you receive messages and process them according to their content. The reply list and the break handling program have similar functions and can, under some conditions, accomplish the same result. The reply list tends to be easier to implement, while a break handling program can be much more flexible in the way it handles different kinds of messages. The third message handling technique, the default reply, lets you predefine an action that the computer will take when it encounters a specific message; the reply becomes a built-in part of the message description.

Return Reply Requested

The general concept of the system reply list is quite simple. The reply list primarily consists of message identifiers and reply values for each message. There is only one reply list on the system (hence the official name: system reply list). When a job using the reply list encounters a predefined inquiry message, OS/400 searches the reply list for an entry that matches the message ID (and the comparison data, which we'll cover later). When a matching entry exists, the system sends the listed reply without intervention from the user or the system operator. When the system finds no match, it sends the message to the user (for interactive jobs) or to the system operator (for batch jobs).

A job does not automatically use the system reply list -- you must specify that the reply list will handle inquiry messages. To do this, indicate INQMSGRPY(*SYSRPYL) within any of the following CL commands:

• BCHJOB (Batch Job)

• SBMJOB (Submit Job)

• CHGJOB (Change Job)

• CRTJOBD (Create Job Description)

• CHGJOBD (Change Job Description)

IBM ships the AS/400 with the system reply list already defined as illustrated in Figure 8.1. This predefined reply list issues a "D" (job dump) reply for inquiry messages that indicate a program failure. Note that the reply list uses the same convention as the MONMSG (Monitor Message) CL command for indicating generic ranges of messages; for example, "RPG0000" matches all messages that begin with the letters "RPG," from RPG0001 through RPG9999. You can modify the supplied reply list by adding your own entries using the following CL commands:

• WRKRPYLE (Work with Reply List Entries)

• ADDRPYLE (Add Reply List Entry)

• CHGRPYLE (Change Reply List Entry)

• RMVRPYLE (Remove Reply List Entry)

Figure 8.2 lists some possibilities to consider for your own reply list. Each entry consists of a unique sequence number (SEQNBR), a message identifier (MSGID), optional comparison data (CMPDTA) and starting position (START), a reply value (RPY), and a dump attribute (DUMP). Let's look at each component individually.

A Table of Matches

The system searches the reply list in ascending sequence number order. Therefore, if you have two list entries that would satisfy a match condition, the system uses the one with the lowest sequence number. The message identifier can indicate a specific message (e.g., RPG1241) or a range of messages (e.g., RPG1200 for any RPG messages from RPG1201 through RPG1299), or you can use *ANY as the message identifier for an entry that will match any inquiry message, regardless of its identifier. The reply list message identifiers are independent of the message files. If you have two message files with a message ID USR9876, for example (usually not a good idea), the system reply list treats both messages the same.

Use the *ANY message identifier with great care. It is a catch-all entry that ensures the system reply list handles all messages, regardless of their message identifier. If you use it, it should be at the end of your reply list, with sequence number 9999. You should also be confident that the reply in the entry will be appropriate for any error condition that might occur. If the system reply list gets control of any message other than the listed ones, it performs a dump and then replies to the message with the default reply from the message description. If you don't use *ANY, the system sends unmonitored messages to the operator.

The comparison data is an optional component of the reply list. You use comparison values when you want to send different replies for the same message, according to the contents of the message data. The format of the message data is defined when you or IBM creates the message. To look at the format, use the DSPMSGD (Display Message Descriptions) command. When a reply list entry contains comparison values, the system compares the values with the message data from the inquiry message. If you indicate a starting position in the system reply list, the comparison begins at that position in the message data. If the message data comparison value matches the list entry comparison value, the system uses the list entry to reply to the message; otherwise, it continues to search the list. For example, Figure 8.2 shows three list entries for the CPA4002 (Align forms) message. When the system encounters this message, it checks the message data for the name of the printer device. If the device name matches either the "PRT3816" or "PRTHPLASER" comparison data, the system automatically replies with the "I" (Ignore) response; otherwise, it requires the user or the system operator to respond to the message.

You use the reply value portion of the list entry to indicate how the system should handle the message in this entry. Your three choices are:

• Indicate a specific reply (up to 32 characters) that the system automatically sends back to the job in response to the message (e.g., I, R, D, and G in Figure 8.2).

• Use *DFT (Default) to have the system send the message default reply from the message description.

• Use *RQD (Required) to require the user or system operator to respond to the message, just as if the job were not using the reply list.

The dump attribute in the system reply list tells the system whether or not to perform a job dump when it encounters the message matching this entry. Specify DUMP(*YES) or DUMP(*NO) for the list entry. You may request a job dump no matter what you specified for a reply value. The system dumps the job before it replies to the message and returns control to the program that originated the message. The dump then serves as a snapshot of the conditions that caused a particular inquiry message to appear.

Although the reply list is a system-wide entity, you can use it with a narrower focus. Figure 8.3 shows portions of a CL program that temporarily changes the system reply list and then uses the changed list for message handling, checking for certain inquiry messages, and issuing replies appropriate to the program. At the end, the program returns the system reply list to its original condition. You should probably limit this approach to programs run on a dedicated or at least a fairly quiet system. Since the program temporarily changes the system reply list, any other jobs that use the reply list may use the changed reply list while this program is active. However, this technique does work well for such tasks as software installation and nighttime unattended operations.

Give Me a Break Message

Another means of processing messages is to use a break handling program, which processes messages arriving at a message queue in *BREAK mode. IBM supplies a default break handling program; it's the same command processing program used by the DSPMSG (Display Messages) command. But you can write your own break handling program if you want break messages to do more than just interrupt your normal work with the Display Messages screen.

Both the system reply list and a break handling program customize your shop's method of handling messages that arrive on a message queue, but there are several differences. The system reply list handles only inquiry messages, while a break handler can process any type of message, such as a completion message or an informational message. The system reply list has a specific purpose: to send a reply back to a job in response to a specific message. The break handler's function, on the other hand, is limited only by your programming ability. It can send customized replies for inquiry messages, it can convert messages to status messages, it can process command request messages, it can initiate a conversational mode of messaging between workstations, it can redirect messages to another message queue -- it can perform any number of functions. Unlike the system reply list, the break handler interrupts the job in which the message occurs and processes the message; it then returns control to the job. The interruption can, however, be transparent to the user.

Like the reply list, a break handler does not take control of break messages unless you first tell it to do so. To turn control over to a break handling program, use the following CL command:

CHGMSGQ MSGQ(library/msgq_name) +

        DLVRY(*BREAK)           +

        PGM(program_name)       +

        SEV(severity_code)

OS/400 calls the break handler if a message of high enough severity reaches the message queue. If you use a break handler in a job that is already using the system reply list, the reply list will get control of the messages first, and it will pass to the break handler only those messages it cannot process.

Take a Break

Figure 8.4 shows a sample break handling program. To make the break handler work, OS/400 passes it three arguments:

• the name of the message queue

• the library containing the message queue

• the reference key of the received message

Figure 8.5 shows a portion of an initial program that puts a break handler into action. The initial program first displays all messages that exist in a user's message queue, and then it clears all but unanswered messages from the queue and activates the break handling program. Note that the initial program also checks whether the user is the system operator; if so, it activates the break handler for the system operator message queue.

It's Your Own Default

One of the easiest methods of processing message replies automatically is also one of the most often overlooked. The message descriptions for inquiry or notify messages can contain default replies, which you can tell the system to use when the message occurs. The default reply must be among the valid replies for the message. You specify the message's default reply using either the ADDMSGD (Add Message Description) or CHGMSGD (Change Message Description) command. You can display a message's default reply using the DSPMSGD command. You can also use WRKMSGD (Work with Message Descriptions) to manage message descriptions.

The default reply is used under the following circumstances:

• when you use the system reply list and the list entry's reply for the message is *DFT

• when you have changed the delivery mode of the receiving message queue to *DFT, using the CHGMSGQ (Change Message Queue) command

No messages are put in a message queue when the queue is in *DFT delivery mode; informational messages are ignored. Messages will be logged, however, in the system history log (QHST).

You can easily set up an unattended environment for your computer to use every night by having your system operator execute the following command daily when signing off:

CHGMSGQ MSGQ(QSYSOPR) DLVRY(*DFT)

Your system will then use default replies instead of sending messages to an absent system operator. This technique may prevent your overnight batch processing from hanging up because of an unexpected error condition. You should be careful, however, to ensure the suitability of the default replies for any messages that might be sent to the queue. You might also consider including the CHGMSGQ command within key CL programs, such as unattended backup procedures or program installation procedures, for which default replies may be appropriate. Another good use for default replies is to have one message queue handle all printer messages. By defining default replies to these messages and placing that queue in *DFT delivery mode, you can have the system automatically respond to forms loading and alignment messages.