Developing and using user-written MQ trigger monitors and MQ message consumers

You can create your own MQ trigger monitors and use them to serve MQ queues in your CICS® environment, instead of using the CICS-supplied trigger monitor CKTI. You can also create your own MQ message consumers that get messages directly from application input queues and perform the required logic. This topic provides important instructions for developing and using user-written MQ trigger monitors and MQ message consumers.

Responsibilities of a user-written MQ monitor or MQ message consumer program

If you are using an MQMONITOR to process the MQ queue, when the MQMONITOR is started, the EXEC CICS START command starts your transaction with MONDATA prepended with <MQMONITOR_resource_nameUSERID> as the FROM data, so the user-written program must retrieve this data into a structure that matches the description for the MONDATA attribute before issuing any calls to MQ.

Then, before opening the MQ queue, the program must set the state of the MQ monitor as specified in the retrieved data to started.

Before returning to CICS, the program must set the state of the MQ monitor to stopped.

Security considerations when your MQ message consumer is used to route work to remote regions

If you are using your MQ message consumer to route work to remote regions, you must take into consideration any effect the security configuration your intersystem communication definitions might have on determining the user ID that will be associated with the transaction in the remote region. For details, see the information about routed transactions started by START commands in START.

Procedure

Your user-written MQ monitor or MQ message consumer program must perform the following steps in the sequence as indicated below:

  1. Check that the transaction has been started with data by using an EXEC CICS ASSIGN STARTCODE command.
  2. Retrieve the FROM data that was passed when your transaction was started into a structure, by issuing an EXEC CICS RETRIEVE command.

    Use the MQMONITOR name that is passed in bytes 2 through 9 of this data for the following steps.

  3. Issue EXEC CICS SET MQMONITOR(MQMONITOR_name) STARTED to set the state of the MQ monitor as specified in the retrieved data to started.
  4. Open the MQ queue.
  5. Get messages on the input queue and do the required application logic.
  6. When ending the program for any reason, issue EXEC CICS SET MQMONITOR(MQMONITOR_name) STOPPED to set the state of the MQ monitor to stopped. Write out the CICS statistics collected when the MQMONITOR was started.
  7. Return to CICS.
CAUTION:
If the user-written MQ trigger monitor or MQ message consumer program fails to perform the steps in the sequence as described in the preceding procedure, unpredictable consequences might occur; for example, recorded statistics will be unpredictable, and the MQMONITOR's MONSTATUS value will be in an unpredictable state.
Note: If the user-written MQ trigger monitor or MQ message consumer program issues EXEC CICS START requests, and if a policy that limits EXEC CICS START requests has been deployed and is active in the same region, the policy might abend the user-written program. In this situation, it is not suitable to activate policies that limit EXEC CICS START requests. For more information about policy rules, see Policy task rules.

Learn more