Triggering under MQ

The queue manager defines certain conditions as constituting trigger events. If triggering is enabled for a queue and a trigger event occurs, the queue manager sends a trigger message to a queue called an initiation queue. The presence of the trigger message on the initiation queue indicates that a trigger event has occurred.

Trigger messages generated by the queue manager are not persistent. This has the effect of reducing logging (thereby improving performance), and minimizing duplicates during restart, so improving restart time.

The program which processes the initiation queue is called a trigger-monitor application, and its function is to read the trigger message and take appropriate action, based on the information contained in the trigger message. Normally this action would be to start some other application to process the queue which caused the trigger message to be generated. From the point of view of the queue manager, there is nothing special about the trigger-monitor application; it is simply another application that reads messages from a queue (the initiation queue).

If triggering is enabled for a queue, you have the option to create a process-definition object associated with it. This object contains information about the application that processes the message which caused the trigger event. If the process definition object is created, the queue manager extracts this information and places it in the trigger message, for use by the trigger-monitor application. The name of the process definition associated with a queue is given by the ProcessName local-queue attribute. Each queue can specify a different process definition, or several queues can share the same process definition.

• 1. Application A, which can be either local or remote to the queue manager, puts a message on the application queue. Note that no application has this queue open for input. However, this fact is relevant only to trigger type FIRST and DEPTH.
• 2. The queue manager checks to see if the conditions are met under which it has to generate a trigger event. They are, and a trigger event is generated. Information held within the associated process definition object is used when creating the trigger message.
• 3. The queue manager creates a trigger message and puts it on the initiation queue associated with this application queue, but only if an application (trigger monitor) has the initiation queue open for input.
• 4. The trigger monitor retrieves the trigger message from the initiation queue.
• 5. The trigger monitor issues a command to start application B (the server application).
• 6. Application B opens the application queue and retrieves the message.

Before your application can take advantage of triggering, follow the steps below:

• 1. Create an initiation queue for your application queue. For example:

   DEFINE QLOCAL (initiation.queue) REPLACE +
   LIKE (SYSTEM.DEFAULT.LOCAL.QUEUE) +
   DESCR ('initiation queue description')
  

• 2. Associate the initiation queue with the application queue. A queue manager can own more than one initiation queue. You may want some of your application queues to be served by different programs, in which case you could use one initiation queue for each serving program, although you do not have to. Here is an example of how to create an application queue:

   DEFINE QLOCAL (application.queue) REPLACE +
   LIKE (SYSTEM.DEFAULT.LOCAL.QUEUE) +
   DESCR ('appl queue description') +
   INITQ ('initiation.queue') +
   PROCESS ('process.name') +
   TRIGGER +
   TRIGTYPE (FIRST)
  

• 3. If you are triggering an application, create a process definition object to contain information relating to the application that is to serve your application queue. For example, to trigger-start a CICS payroll transaction called PAYR:

   DEFINE PROCESS (process.name) +
   REPLACE +
   DESCR ('process description') +
   APPLTYPE ('CICS') +
   APPLICID ('PAYR') +
   USERDATA ('Payroll data')
  

  When the queue manager creates a trigger message, it copies information from the attributes of the process definition object into the trigger message.

• 4. You need to create a process definition if you want to trigger a channel and you are using a Version 2 MQSeries product. Otherwise, you can create a transmission queue definition and use blanks for the ProcessName attribute. The TrigData attribute can contain the name of the channel to be triggered or it can be left blank. Except on WebSphere MQ for z/OS, if it is left blank, the channel initiator searches the channel definition files until it finds a channel that is associated with the named transmission queue. When the queue manager creates a trigger message, it copies information from the TrigData attribute of the transmission queue definition into the trigger message.

• 5. If you have created a process definition object to specify properties of the application that is to serve your application queue, associate the process object with your application queue by naming it in the ProcessName attribute of the queue.

• 6. Start instances of the trigger monitors (or trigger servers in WebSphere MQ for iSeries) that are to serve the initiation queues you have defined. See "Trigger monitors" on page 206 for more information.

If you wish to be aware of any undelivered trigger messages, make sure your queue manager has a dead-letter (undelivered-message) queue defined. Specify the name of the queue in the DeadLetterQName queue manager field.

A program is not triggered if the trigger monitor cannot start the program or the queue manager cannot deliver the trigger message. For example, the ApplId in the process object must specify that the program is to be started in the background; if this is not done, the trigger monitor cannot start the program.

If a trigger message is created but cannot be put on the initiation queue (for example, because the queue is full or the length of the trigger message is greater than the maximum message length specified for the initiation queue), the trigger message is put instead on the dead-letter (undelivered message) queue.

If the put operation to the dead-letter queue cannot complete successfully, the trigger message is discarded and a warning message is sent to the console (z/OS) or to the system operator (iSeries), or put on the error log.

