Message Handling APIs

The Message Handling APIs let your applications work with iSeries^(TM) messages. They allow you to do the following:

• Send messages to users or programs
• Receive messages from a message queue
• Handle errors
• Return message and message queue information
• Return message description and message file information

Before using the message handling APIs, read the following material:

• Message Handling Terms and Concepts. This section briefly describes the elements of iSeries messages and message handling.
• CL Programming topic. For complete background information, see the sections that discuss defining and working with messages.

The Message Handling APIs are:

• Change Exception Message (QMHCHGEM) changes an exception message on a call message queue. This API allows the current program to perform a variety of actions on an exception message that was sent to its caller, a previous caller, or itself.
• Control Job Log Output (QMHCTLJL) controls the production of a job log when the related job ends or when the job message queue becomes full and the print-wrap option is in effect for the job.
• List Job Log Messages (QMHLJOBL) lists messages from the job message queue of a job. This function gets the requested message information and returns it in a user space in the format specified in the parameter list.
• List Nonprogram Messages (QMHLSTM) lists messages from one or two nonprogram message queues. This function gets the requested message information and returns it in a user space in the format specified in the parameter list.
• Move Program Messages (QMHMOVPM) moves messages from one call message queue to the message queue of an earlier call stack entry in the call stack. This is especially useful for error handling.
• Open List of Job Log Messages (QGYOLJBL) lists messages from a job log. Returned messages are sorted by their sending date and time unless the message being listed is a reply message to an inquiry, a sender's copy, or a notify type of message.
• Open List of Messages (QGYOLMSG) provides information on messages for the current user, a specific user, or one specific nonprogram message queue.
• Promote Message (QMHPRMM) promotes an escape or status message that was sent to a call stack entry. That is, the message is handled and replaced with a new escape or status message. You may promote an escape message to another escape message or to a status message. You may promote a status message to an escape message or to another status message.
• Receive Nonprogram Message (QMHRCVM) receives a message from a nonprogram message queue, providing information about the sender of the message as well as the message itself. This API is similar in function to the Receive Message (RCVMSG) command with the MSGQ parameter.
• Receive Program Message (QMHRCVPM) receives a message from a call message queue, and provides information about the sender of the message as well as the message itself. This API is similar in function to the Receive Message (RCVMSG) command with the PGMQ parameter.
• Remove Nonprogram Messages (QMHRMVM) removes messages from nonprogram message queues. This API is similar in function to the Remove Message (RMVMSG) command with the MSGQ parameter.
• Remove Program Messages (QMHRMVPM) removes messages from call message queues. This API is similar in function to the Remove Message (RMVMSG) command with the PGMQ parameter.
• Resend Escape Message (QMHRSNEM) resends an escape message from one call message queue to the message queue of the previous call stack entry in the call stack.
• Retrieve Message (QMHRTVM) retrieves the message text and other elements of a predefined message stored in a message file on your system. This API is similar to the Retrieve Message (RTVMSG) command.
• Retrieve Message File Attributes (QMHRMFAT) retrieves information about the attributes of a message file.
• Retrieve Nonprogram Message Queue Attributes (QMHRMQAT) provides information about the attributes of a nonprogram message queue.
• Retrieve Request Message (QMHRTVRQ) retrieves request messages from the current job's call message queue.
• Send Break Message (QMHSNDBM) sends a message to a work station for immediate display, interrupting the work station user's task. You can use break messages to warn users of impending system outages and the like. This API is similar in function to the Send Break Message (SNDBRKMSG) command.
• Send Nonprogram Message (QMHSNDM) sends a message to a system user or a message queue that is not associated with a specific program. This API is similar in function to the Send Program Message (SNDPGMMSG) command with the TOMSGQ parameter.
• Send Program Message (QMHSNDPM) sends a message to the message queue of a call stack entry in the call stack. This API is similar in function to the Send Program Message (SNDPGMMSG) command with the TOPGMQ parameter.
• Send Reply Message (QMHSNDRM) sends a response to an inquiry message. This API is similar in function to the Send Reply (SNDRPY) command.
• Send Scope Message (QMHSNDSM) Sends a scope message that allows a user to specify a program to run when your program or job is completed.

The Message Handling exit programs are:

• Break Handling provides the capability of handling messages that arrive at a message queue that is in *BREAK mode.
• Default Handling provides a default message handling action that can be used if the program that is signaled an escape message does not monitor for or handle the escape message.
• Reply Handling is called when a reply is sent to an inquiry message.