Signaling

Signaling is supported only on IBM MQ for z/OS .

Signaling is an option on the MQGET call to allow the operating system to notify (or signal ) a program when an expected message arrives on a queue. This is like the get with wait function described in topic Waiting for messages because it allows your program to continue with other work while waiting for the signal. However, if we use signaling, we can free the application thread and rely on the operating system to notify the program when a message arrives.

To set a signal

1. Set the MQGMO_SET_SIGNAL option in the Options field.
2. Set the maximum life of the signal in the WaitInterval field. This sets the length of time (in milliseconds) for which we want IBM MQ to monitor the queue. Use the MQWI_UNLIMITED value to specify an unlimited life. Note: IMS applications must not specify an unlimited wait interval because this would prevent the IMS system from terminating. (When IMS terminates, it requires all dependent regions to end.) Instead, IMS applications can examine the state of the ECB at regular intervals (see step 3). A program can have signals set on several queue handles at the same time:
3. Specify the address of the Event Control Block (ECB) in the Signal1 field. This notifies you of the result of our signal. The ECB storage must remain available until the queue is closed.

Note: We cannot use the MQGMO_SET_SIGNAL option with the MQGMO_WAIT option.

When the message arrives

When a suitable message arrives, a completion code is returned to the ECB.

• The message that you set the signal for has arrived on the queue. The message is not reserved for the program that requested a signal, so the program must issue an MQGET call again to get the message. Note: Another application could get the message in the time between your receiving the signal and issuing another MQGET call.
• The wait interval you set has expired and the message you set the signal for did not arrive on the queue. IBM MQ has canceled the signal.
• The signal has been canceled. This happens, for example, if the queue manager stops, or the attribute of the queue is changed, so that MQGET calls are no longer allowed.

When a suitable message is already on the queue, the MQGET call completes in the same way as an MQGET call without signaling. Also, if an error is detected immediately, the call completes and the return codes are set.

When the call is accepted and no message is immediately available, control is returned to the program so that it can continue with other work. None of the output fields in the message descriptor are set, but the CompCode parameter is set to MQCC_WARNING and the Reason parameter is set to MQRC_SIGNAL_REQUEST_ACCEPTED.

For information about what IBM MQ can return to the application when it makes an MQGET call using signaling, see MQGET.

• For a CICS Transaction Server for z/OS program, the EXEC CICS WAIT EXTERNAL command
• For batch and IMS programs, the z/OS WAIT macro

If the state of the queue or the queue manager changes while the signal is set (that is, the ECB has not yet been posted), the following actions occur:

• If the queue manager enters the quiescing state, and we used the MQGMO_FAIL_IF_QUIESCING option, the signal is canceled. The ECB is posted with the MQEC_Q_MGR_QUIESCING completion code. Without this option, the signal remains set.
• If the queue manager is forced to stop, or is canceled, the signal is canceled. The signal is delivered with the MQEC_WAIT_CANCELED completion code.
• If the attributes of the queue (or a queue to which the queue name resolves) are changed so that get requests are now inhibited, the signal is canceled. The signal is delivered with the MQEC_WAIT_CANCELED completion code.

Note:

1. If more than one program has set a signal on the same shared queue to remove a message, only one program is activated by a message arriving. However, if more than one program is waiting to browse a message, all the programs can be activated. The rules that the queue manager follows when deciding which applications to activate are the same as those for waiting applications: for more information, see the description of the Options field of the MQGMO structure in MQGMO - Get-message options.
2. If there is more than one MQGET call waiting for the same message, with a mixture of wait and signal options, each waiting call is considered equally. For more information, see the description of the Options field of the MQGMO structure in MQGMO - Get-message options.
3. Under some conditions, it is possible both for an MQGET call to retrieve a message and for a signal (resulting from the arrival of the same message) to be delivered. This means that when your program issues another MQGET call (because the signal was delivered), there could be no message available. Design your program to test for this situation.

For information about how to set a signal, see the description of the MQGMO_SET_SIGNAL option and the Signal1 field in Signal1.