Putting the trigger message on the dead-letter queue may generate a trigger message for that queue. This second trigger message is discarded if it adds a message to the dead-letter queue.

If the program is triggered successfully but abends before it gets the message from the queue, use a trace utility (for example, CICS AUXTRACE if the program is running under CICS) to find out the cause of the failure.

UNO.EXE

• Host = "T42" ;

• Qmgr = "Q3" ;

• DLQ = "Q3DLQ" ;

• Data Q = "Q3SAG" ;

   Usage = "normal" ; (rx)
   Trigger Control = 'on' / 'every' ;
   Initiation Q = "Q3IQ" ;
   Process Name = "PSAG" ;
  

• Init Q = "Q3IQ" ;

   Usage = "normal" ; (rx)
  

• Process = "PSAG" ;

   Process Definition Name = "PSAG" ;
   Application Type = Windows ;
   Application Identifier = "\\cpp\winpopup\uno.exe"
  

• MQ Services + "Create a New Trigger Monitor Service"
  Parameters : "Queue Name := Q3IQ ;"
  Si se omite el nombre, se utilizará SYSTEM.DEFAULT.INITIATION.QUEUE
• MQ v7 : MQ Explorer + <qmn> + Advanced + Services + New Service

   Service Name = "MyTrigger" ;
   Service Control = QMgr ;
   Start Command = "c:\MQ\bin\runmqtrm.exe" ;
   Start Args = "-m QMM2 -q QL.QMM2.TIQ" ;
  

amqsput Q3SAG Q3 :

If I change "Trigger Monitor" parameter Queue Name to "Q3SAG", then, on every message I put there, I get MQFB_TM_ERROR

MQFB_TM_ERROR - MQTM structure not valid or missing.
The Format field in MQMD specifies MQFMT_TRIGGER, but the message does not begin with a valid MQTM structure. For example, the StrucId mnemonic eye-catcher may not be valid, the Version may not be recognized, or the length of the trigger message may be insufficient to contain the MQTM structure.

WR2FI.EXE

• Host = "T42" ;

• Qmgr = "Q2" ;

• Data Q = "QTRIG" ;

   Usage = "normal" ; (rx)
   Trigger Control = 'on' / 'every' ;
   Initiation Q = "QINI" ;
   Process Name = "SAGPROC" ;
  

• Init Q = "QINI" ;

• Process = "SAGPROC" ;

   Application Type = Windows NT ;
   Application Identifier = "\\cpp\timewr\wr2fi.exe" [sin START muestra los parámetros de entrada]
  

• Trigger Monitor : "start runmqtrm -m Q2 -q QINI" (A) from c:\TEMP directory (B).

• Resultat : [at (A) window]

  AMQ8618 Error starting triggered application.
  Explanation: An error was detected when trying to start the application identified in a trigger message.
  User Response: Check that the application the trigger
  

    Se escribia un string largo en una variable de 128 bytes.     *** Fixed & OK ***

  In (B) directory, a ZZZ.SAG is created, containing

  ( TMC StrucId 2 Version QTRIG QName sagproc ProcessName popoxo TriggerData \\cpp\timewr\wr2fi.exe ApplId 1234 EnvData ABCD UserData Q2 Qmgr ) My local time is [Wed Oct 12 11:09:14 2005].

  The MQTM strucure is like this :

  assemble with \\mq\tools\c\include\cmqc.h link to \\mq\tools\lib\mqm.lib struct tagMQTM { MQCHAR4 StrucId ; /* Structure identifier */ MQLONG Version ; /* Structure version number */ MQCHAR48 QName ; /* Name of triggered queue */ MQCHAR48 ProcessName ; /* Name of process object */ MQCHAR64 TriggerData ; /* Trigger data */ MQLONG ApplType ; /* Application type */ MQCHAR256 ApplId ; /* Application identifier */ MQCHAR128 EnvData ; /* Environment data */ MQCHAR128 UserData ; /* User data */ } ;

In order to start a sender channel when a message comes to its transmit queue, use the following :

 def ql(DESA4) usage(xmitq) maxmsgl(104857600) + 
     trigger TRIGTYPE(EVERY) TRIGDPTH(1) + 
     trigdata(DESA3.DESA4) +               /* channel name */ 
     initq(SYSTEM.CHANNEL.INITQ) replace   /* mandatory */ 
 

Initiation queue
A local queue on which the queue manager puts trigger messages.

Trigger event
An event (such as a message arriving on a queue) that causes a queue manager to create a trigger message on an initiation queue.

Trigger message
A message containing information about the program that a trigger monitor is to start.

Trigger monitor
A continuously-running application serving one or more initiation queues. When a trigger message arrives on an initiation queue, the trigger monitor retrieves the message. It uses the information in the trigger message to start a process that serves the queue on which a trigger event occurred.

Trigger monitor interface (TMI)
The MQSeries interface to which customer- or vendor-written trigger monitor programs must conform. A part of the MQSeries Framework.