Feedback: An omissible 12-byte feedback code.
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.
In RPG, operational descriptors are an all-or-nothing feature. To specify that descriptors are to be used, you must either specify the OpDesc keyword on the procedure prototype, or use the D extender on the CallB op-code. Either way, the compiler will then automatically build operational descriptors for all of the parameters that are a part of the call operation.
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, 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.
Sample code: How to use the CEEMOUT API
This CEEMOUNT program illustrates the use of the CEEMOUT API. The program calls the API using the CallB op-code with a D extender to ensure that the compiler generates operational descriptors. The message is sent prior to entering a long operation in the program (in this case, a dummy-loop performing inane work for illustrative purposes).
To make sending these "status" messages even easier, the sample program also defines a SndStsMsg procedure that wraps up the CEEMOUT API. The interface to the SndStsMsg procedure is simpler than the interface of the CEEMOUT API. The single parameter Msg is passed by value so you can just code a constant or literal when calling the procedure.
Tip: Put the SndStsMsg procedure in a separate module or service program. This way, when a program needs to use it, all you need to do is link the program with the module or service program. To save yourself some more time, put the procedure prototype in a /COPY member.
-----------------------------------
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.
