CL Programming

Job Message Queues

Job message queues are created for each job on the system to handle all the message requirements of the job. Job message queues for a single job consist of an external message queue (*EXT) and a set of call message queues. A call message queue is assigned to each ILE procedure and OPM program that is called within the job. In addition, a job log is created for each job. A job log is a logical queue which maintains all messages sent within a job in chronological order. You may send messages to the *EXT queue or to a call message queue. You do not send messages to the job log. Rather a message sent to either *EXT or a call message queue is also logically added to the job log by the system.

The external message queue (*EXT) is used to communicate with the external requester (such as a display station user) of the job. Messages (except status messages) sent to the external message queue of a job are also placed on the job log (see Job Log for more information).

If an informational, inquiry, or notify message is sent to the external message queue for an interactive job, the message is displayed on the Display Program Messages display. Additionally, the procedure waits for a reply to inquiry or notify messages from the display station user. Should the user not enter a reply and press the Enter key or F3 (Exit), the default message reply is returned to the sender of the message. If there is no default message reply, *N is sent. If you send an inquiry or notify message to the external message queue for a batch job, the system sends the default reply back to you. If there is no default message reply, *N is the reply. The system reply list may override the displaying of inquiries or the sending of default replies to inquiries to *EXT.

If a status message is sent to the external message queue of an interactive job, the message is displayed on the message line of the display station. You can use status messages like this to inform the display station user of the progress of a long-running operation. For example, the system sends status messages when running the CPYF command if you copy a file with several members.

Note:
When your application completes the long-running operation, you must send another message to clear the message line at the display. You can use message CPI9801, which is a blank message, for this purpose. For example:
PGM
.
.
.
SNDPGMMSG  MSGID(CPF9898)  MSGF(QCPFMSG)  MSGDTA('Status 1')  +
           TOPGMQ(*EXT)  MSGTYPE(*STATUS)
.
.
.
SNDPGMMSG  MSGID(CPF9898)  MSGF(QCPFMSG)  MSGDTA('Status 2')  +
           TOPGMQ(*EXT)  MSGTYPE(*STATUS)
.
.
.
SNDPGMMSG  MSGID(CPI9801)  MSGF(QCPFMSG)  TOPGMQ(*EXT)  +
           MSGTYPE(*STATUS)
.
.
.
ENDPGM

A call message queue is used to send messages between one program or procedure and another program or procedure. As long as a program or procedure is on the call stack (has not returned yet) its call message queue is active and messages can be sent to that program or procedure. Once the program or procedure returns, its call message queue no longer exists and messages can no longer be sent to it. Message types which can be sent to a call message queue include informational, request, completion, diagnostic, status, escape, and notify.

The call message queue for an OPM program or ILE procedure is created when that program or procedure is called. The call message queue is exclusively associated only with the call stack entry in which the program or procedure is running. A call message queue is identified indirectly by identifying the call stack entry. A call stack entry is identified by the name of the program or procedure that is running in that call stack entry.

In the case of an OPM program, the associated call stack entry is identified by the (up to) 10 character program name. In the case of an ILE procedure, the associated call stack entry is identified by a three part name which consists of the (up to) 256 character procedure name, the (up to) 10 character module name, and the (up to) 10 character program name. The module name is the name of the module into which the procedure was compiled. The ILE program name is the name of the ILE program into which the module was bound.

When identifying the call stack entry for an ILE procedure, it is sufficient to specify only the procedure name. If the procedure name by itself does not uniquely identify the call stack entry, the module name or the ILE program name can also be specified. If, at the time a message is sent, a program or procedure is on the call stack more than once, the name specified will identify the most recently called occurrence of that program or procedure.

There are other methods to identify a call stack entry. These methods are discussed in detail in Call Stack Entry Identification on SNDPGMMSG.

If an OPM or ILE program is compiled and then replaced while it is on the call stack, care must be taken when the program name is used to reference a call stack entry. For call stack entries that are earlier on the stack than the point at which the replace operation was done, the name reference will resolved to the replaced object which now exists in QRPLOBJ. These name references are valid as long as the replaced object continues to exist in the QRPLOBJ library. For entries on the stack that are more recent then the point at which the replace operation was done, the name reference is for the new version of the program. Because of the manner in which the version to use is determined, you should not place a program directly in the library QRPLOBJ. This library should be used exclusively for the replaced version of a program. A name reference to a program that you place directly into QRPLOBJ will fail.

If a program object is removed or renamed while an occurrence of it is on the call stack, any name reference to the removed program or any name reference using the old name will fail. For ILE procedures, if you are using only the procedure and module name for a reference, renaming the program will not impact the name reference. If you are also using the ILE program name, the name reference will fail.

A message queue for a call stack entry of a program or procedure is no longer available when the program or procedure ends. A message that was on the associated call message queue can only be referenced at that point by using the message reference key of the message.

For example, assume that procedure A calls procedure B which calls procedure C. Procedure C sends a message to procedure B and ends. The message is available to procedure B. However, when procedure B ends, its call message queue is no longer available. As a result, you cannot access procedure B by using procedure A, even though the message appears in the job log. Procedure A cannot access messages that are sent to Procedure B unless Procedure A has the message reference key to that message.
For example, assume that procedure A calls procedure B which calls procedure C. Procedure C sends a message to procedure B and ends. The message is available to procedure B. However, when procedure B ends, its call message queue is no longer available. As a result, you cannot access procedure B by using procedure A, even though the message appears in the job log. Procedure A cannot access messages that are sent to Procedure B unless Procedure A has the message reference key to that message.

If procedure A needs to delete specific messages, you could do the following:

The following figure shows the relationship of procedure calls, the job message queue, and the call stack entry queues. A connecting line (-----) indicates which message queue is associated with which call of a procedure.
This figure shows the relationship of procedure calls, the job message queue, and the call stack entry queues. A connecting line (-----) indicates which message queue is associated with which call of a procedure.

In the preceding figure, procedure B has two call stack entry queues, one for each call of the procedure. There are no message queues for procedure C because no messages were sent to procedure C. When procedure C sends a message to procedure B, the message goes to the call stack entry queue for the last call of procedure B.

Note:
When you are using the command entry display, you can display all the messages sent to the job message queue by pressing F10 (Include detailed messages). Once the messages are displayed, you can roll through them using one of the roll keys.

You can also display the messages for a job by using the Display Job Log (DSPJOBLOG) command.


[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]