Controlling trigger events
You control trigger events using some of the attributes that define our application queue. This information also gives examples of using the trigger types: EVERY, FIRST, and DEPTH.
We can enable and disable triggering, and we can select the number or priority of the messages that count toward a trigger event. There is a full description of these attributes in Attributes of objects.
The relevant attributes are:
- TriggerControl
- Use this attribute to enable and disable triggering for an application queue.
- TriggerMsgPriority
- The minimum priority that a message must have for it to count toward a trigger event. If a message of priority less than TriggerMsgPriority arrives on the application queue, the queue manager ignores the message when it determines whether to create a trigger message. If TriggerMsgPriority is set to zero, all messages count toward a trigger event.
- TriggerType
- In addition to the trigger type NONE (which disables triggering just like setting the TriggerControl to OFF), we can use the following trigger types to set the sensitivity of a queue to trigger events:
- EVERY
- A trigger event occurs every time that a message arrives on the application queue. Use this type of trigger if you want multiple instances of an application started.
- FIRST
- A trigger event occurs only when the number of messages on the application queue changes from zero to one. Use this type of trigger if you want a serving program to start when the first message arrives on a queue, continue until there are no more messages to process, then end. You must always process the queue until it is empty. See also Special case of trigger type FIRST.
- DEPTH
- A trigger event occurs only when the number of messages on the application queue reaches the value of the TriggerDepth attribute. A typical use of this type of triggering is to start a program when all the replies to a set of requests are received. Triggering by depth: With triggering by depth, the queue manager disables triggering (using the TriggerControl attribute) after it creates a trigger message. Your application must re-enable triggering itself (by using the MQSET call) after this has happened.
The action of disabling triggering is not under syncpoint control, so triggering cannot be re-enabled by backing out a unit of work. If a program backs out a put request that caused a trigger event, or if the program abends, you must re-enable triggering by using the MQSET call or the ALTER QLOCAL command.
- TriggerDepth
- The number of messages on a queue that causes a trigger event when using triggering by depth.
The conditions that must be satisfied for a queue manager to create a trigger message are described in Conditions for a trigger event.
Example of the use of trigger type EVERY
Consider an application that generates requests for motor insurance. The application might send request messages to a number of insurance companies, specifying the same reply-to queue each time. It might set a trigger of type EVERY on this reply-to queue so that each time a reply arrives, the reply might trigger an instance of the server to process the reply.
Example of the use of trigger type FIRST
Consider an organization with a number of branch offices that each transmit details of the days business to the head office. They all do this at the same time, at the end of the working day, and at the head office there is an application that processes the details from all the branch offices. The first message to arrive at the head office could cause a trigger event that starts this application. This application would continue processing until there are no more messages on its queue.
Example of the use of trigger type DEPTH
Consider a travel agency application that creates a single request to confirm a flight reservation, to confirm a reservation for a hotel room, to rent a car, and to order some travelers checks. The application might separate these items into four request messages, sending each to a separate destination. It might set a trigger of type DEPTH on its reply-to queue (with the depth set to the value 4), so that it is restarted only when all four replies have arrived.
If another message (possibly from a different request) arrives on the reply-to queue before the last of the four replies, the requesting application is triggered early. To avoid this, when using DEPTH triggering to collect multiple replies to a request, always use a new reply-to queue for each request.
Special case of trigger type FIRST
With trigger type FIRST, if there is already a message on the application queue when another message arrives, the queue manager does not typically create another trigger message.
However, the application serving the queue might not actually open the queue (for example, the application might end, possibly because of a system problem). If an incorrect application name has been put into the process definition object, the application serving the queue will not pick up any of the messages. In these situations, if another message arrives on the application queue, there is no server running to process this message (and any other messages on the queue).
To deal with this, the queue manager creates further trigger messages under the following circumstances:
Consider the following points when deciding on a value for the trigger interval to use in our application:
- If another message arrives on the application queue, but only if a predefined time interval has elapsed since the queue manager created the last trigger message for that queue. This time interval is defined in the queue manager attribute TriggerInterval. Its default value is 999 999 999 milliseconds.
- On IBM MQ for z/OSĀ®, application queues that name an open initiation queue are scanned periodically. If TRIGINT milliseconds have passed since the last trigger message was sent and the queue satisfies the conditions for a trigger event and CURDEPTH is greater than zero, a trigger message is generated. This process is called backstop triggering.
- If you set TriggerInterval to a low value, and there is no application serving the application queue, trigger type FIRST might behave like trigger type EVERY. This depends on the rate that messages are being put onto the application queue, which in turn might depend on other system activity. This is because, if the trigger interval is very small, another trigger message is generated each time that a message is put onto the application queue, even though the trigger type is FIRST, not EVERY. (Trigger type FIRST with a trigger interval of zero is equivalent to trigger type EVERY.)
- On IBM MQ for z/OS if you set TRIGINT to a low value, and there is no application serving the trigger type FIRST application queue, backstop triggering will generate a trigger message each time the periodic scan of application queues that name open initiation queues takes place.
- If a unit of work is backed out (see Trigger messages and units of work ) and the trigger interval has been set to a high value (or the default value), one trigger message is generated when the unit of work is backed out. However, if we have set the trigger interval to a low value or to zero (causing trigger type FIRST to behave like trigger type EVERY) many trigger messages can be generated. If the unit of work is backed out, all the trigger messages are still made available. The number of trigger messages that are generated depends on the trigger interval. If the trigger interval is set to zero, the maximum number of messages are generated.