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 
(http://www.the400group.com).


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.

[report a broken link by clicking here]