IBM Software Group

WebSphere MQ Triggering

Beverly Brown, Calista Stevens WebSphere MQ Level 2 Customer Support

WebSphere Support Technical Exchange

IBM Software Group

Agenda
What is triggering How does triggering work The flow of triggering The different types of triggering How to set up triggering The conditions for a trigger event How to diagnose triggering problems Miscellaneous notes Triggering Documentation and SupportPacs

WebSphere Support Technical Exchange

2 of 37

IBM Software Group

Acknowledgement
Special thanks to Calista Stevens for her contribution to the content of this presentation.

WebSphere Support Technical Exchange

3 of 37

IBM Software Group

Triggering What is it?

WebSphere MQ provides a feature that enables an application or channel to be started automatically when there are messages available to retrieve from a queue.

WebSphere Support Technical Exchange

4 of 37

IBM Software Group

Triggering - How does it work?

A message is put to a queue defined as triggered. If a series of conditions are met, the queue manager sends a trigger message to an initiation queue. This is called a trigger event. A trigger monitor reads the trigger message and takes the appropriate action based on the contents of the message, which is typically to start a program to process the triggered queue. Trigger monitors may be built-in, supplied by a SupportPac, or user written.

WebSphere Support Technical Exchange

5 of 37

IBM Software Group

1.Put Message To Queue Application

Flow of Triggering
Queue Manager Xmitq or Localq

5.Message Retrieved from local or xmit queue Application

User application started by trigger monitor or MCA started by channel initiator

Local or MCA

2.Trigger Message Sent

INITIATION QUEUE

3.Trigger Message Retrieved Program Trigger monitor 4. Start User Program or RUNMQCHL
6 of 37

WebSphere Support Technical Exchange

IBM Software Group

TRIGTYPE
FIRST: A trigger event occurs when the current depth of the triggered queue changes from 0 to 1. Use this type of trigger when the serving program will process all the messages on the queue (i.e. until MQRC_NO_MSG_AVAILABLE). EVERY: A trigger event occurs every time a message arrives on the triggered queue. Use this type of trigger when the serving program will only process one message at a time. Note: On i5/OS this value is *ALL.

WebSphere Support Technical Exchange

7 of 37

IBM Software Group

TRIGTYPE
DEPTH: A trigger event occurs when the number of messages on the triggered queue reaches the value of the TRIGDPTH attribute. Use this type of trigger when the serving program is designed to process a fixed number of messages (i.e. all replies for a certain request). Note: When triggering by depth, triggering is disabled and must be re-enabled by using MQSET or ALTER QLOCAL.

WebSphere Support Technical Exchange

8 of 37

IBM Software Group

Trigger Interval
TriggerInterval or TRIGINT is a time interval specified on the QMGR definition for use by queues defined as TRIGTYPE=FIRST. Situations may occur when messages are left on the queue. New messages will not cause another trigger message. To help with this situation, a trigger message will be created when the next message is put if TriggerInterval has elapsed since the last trigger message was created for the queue. z/OS has a backstop process to scan queues.

WebSphere Support Technical Exchange

9 of 37

IBM Software Group

Channel Triggering Setup

Create an initiation queue (non-z/OS platforms) or use the default SYSTEM.CHANNEL.INITQ. Create a process definition (optional). TriggerData may be specified in lieu of a process definition. Create or alter a transmission queue. Associate the initiation queue and the process definition (if applicable) with the transmission queue, and specify the trigger attributes.

WebSphere Support Technical Exchange

10 of 37

IBM Software Group

Channel Triggering Setup Example 1

DEFINE QLOCAL(QM2) REPLACE + USAGE (XMITQ) TRIGGER TRIGTYPE(FIRST) + TRIGDATA(QM1.TO.QM2) + INITQ (SYSTEM.CHANNEL.INITQ) QM2 is the name of the XMITQ QM1.TO.QM2 is the name of the channel to be started when a message hits the XMITQ SYSTEM.CHANNEL.INITQ is the initq monitored by the channel initiator

WebSphere Support Technical Exchange

11 of 37

IBM Software Group

Channel Triggering Setup Example 2 - dist

DEFINE QLOCAL(QM4) TRIGGER + INITQ(SYSTEM.CHANNEL.INITQ) + PROCESS(P1) USAGE (XMITQ) DEFINE PROCESS(P1) + USERDATA(QM3.TO.QM4) The XMITQ definition has PROCESS instead of TRIGDATA The channel name is in USERDATA

WebSphere Support Technical Exchange

12 of 37

IBM Software Group

Channel Triggering Setup Example 3 -- z/OS

DEFINE QLOCAL(QM4) TRIGGER + INITQ(SYSTEM.CHANNEL.INITQ) + PROCESS(P1) USAGE (XMITQ) DEFINE PROCESS(P1) APPLTYPE(MVS) + APPLICID(CSQX START) + USERDATA(QM3.TO.QM4) Quotes for APPLICID are not needed on CSQOREXX panels APPLTYPE(MVS) is needed -- CICS is the default
WebSphere Support Technical Exchange 13 of 37

IBM Software Group

Channel Triggering Setup Example 4 i5/OS

