The Triggering sample programs

The function provided in the triggering sample is a subset of that provided in the trigger monitor in the runmqtrm program. See Features demonstrated in the sample programs for the names of these programs.

Running the amqstrg0.c, amqstrg, and amqstrgc samples

The program takes 2 parameters:

1. The name of the initiation queue (necessary)
2. The name of the queue manager (optional)

If a queue manager is not specified, it will connect to the default one. A sample initiation queue will have been defined when you ran amqscos0.tst. the name of that queue is SYSTEM.SAMPLE.TRIGGER, and you can use it when you run this program.

Note:

The function in this sample is a subset of the full triggering function that is supplied in the runmqtrm program.

Running the AMQSTRG4 sample

This is a trigger monitor for the OS/400 environment. It submits one OS/400 job for each application to be started. This means there is a processing overhead associated with each trigger message.

AMQSTRG4 (in QCSRC) takes two parameters: the name of the initiation queue it is to serve, and the name of the queue manager (optional). AMQSAMP4 (in QCLSRC) defines a sample initiation queue, SYSTEM.SAMPLE.TRIGGER, that you can use when you try the sample programs.

Using the example trigger queue, the command to issue is:

   CALL PGM(QMQM/AMQSTRG4) PARM('SYSTEM.SAMPLE.TRIGGER')

Alternatively, you can use the CL equivalent STRMQMTRM - see WebSphere MQ for iSeries V5.3 System Administration.

Design of the triggering sample

The triggering sample program opens the initiation queue using the MQOPEN call with the MQOO_INPUT_AS_Q_DEF option. It gets messages from the initiation queue using the MQGET call with the MQGMO_ACCEPT_TRUNCATED_MSG and MQGMO_WAIT options, specifying an unlimited wait interval. The program clears the MsgId and CorrelId fields before each MQGET call to get messages in sequence.

When it has retrieved a message from the initiation queue, the program tests the message:

• It checks the size of the message to make sure it is the same size as an MQTM structure.
• It checks the ApplType field to make sure it contains the value MQAT_UNIX.

If either of these tests fail, the program displays a warning.

For valid trigger messages, the triggering sample copies data from these fields: ApplicId, EnvrData, Version, and ApplType. The last two of these fields are numeric, so the program creates character replacements to use in an MQTMC2 structure for OS/2, UNIX, and Windows systems, and in an MQTMC structure for OS/400.

The triggering sample issues a start command to the application specified in the ApplicId field of the trigger message, and passes an MQTMC2 or MQTMC (a character version of the trigger message) structure. In OS/2, UNIX systems, and Windows systems, the EnvData field is used as an extension to the invoking command string. In OS/400, it is used as job submission parameters, for example, the job priority or the job description. See WebSphere MQ for iSeries V5.3 System Administration for a discussion of job priority and job description.

Finally, the program closes the initiation queue.

Running the AMQSERV4 sample

This is a trigger server for the OS/400 environment. For each trigger message, this server runs the start command in its own job to start the specified application. The trigger server can call CICS transactions.

AMQSERV4 takes two parameters: the name of the initiation queue it is to serve, and the name of the queue manager (optional). AMQSAMP4 defines a sample initiation queue, SYSTEM.SAMPLE.TRIGGER, that you can use when you try the sample programs.

Using the example trigger queue the command to issue is:

   CALL PGM(QMQM/AMQSERV4) PARM('SYSTEM.SAMPLE.TRIGGER')

Design of the trigger server

The design of the trigger server is similar to that of the trigger monitor, except the trigger server:

• Allows MQAT_CICS as well as MQAT_OS400 applications
• Calls OS/400 applications in its own job (or uses STRCICSUSR to start CICS applications) rather than submitting an OS/400 job
• For CICS applications, substitutes the EnvData, for example, to specify the CICS region, from the trigger message in the STRCICSUSR command
• Opens the initiation queue for shared input, so many trigger servers can run at the same time

Note:

Programs started by AMQSERV4 must not use the MQDISC call because this will stop the trigger server. If programs started by AMQSERV4 use the MQCONN call, they will get the MQRC_ALREADY_CONNECTED reason code.

A trigger monitor program can be ended by the sysrequest option 2 (ENDRQS) or by inhibiting gets from the trigger queue. If the sample trigger queue is used the command is:

    CHGMQMQ QNAME('SYSTEM.SAMPLE.TRIGGER') MQMNAME GETENBL(*NO)

Note:

Before starting triggering again on this queue, you must enter the command:

    CHGMQMQ QNAME('SYSTEM.SAMPLE.TRIGGER') GETENBL(*YES)