Signaling
Signaling is supported only on WebSphere MQ for z/OS and MQSeries for Compaq NonStop Kernel.
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 similar to 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 you use signaling, you can free the application thread and rely on the operating system to notify the program when a message arrives.
To set a signal
To set a signal, do the following in the MQGMO structure that you use on your MQGET call:
- Set the MQGMO_SET_SIGNAL option in the Options field.
- Set the maximum life of the signal in the WaitInterval field. This sets the length of time (in milliseconds) for which you want WebSphere MQ to monitor the queue. Use the MQWI_UNLIMITED value to specify an unlimited life.
- Note:
- IMS applications should 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 should 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:
- On MQSeries for Compaq NonStop Kernel, specify an application tag in the Signal1 field. This can be used by an application to associate the IPC notification message with a particular MQGET call (see When the message arrives). On WebSphere MQ for z/OS, specify the address of the Event Control Block (ECB) in the Signal1 field. This notifies you of the result of your signal. The ECB storage must remain available until the queue is closed.
- Note:
- You cannot use the MQGMO_SET_SIGNAL option in conjunction with the MQGMO_WAIT option.
When the message arrives
When a suitable message arrives, the following occurs:
- On MQSeries for Compaq NonStop Kernel An Inter-Process Communication (IPC) message is sent to the $RECEIVE queue of the process that made the MQGET call.
- On WebSphere MQ for z/OS, a completion code is returned to the ECB.
The completion code describes one of the following:
- The message 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 you receiving the signal and you 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. WebSphere 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 and Reason parameters are set to MQCC_WARNING and MQRC_SIGNAL_REQUEST_ACCEPTED, respectively.
For information on what WebSphere MQ can return to your application when it makes an MQGET call using signaling, see WebSphere MQ Application Programming Reference.
On WebSphere MQ for z/OS, if the program has no other work to do while it is waiting for the ECB to be posted, it can wait for the ECB using:
- 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 you 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.
Notes:
- 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 WebSphere MQ Application Programming Reference.
- 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 WebSphere MQ Application Programming Reference.
- 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. You should 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 WebSphere MQ Application Programming Reference.
WebSphere is a trademark of the IBM Corporation in the United States, other countries, or both.
IBM is a trademark of the IBM Corporation in the United States, other countries, or both.