This article describes the basic elements of iSeries messages and message handling, including:
For details about these topics, see the CL Programming topic.
The i5/OS program uses two basic kinds of messages, immediate and predefined. Immediate messages, also known as impromptu messages, are created by the sender when they are sent. They consist completely of text that the sender supplies. They do not have identifying codes like CPF2469, and they are not stored in message files on the system.
In contrast, predefined messages are created and exist outside the programs that use them. Each predefined message has its own message description, which is stored in a message file (object type *MSGF) on the system. The message description includes the message text and other items, such as message help, the default reply for the message, and its severity level.
Each message description has its own message identifier. The message identifier is a 7-character code, such as CPF2469, that refers to the message description as a whole. It is displayed with the text of the message and lets programs refer to the message easily. The term message identifier is usually abbreviated to MSGID in items such as CL commands.
Predefined messages have two types of text, message text and message help. The message text is the version of the predefined message that is first displayed at a work station or logged in a job log. The message text is also known as first-level text. It briefly describes a condition. Message help, also known as second-level text, is available to the user on request. It usually describes the cause of the condition and details any corrective action the user should take.
The message text and message help for predefined messages can consist of only constant text, only substitution variables, or both constant text and substitution variables. are variables for items such as file names in the message text or message help. They allow the message to better describe the recipient's individual circumstances. Substitution variables are also known as replacement data. Substitution variables The specific values you assign to these variables are called message data.
When either an immediate or predefined message is sent, the command or API used to send it usually assigns it a message key. The message key, also called the message reference key, is a unique string of characters that identifies a particular instance of a message in a queue. (In contrast, a message identifier identifies a message as it is stored in a message file, not as it is sent.) You can use the message key to refer to a specific instance of a message in order to move, receive, reply to, resend, or remove it.
The i5/OS program divides messages into types according to their use. These message types are categories based on the message's purpose. The sender of the message determines its type when sending the message. The message handling APIs use these message types in defining and working with messages:
Completion (*COMP). Reports the successful completion of a task.
Diagnostic (*DIAG). Describes errors in processes or input data. When an error occurs, a program usually sends an escape message, which causes the task to end abnormally. One or more diagnostic messages can be sent before the escape message to describe the error.
Escape (*ESCAPE). Indicates a condition causing a program to end abnormally, without completing its work.
Exception (*EXCP). Indicates a condition causing a program to end abnormally, without completing its work. An exception message can be either an escape or a notify message. The exception message type and the special value *EXCP are used only with the Receive Program Message (QMHRCVPM) API.
Informational (*INFO). Conveys information without asking for a reply.
Inquiry (*INQ). Conveys information and asks for a reply.
Notify (*NOTIFY). Describes a condition in the sending program requiring corrective action or a reply.
Reply (*RPY). Responds to an inquiry or notify message.
Request (*RQS). Requests a function from the receiving program.
Sender's copy (*COPY). Is a copy of an inquiry or notify message. This copy is kept by the sender of the inquiry or notify message.
Scope (*SCOPE). Specifies a program to run when the program this message is sent to completes. If the message is sent to *EXT the program is to run when the job completes.
Status (*STATUS). Describes the status of work being done by a program.
All iSeries messages are sent to message queues. The system provides the following message queues:
Any thread in a multithreaded job can send messages to the external message queue. Each thread can receive or remove only those messages sent to the external message queue from that thread.
A call message queue is also known as a program message queue. However, in the ILE model, you can call procedures as well as programs. Both ILE procedure message queues and OPM program message queues are referred to as call message queues. A multithreaded job has a separate set of call message queues for each thread that is running in the job. Each thread can access only the messages for the call message queues within its own thread; messages cannot be sent to, received from, or removed from call message queues in other threads.
Note: An ILE procedure has an associated call message queue only if the related compiler does not place the procedure inline. A inline procedure does not have a call message queue, and because of this, cannot be referenced on any message handler API. For example, you cannot send a message to an inline procedure by specifying the name of that inline procedure.
Note: A message sent to a message queue remains on the queue until you use a command or API to remove it from the queue or move it to another queue. Removing a message from a message queue deletes that one instance of the message from the system. After removal, you can no longer receive or otherwise work with that instance of the message. However, other instances of the message might still be available in the same or different message queues. The message description of a predefined message still exists in a message file.
This exit program could be called from an exit point within a multithreaded job and should be written to be threadsafe.
| Top | Message Handling APIs | APIs by category |