Here's the situation: You are writing an RPG or some other high-level language (HLL) program. You are programming a portion of the program that will probably be long running, for instance, a search procedure that is looking for a string of characters within the last names stored in the 100,000-record customer master file. This is a perfect time for a status message -- that is, a message at the bottom of the screen informing the user that the operation may take a moment. But how can you set up such a message quickly?
Status messages, the easy way
The traditional way of sending a status message is to use the Send Program Message (SNDPGMMSG) CL command or one of the message APIs. But, both of these approaches require external program calls and can be overly complicated to implement.
On the other hand, the Dispatch Message (CEEMOUT) API provides a quick and easy way of sending a "status" message (actually, the message is sent more like a notify message). And, the CEEMOUT API is a bindable API (i.e., it is a procedure), so calls to it are extremely fast.
Understanding CEEMOUT's interface
The interface of the CEEMOUT API is simple. It accepts the following two required parameters and a third optional parameter:
Message: A variable-length character string containing the message you want displayed. However, you do not need to pass a variable-length field. Any fixed-length field will do. There is no maximum length; however, for displaying status messages, the practical limit is 78 characters since the system displays the message on the message line at the bottom of the screen. Note: Since the system uses message ID CPF9898 to send the message, you do not need to put a period on the end of the message (i.e., CPF9898 has a period).
Destination code. A 4-byte binary integer that controls how the system displays the message. Specify a 1 to display the message on the message line and the job log. Specify 2 to record the message only in the job log.
Feedback. A 12-byte feedback code (i.e., condition token). This is an omissible parameter. Use *Omit in RPG to omit.
The CEEMOUT API requires the use operational descriptors, which we will tackle next time. We'll also discuss a code example.
-----------------------------------
About the author: Ron Turull is editor of Inside Version 5. He has more than 20 years' experience programming for and managing AS/400-iSeries systems.
