Add Support for MQ Trigger Monitor

IDMS MQ supports trigger monitoring to start application tasks automatically when messages arrive in the application queue. The MQ Trigger Monitor provides a polling option for CA IDMS to connect automatically to the queue manager when the queue manager comes online. CA IDMS supports multiple trigger monitors, each monitoring one initiation queue. 
idms19
IDMS MQ supports trigger monitoring to start application tasks automatically when messages arrive in the application queue. The MQ Trigger Monitor provides a polling option for CA IDMS to connect automatically to the queue manager when the queue manager comes online. CA IDMS supports multiple trigger monitors, each monitoring one initiation queue. 
The MQ Trigger Monitor performs the following events for each trigger monitor instance:
  • The associated initiation queue that is defined for the trigger monitor is opened.
  • The initiation queue is monitored for a trigger message. (A trigger message is put on an initiation queue if a trigger event has occurred)
  • Based on the contents of the trigger message, starts a DC task to process the application queue.
    The task that is started is defined in the APPLICID parameter of the IBM MQ process definition.
  • Passed to the task is the address of the MQTM structure which describes the trigger message data after a trigger event occurs. See IBM MQ MQI application reference for language-specific MQTM declarations. 
This article contains the following information:
2
Generate MQ Trigger Monitor Support with SYSGEN
The MQ Trigger Monitor is provided by the MQ line driver. The IDMS parameters that control the trigger monitor are defined using the following SYSGEN statements:
SYSGEN STATEMENT
DESCRIPTION
MQ LINE
Defines the MQ LINE which supports the MQ Trigger Monitor. The LINE defines the polling Interval which determines the number of seconds to wait before trying to reconnect to the initiation queue for each MQTRIGGR PTE if there is a failure.
MQ Trigger Monitor PTERM
Defines the initiation queue from which the trigger message is retrieved. The PTERM definition TYPE MQTRIGGR specifies the IBM MQ defined initiation queue that is accessed by the trigger monitor. Each trigger monitor PTERM uses a utility subtask. Depending on how many active units of work are expected to run simultaneously, the number of subtasks may need to be increased.
BULK PTERM/LTERM pairs
Defines each pair that is assigned to the user-defined task that gets started when a trigger message is retrieved and a task has been specified.
To enable the MQ Trigger Monitor feature in the DC/UCF system, perform the following tasks:
  • Define an MQ type LINE. 
  • Define a PTERM/LTERM pair for each trigger monitor instance.
    • PTERM type is MQTRIGGR.
  • Define several BULK PTERM/LTERM pairs.
    You determine the number of BULK PTERM/LTERM pairs by defining as many BULK PTERM/LTERM pairs as the expected maximum number of concurrent tasks automatically started by the trigger monitor. The system generation syntax permits you to define one pair, and the REPEAT clause of the PTERM statement can be used to facilitate the definition of multiple PTERMs and LTERMs.
  • Define polling for online queue manager.
    Specify the Polling Interval option on the MQ LINE statement in SYSGEN. In the definition for an MQ LINE, specify POLLING INTERVAL IS n where N is the number of seconds to wait in between polling. If 0, then polling is disabled. The default is 0, no polling.
