Quick and easy status messages with the CEEMOUT API
By Ron Turull
This article originally appeared in the May 2000 edition of Inside Version 4 and is provided courtesy of The 400 Group..
Here's the situation: You are writing an RPG or some other 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 -- a message at the bottom of the screen informing the user that the operation may take a moment. But how do you send one quickly?
Status messages, the easy way
The traditional way of sending a status message is to use the SNDPGMMSG CL command or one of the message APIs. But both approaches require external program calls and can be overly complicated to implement.
The dispatch message API (CEEMOUT) is a quick and easy way to send a "status" message (the message is actually 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 two or three parameters:
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.
You must use operational descriptors
Because the message parameter can accept different types of strings, you must specify operational descriptors on the call to the CEEMOUT API. This lets the API know the exact type of character string passed, as well as the length.
For languages that support parameter-level descriptors (i.e., the ability to specify operational descriptors on a parameter by parameter basis), only the message parameter needs a descriptor.
Not a status message, but not a notify message either
Messages sent with the CEEMOUT API are not true status messages. The CEEMOUT API not only displays the message at the bottom of the screen, but it also logs it in the job's job log as an informational message. (And if you specify a 2 for the destination parameter, the message is only recorded in the job log -- it is not displayed on the screen at all).
This behavior is reminiscent of notify messages. Often, the program receiving a notify message (e.g., the PDM's command-line processor) will display the message on the message line and record the message in the job log. However, the system records the message in the job log as a true notify message and not an informational message, as is the case when a message is sent via the CEEMOUT API.
The bottom line is this: If you don't mind these extraneous messages in the job log, the CEEMOUT API is a great way to send "pseudo-status" messages.