Trigger monitors

To a queue manager, a trigger monitor is like any other application that serves a queue. However, a trigger monitor serves initiation queues.

A trigger monitor is usually a continuously-running program. When a trigger message arrives on an initiation queue, the trigger monitor retrieves that message. It uses information in the message to issue a command to start the application that is to process the messages on the application queue.

The trigger monitor must pass sufficient information to the program it is starting so that the program can perform the right actions on the right application queue.

A channel initiator is an example of a special type of trigger monitor for message channel agents. In this situation however, you must use either trigger type FIRST or DEPTH.

Trigger monitors on z/OS

The following trigger monitor is provided for CICS Transaction Server for z/OS and CICS for MVS/ESA:

CKTI

You need to start one instance of CKTI for each initiation queue (see WebSphere MQ for z/OS System Administration Guide for information on how to do this). CKTI passes the MQTM structure of the trigger message to the program it starts by EXEC CICS START TRANSID. The started program gets this information by using the EXEC CICS RETRIEVE command. A program can use the EXEC CICS RETRIEVE command with the RTRANSID option to determine how the program was started; if the value returned is CKTI, the program was started by WebSphere MQ for z/OS. For an example of how to use CKTI, see the source code supplied for module CSQ4CVB2 in the Credit Check sample application supplied with WebSphere MQ for z/OS. See The Credit Check sample for a full description.

The following trigger monitor is provided for IMS/ESA:

CSQQTRMN

You need to start one instance of CSQQTRMN for each initiation queue (see WebSphere MQ for z/OS System Administration Guide for information on how to do this). CSQQTRMN passes the MQTMC2 structure of the trigger message to the programs it starts.

The following trigger monitors are provided for the server environment:

amqstrg0

This is a sample trigger monitor that provides a subset of the function provided by runmqtrm. See Chapter 35, Sample programs (all platforms except z/OS) for more information on amqstrg0.

runmqtrm

runmqtrm [-m QMgrName] [-q InitQ] is the command. The default is SYSTEM.DEFAULT.INITIATION.QUEUE on the default queue manager. It calls programs for the appropriate trigger messages. This trigger monitor supports the default application type.

The command string passed by the trigger monitor to the operating system is built as follows:

1. The ApplId from the relevant PROCESS definition (if created)
2. The MQTMC2 structure, enclosed in quotation marks
3. The EnvData from the relevant PROCESS definition (if created)

where ApplId is the name of the program to run - as it would be entered on the command line.

The parameter passed is the MQTMC2 character structure. A command string is invoked which has this string, exactly as provided, in 'quotation marks', in order that the system command will accept it as one parameter.

The trigger monitor will not look to see if there is another message on the initiation queue until the completion of the application it has just started. If the application has a lot of processing to do, this may mean that the trigger monitor cannot keep up with the number of trigger messages arriving. You have two options:

• Have more trigger monitors running
• Run the started applications in the background

If you choose to have more trigger monitors running you have control over the maximum number of applications that can run at any one time. If you choose to run applications in the background, there is no restriction imposed by WebSphere MQ on the number of applications that can run.

To run the started application in the background under OS/2 or Windows systems, within the ApplId field you must prefix the name of your application with a START command. For example:

  START AMQSECHA /B

To run the started application in the background on UNIX systems, you must put an '&' at the end of the EnvData of the PROCESS definition.

The following trigger monitors are provided for the WebSphere MQ client:

runmqtmc

This is the same as runmqtrm except that it links with the WebSphere MQ client libraries.

For CICS:

The amqltmc0 trigger monitor is provided for CICS. It works in the same way as the standard trigger monitor, runmqtrm, but you run it in a different way and it triggers CICS transactions.

It is supplied as a CICS program and you must define it with a 4-character transaction name. Enter the 4-character name to start the trigger monitor. It uses the default queue manager (as named in the qm.ini file or, on WebSphere MQ for Windows, the registry), and the SYSTEM.CICS.INITIATION.QUEUE.

If you want to use a different queue manager or queue, you must build the trigger monitor the MQTMC2 structure: this requires you to write a program using the EXEC CICS START call, because the structure is too long to add as a parameter. Then, pass the MQTMC2 structure as data to the START request for the trigger monitor.

When you use the MQTMC2 structure, you only need to supply the StrucId, Version, QName, and QMgrName parameters to the trigger monitor as it does not reference any other fields.

Messages are read from the initiation queue and used to start CICS transactions, using EXEC CICS START, assuming the APPL_TYPE in the trigger message is MQAT_CICS. The reading of messages from the initiation queue is performed under CICS syncpoint control.

Messages are generated when the monitor has started and stopped as well as when an error occurs. These messages are sent to the CSMT transient data queue.

Here are the available versions of the trigger monitor:

If you need a trigger monitor for other environments, you need to write a program that can process the trigger messages that the queue manager puts on the initiation queues. Such a program should:

1. Use the MQGET call to wait for a message to arrive on the initiation queue.
2. Examine the fields of the MQTM structure of the trigger message to find the name of the application to start and the environment in which it runs.
3. Issue an environment-specific start command. For example, in z/OS batch, submit a job to the internal reader.
4. Convert the MQTM structure to the MQTMC2 structure if required.
5. Pass either the MQTMC2 or MQTM structure to the started application. This may contain user data.
6. Associate with your application queue the application that is to serve that queue. You do this by naming the process definition object (if created) in the ProcessName attribute of the queue.

   Use DEFINE QLOCAL or ALTER QLOCAL. On iSeries you can also use CRTMQMQ or CHGMQMQ.

For more information on the trigger monitor interface, see WebSphere MQ Application Programming Reference.

WebSphere MQ for iSeries trigger monitors

The following are provided:

AMQSTRG4

This is a trigger monitor that submits an OS/400 job for the process that is to be started, but this means there is a processing overhead associated with each trigger message.

AMQSERV4

This is a trigger server. For each trigger message, this server runs the command for the process in its own job, and can call CICS transactions.

Both the trigger monitor and the trigger server pass an MQTMC2 structure to the programs they start. For a description of this structure, see WebSphere MQ Application Programming Reference. Both of these samples are delivered in both source and executable forms.

Since these trigger monitors can only invoke native OS/400 programs, they cannot trigger Java programs directly, because java classes are located in the IFS. However, Java programs can be triggered indirectly by triggering a CL program which then invokes the Java program and passes across the TMC2 structure. The minimum size of the TMC2 structure is 732 bytes.

The source of a sample CLP is shown below:

  PGM PARM(&TMC2)
    DCL &TMC2 *CHAR LEN(800)
      ADDENVVAR ENVVAR(TM) VALUE(&TMC2)
      QSH  CMD('java_pgmname $TM')
      RMVENVVAR ENVVAR(TM)
  ENDPGM