Tip

Quick and easy status messages with the CEEMOUT API

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.


This was first published in May 2000

There are Comments. Add yours.

 
TIP: Want to include a code block in your comment? Use <pre> or <code> tags around the desired text. Ex: <code>insert code</code>

REGISTER or login:

Forgot Password?
By submitting you agree to receive email from TechTarget and its partners. If you reside outside of the United States, you consent to having your personal data transferred to and processed in the United States. Privacy
Sort by: OldestNewest

Forgot Password?

No problem! Submit your e-mail address below. We'll send you an email containing your password.

Your password has been sent to:

Disclaimer: Our Tips Exchange is a forum for you to share technical advice and expertise with your peers and to learn from other enterprise IT professionals. TechTarget provides the infrastructure to facilitate this sharing of information. However, we cannot guarantee the accuracy or validity of the material submitted. You agree that your use of the Ask The Expert services and your reliance on any questions, answers, information or other materials received through this Web site is at your own risk.