Message Handling APIs

The message handling APIs can be used to work with IBM^® i messages. They allow you to perform the following tasks:

• 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 you use the message handling APIs, read the following topics:

• Message Handling Terms and Concepts. This topic briefly describes the elements of IBM i messages and message handling.
• Control language. For complete background information, see the topic collection about 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 History Log Messages (QMHOLHST) provides information about messages that were sent to the QHST message queue.
• 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 workstation for immediate display, interrupting the workstation 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.
• Inquiry Handling (QIBM_QMH_HDL_INQEXT) is called in an interactive job when an inquiry message has been sent to *EXT and the job would be interrupted by the Display Program Messages screen to obtain a reply. The exit program can send a reply to the inquiry message, so the interactive user is not interrupted to provide a reply to the inquiry message.
• Reply Handling (QIBM_QMH_REPLY_INQ) is called when a reply is sent to an inquiry message.

---

[ Back to top | APIs by category ]