For more information, see Using System Generation.
For more information about system generation MQ types, see SYSGEN MQ Type.
Define IBM MQ Queues and Processes for MQ Trigger Monitor to Use
MQ trigger queues and processes must be defined to use the MQ Trigger Monitor. Parameters that are defined in these queues and processes are also defined in the IDMS MQ environment using SYSGEN.
FROM IBM MQ DEFINITION
IBM MQ PARAMETER
DESCRIPTION
EXAMPLE
Define a process
APPLICID
DC task that is defined for IDMS MQ application program that the MQ Trigger Monitor starts.
APPLICID ('FINAN')
Define a queue ('CAMQTS.SID.TRIGG01')
INITQ
Name of the local MQ initiation queue where the queue manager puts the trigger messages and where the MQ Trigger Monitor is retrieving them. The name of this queue must match the name of the initiation queue that is defined in the MQ Trigger Monitor PTERM.
INITQ ('SYSTEM.DEFAULT.INITIATION.QUEUE')
See the IBM MQ documentation for more information about IBM MQ triggering.  
The queue and process parameters that are included in the trigger message are passed to the IDMS MQ application but the parameters are not required to be added to the IDMS CV. For more information, see the following Trigger Message Data Passed to DC Application upon Invocation section.
Example of the Relationship Between IBM MQ and IDMS Definitions
The following information represents the PROCESS in the QLOCAL definition to show the relationship between QLOCAL and PROCESS.
For more information about triggering requirements, see the IBM Knowledge Center, prerequisites for triggering topic.
  1. Create a local queue to be triggered and associate the initiation queue, for example:
    DEFINE QLOCAL ('CAMQTS.SID.TRIGG01') +  DESCR ('initiation queue description') +  INITQ ('initiation.queue') +  PROCESS ('process.name')
  2.  Specify the INITQ (initiation queue) in the trigger attributes of the QLOCAL that is set up for triggering. 
    * Trigger attributes TRIGGER + TRIGTYPE( FIRST ) + TRIGMPRI( 0 ) + TRIGDPTH( 1 ) + TRIGDATA( ' ' ) + PROCESS( 'CAMQTS.HB.TRIGG01.PROCESS' ) + INITQ( 'SYSTEM.DEFAULT.INITIATION.QUEUE' )       
    The initiation queue is also defined in the MQ PTERM statement in the following example:
    ADD PTERM MQPTERM1       ENABLED       IN LINE MQ1       MAXIMUM ERRORS IS 3       PRINTER CLASS IS 1       READBUFFER       TYPE IS MQTRIGGR       INITIATION QUEUE IS 'SYSTEM.DEFAULT.INITIATION.QUEUE
  3. Create an IBM process definition object with information defining the DC task to be initiated and the data to be passed to application or task (optional). For example, trigger the task called
    FINAN
    .
    DEFINE PROCESS (process.name) +  DESCR ('process description') +  APPLTYPE ('65536') +  APPLICID ('FINAN') +  USERDATA ('Finance data')
    The following example displays the DC task statement added for
    FINAN
    . See Example TASK Statement for more information about adding a task:
    ADD TASK FINAN       ENABLED       EXTERNAL       EXTERNAL WAIT IS SYSTEM
    When a trigger message is placed on the initiation queue by the queue manager, the trigger message contains information from the process definition. For example, 'finance data' is passed in the trigger message USERDATA field. See the corresponding IBM MQ documentation for a layout of the MQTM structure.
Trigger Message Data Passed to DC Application upon Invocation
When a DC task is invoked by MQ Trigger Monitor, the MQTM structure is made available to the program associated with the task. The MQTM structure describes the data in the trigger message and can be used by the program. The fields of the MQTM structure are derived from the IBM MQ queue and process definitions. For example, ENVDATA and USERDATA are defined in the IBM MQ process definition. TRIGGERDATA is defined in the application queue definition.
For more information, see the corresponding IBM MQ documentation.
Example of an Application Accessing a Passed Trigger Message
The application in this example uses the LINKAGE SECTION to accept the MQTM data fields into the program. The application program gains access to the Linkage section with the PROCEDURE DIVISION USING MQM-TRIGGER-MESSAGE.statement. When the application program gains access, any of the fields in CMQTML such as MQTM-QNAME or MQTM-USERDATA can be used in the program.
For a full source listing of the example, see the IDMSMQCB member in the CAGJSAMP library.
LINKAGE SECTION.           *    This IBM copybook contains the MQTM structure that is passed         *    to the application program via linkage from the IDMS MQ         *    Trigger Monitor.  It is optional to use the MQTM structure.          01  MQM-TRIGGER-MESSAGE.              COPY CMQTML.           *****************************************************************         *         *  PROCEDURE DIVISION         *         *****************************************************************         *    Procedure Division using MQTM structure          PROCEDURE DIVISION USING MQM-TRIGGER-MESSAGE.