This installment of Carsten Flensburg's APIs by Example not only shows how to use the Message Handling APIs Retrieve Message (QMHRTVM), Move Program Message (QMHMOVPM), and Receive Program Message (QMHRCVPM), but it also offers a great way to enhance the system request menu.

The system request menu enhancement is comprised of exit program CBX108 (as well as service program CBX108S) that is called by the registered exit point, which in this case is the presystem request exit. A third program, CL program CBX108C, generates example message file SRQMSGF, which contains the additional system request menu options.

CBX108 enhances the system request menu facility by retrieving, formatting, and executing additional menu options from the message file SRQMSGF. The new options can either be formatted to accept a menu item number or a menu item number and a string. For example, one of the messages added to file SRQMSGF by CBX108C is this line:

SRQ0021 'WRKJOB'

When the user selects option 21 in the system request menu, the CBX108 will execute command WRKJOB. Another message added to the example file is this:

SRQ0032 'GO MENU(&1)

In this case, when the user enters menu option 32 followed by "MAIN", the command GO MENU(MAIN) will be run.

If an error occurs during processing of the command, the error message text is displayed in a pop-up window and an alarm sound is sent to the terminal session.

In the file SRQMSGF, option '00' specifies that WRKMSGD will run, which lets you manage SRQMSGF. Menu options in the range 20-99, excluding 80 and 90, are available to add your own system request menu options. Note, however, that the added menu options are not displayed on the system request menu panel.

Once you've compiled the three programs and run CL program CBX108C, you can enable or disable CBX108 or any other registered exit programs with utility SetPrfExit, which appeared in the September 4 issue of this newsletter, which you can read at http://www.iseriesnetwork.com/article.cfm?ID=17221.

The following are the APIs and functions used in CBX108 and CBX108S:

Retrieve Message (QMHRTVM) API
This API retrieves the message description of a predefined message that was created with the Add Message Description (ADDMSGD) command.
http://publib.boulder.ibm.com/iseries/v5r2/ic2924/info/apis/QMHRTVM.htm

Move Program Message (QMHMOVPM) API
This API moves messages from a call message queue in the call stack to the call message queue of an earlier call stack entry.
http://publib.boulder.ibm.com/iseries/v5r2/ic2924/info/apis/qmhmovpm.htm

Receive Program Message (QMHRCVPM) API
This receives a message from a call message queue or external message queue and returns information describing the message.
http://publib.boulder.ibm.com/iseries/v5r2/ic2924/info/apis/QMHRCVPM.HTM

Display Long Text (QUILNGTX) API
This displays a pop-up window containing a string that is passed to it.
http://publib.boulder.ibm.com/iseries/v5r2/ic2924/info/apis/quilngtx.htm

Generate a Beep (QsnBeep) API
This API generates a beep in the current terminal session.

Tokenize string (strtok)
This API reads a string and returns for each call the found substrings one by one. A second parameter defines the delimiter(s) used to identify the substrings http://publib.boulder.ibm.com/iseries/v5r2/ic2924/books/c4156071.pdf.

The source code for the three programs are available here:
http://www.iseriesnetwork.com/noderesources/code/clubtechcode/EnhancedSysReqMenu.zip

The above source code was written by Carsten Flensburg. For questions regarding this tip, contact Carsten at mailto:flensburg@novasol.dk.