CRTMQMQ QNAME(initq_name) CRTMQMPRC PRCNAME(proc_name) USRDATA (chlname) APPID(QMQM/RUNMQCHL) CRTMQMQ QNAME(xmitq_name) PRCNAME (proc_name) TRGENBL(*YES) TRGTYPE(*FIRST) INITQNAME(initq_name) USAGE(*TMQ) Could use TRIGDATA instead of PRCNAME.

WebSphere Support Technical Exchange

14 of 37

IBM Software Group

Application Triggering Setup

Create an initiation queue or use the default SYSTEM.DEFAULT.INITIATION.QUEUE. Create a process definition. Create or alter a local or model queue. Associate the initiation queue and process definition with the local queue, and specify the trigger attributes .

WebSphere Support Technical Exchange

15 of 37

IBM Software Group

Application Triggering Setup -PROCESS

APPLICID is the name of the application executable file, e.g. - For APPLTYPE(UNIX): APPLICID ('/u/admin/test/IRMP01') - For APPLTYPE(WINDOWSNT): APPLICID(c:\appl\test\irmp01.exe.) On UNIX systems, ENVRDATA can be set to the ampersand character to make the started application run in the background. The application can receive a parm list with an MQTMC2 containing USRDATA and ENVRDATA.
WebSphere Support Technical Exchange 16 of 37

IBM Software Group

Application Triggering Setup Example 1

DEFINE QLOCAL (IQ) REPLACE DEFINE PROCESS (PROC) REPLACE + APPLTYPE ('CICS') APPLICID ('PAYR') + USERDATA ('Payroll data') DEFINE QLOCAL (Q1) REPLACE + INITQ (IQ) PROCESS (PROC) + TRIGGER TRIGTYPE (FIRST) Note: If using TRIGTYPE(DEPTH) then TRIGDEPTH must also be specified.

WebSphere Support Technical Exchange

17 of 37

IBM Software Group

Application Triggering Setup Example 2

CRTMQMQ QNAME(initq_name) CRTMQMPRC PRCNAME(proc_name) APPID(lib/ pgm) ENVDATA (JOBNAME(trigapl) JOBD(lib/ jobd)) CRTMQMQ QNAME(lclq_name) PRCNAME (proc_name) TRGENBL(*YES) TRGTYPE(*FIRST) INITQNAME(initq_name) Note: If using TRGTYPE(*DEPTH) then TRGDEPTH must also be specified.

WebSphere Support Technical Exchange

18 of 37

IBM Software Group

Trigger conditions
A trigger message is sent to the initiation queue when all of the following conditions are satisfied: 1. A message is put on a transmission or local queue. 2. The messages priority is greater than or equal to the TriggerMsgPriority of the queue.

WebSphere Support Technical Exchange

19 of 37

IBM Software Group

Trigger conditions
3. The number of messages on queue was previously - Zero for trigger type FIRST - Any number for trigger type EVERY or *ALL - TriggerDepth minus 1 for trigger type DEPTH 4. For trigger type FIRST or DEPTH, no program has the trigger queue open for GETs (Open input count=0). 5. The Get enabled attribute is set to YES on the triggered queue.

WebSphere Support Technical Exchange

20 of 37

IBM Software Group

Trigger conditions
6. A Process name is specified and exists, or for transmission queues, TriggerData contains the name of a channel. 7. An Initiation queue is specified and exists and GETs and PUTs are enabled for the initiation queue. 8. The trigger monitor has been started and has the initiation queue open for GETs

WebSphere Support Technical Exchange

21 of 37

IBM Software Group

Trigger conditions
9. The TriggerControl attribute is set to YES on the triggered queue. 10. The TriggerType attribute is not set to NONE. 11. For Trigger Type FIRST, the queue was not previously empty, but the TriggerInterval set for the QMGR has elapsed. 12. The only application serving the queue issues MQCLOSE and there are still messages on the queue that satisfy Conditions 2 and 6-10.

WebSphere Support Technical Exchange

22 of 37

IBM Software Group

Trigger conditions
13. Certain trigger attributes of the triggered queue are changed, such as - NOTRIGGER to TRIGGER - PUT or GET DISABLED to ENABLED or a trigger monitor opens the Initiation queue. 14. MSGDLVSQ is set correctly relative to the priority of the messages and the TriggerMsgPriority setting.

WebSphere Support Technical Exchange

23 of 37

IBM Software Group

Problem Determination
If the setup is brand new or any configuration changes have been made, verify all the definitions are complete and correct. If the setup is brand new or has worked before, verify all the conditions for a trigger event are satisfied. If channel triggering, verify the correct channel name is specified and the channel is not in a STOPPED state.

WebSphere Support Technical Exchange

24 of 37

IBM Software Group

Problem Determination
If application triggering - verify the application name is correct and exists - verify the application is coded correctly - verify the correct authorizations are in place. Verify a trigger message can be delivered. Verify a trigger monitor is active. Verify trigger type and application design match. Try manually starting the triggered application to see if it is able to run.

WebSphere Support Technical Exchange

25 of 37

IBM Software Group

