Working with triggering on IBM i

Use this information to learn about triggering and process definitions.

IBM® MQ provides a facility for starting an application automatically when certain conditions on a queue are met. One example of the conditions is when the number of messages on a queue reaches a specified number. This facility is called triggering and is described in detail in Triggering channels.

What is triggering?

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.

What is the trigger monitor?

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 another application that reads messages from a queue (the initiation queue).

Altering the job submission attributes of the trigger monitor

The trigger monitor supplied as command STRMQMTRM submits a job for each trigger message using the system default job description, QDFTJOBD. This has limitations in that the submitted jobs are always called QDFTJOBD and have the attributes of the default job description including the library list, *SYSVAL. IBM MQ provides a method for overriding these attributes. For example, it is possible to customize the submitted jobs to have more meaningful job names as follows:

In the job description specify the description you want, for example logging values.
Specify the Environment Data of the process definition used in the triggering process:
```
CHGMQMPRC PRCNAME(MY_PROCESS) MQMNAME(MHA3) ENVDATA ('JOBD(MYLIB/TRIGJOBD)')
```
The Trigger Monitor performs a SBMJOB using the specified description.

It is possible to override other attributes of the SBMJOB by specifying the appropriate keyword and value in the Environment Data of the process definition. The only exception to this is the CMD keyword because this attribute is filled by the trigger monitor. An example of the command to specify the Environment Data of the process definition where both the job name and description are to be altered follows:


CHGMQMPRC PRCNAME(MY_PROCESS) MQMNAME(MHA3) ENVDATA ('JOBD(MYLIB/TRIGJOB)
JOB(TRIGGER)')

Defining an application queue for triggering

An application queue is a local queue that is used by applications for messaging, through the MQI. Triggering requires a number of queue attributes to be defined on the application queue. Triggering itself is enabled by the TRGENBL attribute.

In this example, a trigger event is to be generated when there are 100 messages of priority 5 or higher on the local queue motor.insurance.queue, as follows:


CRTMQMQ MQMNAME(MYQUEUEMANAGER) QNAME('motor.insurance.queue') QTYPE(*LCL)
PRCNAME('motor.insurance.quote.process') MAXMSGLEN(2000)
DFTMSGPST(*YES) INITQNAME('motor.ins.init.queue')
TRGENBL(*YES) TRGTYPE(*DEPTH) TRGDEPTH(100) TRGMSGPTY(5)

where the parameters are:

MQMNAME(MYQUEUEMANAGER): The name of the queue manager.
QNAME('motor.insurance.queue'): The name of the application queue being defined.
PRCNAME('motor.insurance.quote.process'): The name of the application to be started by a trigger monitor program.
MAXMSGLEN(2000): The maximum length of messages on the queue.
DFTMSGPST(*YES): Messages on this queue are persistent by default.
INITQNAME('motor.ins.init.queue'): The name of the initiation queue on which the queue manager is to put the trigger message.
TRGENBL(*YES): The trigger attribute value.
TRGTYPE(*DEPTH): A trigger event is generated when the number of messages of the required priority ( TRGMSGPTY ) reaches the number specified in TRGDEPTH.
TRGDEPTH(100): The number of messages required to generate a trigger event.
TRGMSGPTY(5): The priority of messages that are to be counted by the queue manager in deciding whether to generate a trigger event. Only messages with priority 5 or higher are counted.

Defining an initiation queue

When a trigger event occurs, the queue manager puts a trigger message on the initiation queue specified in the application queue definition. Initiation queues have no special settings, but you can use the following definition of the local queue motor.ins.init.queue for guidance:


CRTMQMQ MQMNAME(MYQUEUEMANAGER) QNAME('motor.ins.init.queue') QTYPE(*LCL)
GETENBL(*YES) SHARE(*NO) TRGTYPE(*NONE)
MAXMSGL(2000)
MAXDEPTH(1000)

Creating a process definition

Use the CRTMQMPRC command to create a process definition. A process definition associates an application queue with the application that is to process messages from the queue. This is done through the PRCNAME attribute on the application queue motor.insurance.queue. The following command creates the required process, motor.insurance.quote.process, identified in this example:


CRTMQMPRC MQMNAME(MYQUEUEMANAGER) PRCNAME('motor.insurance.quote.process')
TEXT('Insurance request message processing')
APPTYPE(*OS400) APPID(MQTEST/TESTPROG)
USRDATA('open, close, 235')

where the parameters are:

MQMNAME(MYQUEUEMANAGER): The name of the queue manager.
PRCNAME('motor.insurance.quote.process'): The name of the process definition.
TEXT('Insurance request message processing'): A description of the application program to which this definition relates. This text is displayed when you use the DSPMQMPRC command. This can help you to identify what the process does. If you use spaces in the string, you must enclose the string in single quotation marks.
APPTYPE(*OS400): The type of application to be started.
APPID(MQTEST/TESTPROG): The name of the application executable file, specified as a fully qualified file name.
USRDATA('open, close, 235'): User-defined data, which can be used by the application.

Displaying your process definition

Use the DSPMQMPRC command to examine the results of your definition. For example:


MQMNAME(MYQUEUEMANAGER) DSPMQMPRC('motor.insurance.quote.process')

You can also use the CHGMQMPRC command to alter an existing process definition, and the DLTMQMPRC command to delete a process definition.