Triggering channels

IBM® MQ provides a facility for starting an application automatically when certain conditions on a queue are met. This facility is called triggering.

This explanation is intended as an overview of triggering concepts. For a complete description, see Starting IBM MQ applications using triggers.

For platform-specific information see the following:

For Windows, see UNIX and Linux® systems, Triggering channels on UNIX, Linux, and Windows.
For IBM i, see Triggering channels in IBM MQ for IBM i
For z/OS®, see Transmission queues and triggering channels

The figure shows the concepts of triggering. The text following this figure explains the objects required and the sequence of events. — Figure 1. The concepts of triggering

The objects required for triggering are shown in Figure 1. It shows the following sequence of events:

The local queue manager places a message from an application or from a message channel agent (MCA) on the transmission queue.
When the triggering conditions are fulfilled, the local queue manager places a trigger message on the initiation queue.
The long-running channel initiator program monitors the initiation queue, and retrieves messages as they arrive.
The channel initiator processes the trigger messages according to information contained in them. This information might include the channel name, in which case the corresponding MCA is started.
The local application or the MCA, having been triggered, retrieves the messages from the transmission queue.

To set up this scenario, you need to:

Create the transmission queue with the name of the initiation queue (that is, SYSTEM.CHANNEL.INITQ) in the corresponding attribute.
Ensure that the initiation queue (SYSTEM.CHANNEL.INITQ) exists.
Ensure that the channel initiator program is available and running. The channel initiator program must be provided with the name of the initiation queue in its start command. On z/OS, the name of the initiation queue is fixed, so is not used on the start command.
Optionally, create the process definition for the triggering, if it does not exist, and ensure that the UserData field contains the name of the channel it serves. Instead of creating a process definition, you can specify the channel name in the TriggerData attribute of the transmission queue. IBM MQ for IBM i, UNIX, Linux, and Windows systems, allow the channel name to be specified as blank, in which case the first available channel definition with this transmission queue is used.
Ensure that the transmission queue definition contains the name of the process definition to serve it, (if applicable), the initiation queue name, and the triggering characteristics you feel are most suitable. The trigger control attribute allows triggering to be enabled, or not, as necessary.

Note:

The channel initiator program acts as a 'trigger monitor' monitoring the initiation queue used to start channels.
An initiation queue and trigger process can be used to trigger any number of channels.
Any number of initiation queues and trigger processes can be defined.
A trigger type of FIRST is recommended, to avoid flooding the system with channel starts.

Triggering channels on UNIX, Linux, and Windows.

You can create a process definition in IBM MQ, defining processes to be triggered. Use the MQSC command DEFINE PROCESS to create a process definition naming the process to be triggered when messages arrive on a transmission queue. The USERDATA attribute of the process definition contains the name of the channel being served by the transmission queue.

Define the local queue (QM4), specifying that trigger messages are to be written to the initiation queue (IQ) to trigger the application that starts channel (QM3.TO.QM4):


DEFINE QLOCAL(QM4) TRIGGER INITQ(SYSTEM.CHANNEL.INITQ) PROCESS(P1) USAGE(XMITQ)

Define the application (process P1) to be started:


DEFINE PROCESS(P1) USERDATA(QM3.TO.QM4)

Alternatively, for IBM MQ for UNIX, Linux and Windows systems, you can eliminate the need for a process definition by specifying the channel name in the TRIGDATA attribute of the transmission queue.

Define the local queue (QM4). Specify that trigger messages are to be written to the default initiation queue SYSTEM.CHANNEL.INITQ, to trigger the application (process P1) that starts channel (QM3.TO.QM4):


DEFINE QLOCAL(QM4) TRIGGER INITQ(SYSTEM.CHANNEL.INITQ)
USAGE(XMITQ) TRIGDATA(QM3.TO.QM4)

If you do not specify a channel name, the channel initiator searches the channel definition files until it finds a channel that is associated with the named transmission queue.

Triggering channels in IBM MQ for IBM i

Triggering of channels in IBM MQ for IBM i is implemented with the channel initiator process. A channel initiator process for the initiation queue SYSTEM.CHANNEL.INITQ is started automatically with the queue manager unless it is disabled by altering the queue manager SCHINIT attribute.

Set up the transmission queue for the channel, specifying SYSTEM.CHANNEL.INITQ as the initiation queue, and enabling triggering for the queue. The channel initiator starts the first available channel that specifies this transmission queue.


CRTMQMQ QNAME(MYXMITQ1) QTYPE(*LCL) MQMNAME(MYQMGR)
TRGENBL(*YES) INITQNAME(SYSTEM.CHANNEL.INITQ)
USAGE(*TMQ)

You can manually start up to three channel initiator processes with the STRMQMCHLI command and specify different initiation queues. You can also specify more than one channel able to process the transmission queue and choose which channel to start. This capability is still provided to be compatible with earlier releases. Its usage is deprecated.

Note: Only one channel at a time can process a transmission queue.


STRMQMCHLI QNAME(MYINITQ)

Set up the transmission queue for the channel, specifying TRGENBL(*YES) and, to choose which channel to attempt to start, specify the channel name in the TRIGDATA field. For example:


CRTMQMQ QNAME(MYXMITQ2) QTYPE(*LCL) MQMNAME(MYQMGR)
TRGENBL(*YES) INITQNAME(MYINITQ)
USAGE(*TMQ) TRIGDATA(MYCHANNEL)