Problem Determination
Stranded messages may occur when the triggered application fails to remove one or more messages - for TriggerType FIRST, use TriggerInteval as a safety net, because a trigger event only occurs when depth goes from 0 to 1. - for TriggerType EVERY, if the triggered application only does one MQGET, manual intervention will be required to process the messages. Otherwise, the application will only read the oldest message on the next successful trigger and the queue depth will remain non-zero.
WebSphere Support Technical Exchange 26 of 37

IBM Software Group

Problem Determination
If there is a loop or high CPU: - Change the triggered application to specify a WaitInterval on its MQGET. Remember Condition 12 and see Getting messages from a triggered queue:
http://publib.boulder.ibm.com/infocenter/wmqv6/v6r0/topic/ com.ibm.mq.csqzal.doc/fg13940_.htm - Check the

BackoutCount in the MQMD Search the Support web page at

http://www-01.ibm.com/software/integration/wmq/support/

Run a trace.
WebSphere Support Technical Exchange 27 of 37

IBM Software Group

Notes:
For trigger EVERY, if the trigger monitor ends prematurely, no matter how many messages reside on the queue only one trigger message will be created on restart. RUNMQTRM will not get another trigger message until the application completes. To prevent trigger messages from accumulating - Run multiple trigger monitors or - Run the applications in the background

WebSphere Support Technical Exchange

28 of 37

IBM Software Group

Notes:
A trigger message is put to the dead letter queue when - The queue manager can not put a trigger message on the INITQ - RUNMQTRM detects an error in the trigger message structure - RUNMQTRM detects an unsupported application type - RUNMQTRM can not start the application - RUNMQTRM detects a data conversion error

WebSphere Support Technical Exchange

29 of 37

IBM Software Group

Notes:
Trigger messages are non-persistent. Conditions for a trigger event are persistent, so, if a trigger message is lost a trigger message will be created when the conditions are met. Trigger messages take on the default priority of the INITQ. Trigger monitors can not retrieve messages that are part of a unit of work until the unit of work completes (applies whether it is committed or backed out).

WebSphere Support Technical Exchange

30 of 37

IBM Software Group

Notes:
The queue manager counts both committed and uncommitted messages on the trigger queue when assessing the conditions for a trigger event. The exception is that only committed messages cause a trigger event for shared queues (on a Coupling Facility) on z/OS. After recycling the queue manager or trigger monitor, a trigger message may be created if the triggered queue has messages on it and provided the trigger conditions are met.

WebSphere Support Technical Exchange

31 of 37

IBM Software Group

Notes:
When triggering channels, trigger type FIRST or DEPTH is recommended. Disabling triggering is not under syncpoint control so triggering can not be re-enabled by backing out a unit of work. If a program backs out a unit of work or abends, triggering for DEPTH must be reenabled by MQSET, ALTER or CHGMQMQ. On z/OS, the CICS trigger monitor autoreconnects after the queue manager terminates.

WebSphere Support Technical Exchange

32 of 37

IBM Software Group

Triggering Documentation and SupportPacs

Channel Triggering: WebSphere MQ Intercommunication Guide, Chapter 2
http://publib.boulder.ibm.com/infocenter/wmqv6/v6r0/topic/ com.ibm.mq.csqzae.doc/ic10580_.htm

Application Triggering: WebSphere MQ Application Programming Guide, Chapter 14

http://publib.boulder.ibm.com/infocenter/wmqv6/v6r0/topic/ com.ibm.mq.csqzal.doc/fg13830_.htm

Link to manuals:
http://www-01.ibm.com/software/integration/wmq/library/

MQ SupportPacs:
http://www-01.ibm.com/support/docview.wss? uid=swg27007197
WebSphere Support Technical Exchange 33 of 37

IBM Software Group

Summary
What is triggering and how does it work How to set up triggering The conditions for a trigger event Problem determination for triggering problems

WebSphere Support Technical Exchange

34 of 37

IBM Software Group

Additional WebSphere Product Resources

Discover the latest trends in WebSphere Technology and implementation, participate in technically-focused briefings, webcasts and podcasts at: http://www.ibm.com/ developerworks/websphere/community/ Learn about other upcoming webcasts, conferences and events: http://www.ibm.com/ software/websphere/events_1.html Join the Global WebSphere User Group Community: http://www.websphere.org Access key product show-me demos and tutorials by visiting IBM Education Assistant: http://www.ibm.com/software/info/education/assistant View a Flash replay with step-by-step instructions for using the Electronic Service Request (ESR) tool for submitting problems electronically: http://www.ibm.com/software/ websphere/support/d2w.html Sign up to receive weekly technical My Notifications emails: http://www.ibm.com/software/ support/einfo.html

WebSphere Support Technical Exchange

35 of 37

IBM Software Group

IBM Support Wants to Hear From You!

Tell us about your support needs and wants
1. 2. 3. Visit any product support pages on IBM.com. Click on Participate in Questionnaire on top right of page. Takes 5-10 minutes to complete.

Or go to https://www.ibm.com/survey/oid/wsb.dll/s/ag21f?wsb34=swg_user

36 of 37

IBM Software Group

Questions and Answers

WebSphere Support Technical Exchange

37 of 37