MQTM - Trigger message

The MQTM structure describes the data in the trigger message that is sent by the queue manager to a trigger-monitor application when a trigger event occurs for a queue. This structure is part of the IBM® MQ Trigger Monitor Interface (TMI), which is one of the IBM MQ framework interfaces.

Format name

MQFMT_TRIGGER.

Character set and encoding

Character data in MQTM is in the character set of the queue manager that generates the MQTM. Numeric data in MQTM is in the machine encoding of the queue manager that generates the MQTM.

The character set and encoding of the MQTM are given by the CodedCharSetId and Encoding fields in:

The MQMD (if the MQTM structure is at the start of the message data), or
The header structure that precedes the MQTM structure (all other cases).

Usage

A trigger-monitor application might need to pass some or all of the information in the trigger message to the application that the trigger-monitor application starts. Information that might be needed by the started application includes QName, TriggerData, and UserData. The trigger-monitor application can pass the MQTM structure directly to the started application, or pass an MQTMC2 structure instead, depending on what is permitted by the environment and convenient for the started application. For information about MQTMC2, see MQTMC2 - Trigger message 2 (character format).

On z/OS®, for an MQAT_CICS application that is started using the CKTI transaction, the entire trigger message structure MQTM is made available to the started transaction; the information can be retrieved by using the EXEC CICS RETRIEVE command.
On IBM i, the trigger-monitor application provided with IBM MQ passes an MQTMC2 structure to the started application.

For information about using triggers, see Starting IBM MQ applications using triggers.

Fields

Note: In the following table, the fields are grouped by usage rather than alphabetically. The child topics follow the same sequence.

Table 1. Fields in MQTM for MQTM
Field name and description	Name of constant	Initial value (if any) of constant
StrucId (structure identifier)	MQTM_STRUC_ID	`'TM¬¬'`
Version (structure version number)	MQTM_VERSION_1	`1`
QName (name of triggered queue)	None	Null string or blanks
ProcessName (name of process object)	None	Null string or blanks
TriggerData (trigger data)	None	Null string or blanks
ApplType (application type	None	`0`
ApplId (application identifier)	None	Null string or blanks
EnvData (environment data)	None	Null string or blanks
UserData (user data)	None	Null string or blanks
Notes: The symbol `¬` represents a single blank character. The value Null string or blanks denotes the null string in C, and blank characters in other programming languages. In the C programming language, the macro variable MQTM_DEFAULT contains the values that are listed in the table. Use it in the following way to provide initial values for the fields in the structure: `MQTM MyTM = {MQTM_DEFAULT};`

Language declarations

C declaration for MQTM


typedef struct tagMQTM MQTM;
struct tagMQTM {
  MQCHAR4    StrucId;      /* Structure identifier */
  MQLONG     Version;      /* Structure version number */
  MQCHAR48   QName;        /* Name of triggered queue */
  MQCHAR48   ProcessName;  /* Name of process object */
  MQCHAR64   TriggerData;  /* Trigger data */
  MQLONG     ApplType;     /* Application type */
  MQCHAR256  ApplId;       /* Application identifier */
  MQCHAR128  EnvData;      /* Environment data */
  MQCHAR128  UserData;     /* User data */
};

COBOL declaration for MQTM


**   MQTM structure
  10 MQTM.
**    Structure identifier
   15 MQTM-STRUCID     PIC X(4).
**    Structure version number
   15 MQTM-VERSION     PIC S9(9) BINARY.
**    Name of triggered queue
   15 MQTM-QNAME       PIC X(48).
**    Name of process object
   15 MQTM-PROCESSNAME PIC X(48).
**    Trigger data
   15 MQTM-TRIGGERDATA PIC X(64).
**    Application type
   15 MQTM-APPLTYPE    PIC S9(9) BINARY.
**    Application identifier
   15 MQTM-APPLID      PIC X(256).
**    Environment data
   15 MQTM-ENVDATA     PIC X(128).
**    User data
   15 MQTM-USERDATA    PIC X(128).

PL/I declaration for MQTM


dcl
 1 MQTM based,
  3 StrucId     char(4),       /* Structure identifier */
  3 Version     fixed bin(31), /* Structure version number */
  3 QName       char(48),      /* Name of triggered queue */
  3 ProcessName char(48),      /* Name of process object */
  3 TriggerData char(64),      /* Trigger data */
  3 ApplType    fixed bin(31), /* Application type */
  3 ApplId      char(256),     /* Application identifier */
  3 EnvData     char(128),     /* Environment data */
  3 UserData    char(128);     /* User data */

High Level Assembler declaration for MQTM


MQTM              DSECT
MQTM_STRUCID      DS   CL4    Structure identifier
MQTM_VERSION      DS   F      Structure version number
MQTM_QNAME        DS   CL48   Name of triggered queue
MQTM_PROCESSNAME  DS   CL48   Name of process object
MQTM_TRIGGERDATA  DS   CL64   Trigger data
MQTM_APPLTYPE     DS   F      Application type
MQTM_APPLID       DS   CL256  Application identifier
MQTM_ENVDATA      DS   CL128  Environment data
MQTM_USERDATA     DS   CL128  User data
*
MQTM_LENGTH       EQU  *-MQTM
                  ORG  MQTM
MQTM_AREA         DS   CL(MQTM_LENGTH)

Visual Basic declaration for MQTM


Type MQTM
  StrucId     As String*4   'Structure identifier'
  Version     As Long       'Structure version number'
  QName       As String*48  'Name of triggered queue'
  ProcessName As String*48  'Name of process object'
  TriggerData As String*64  'Trigger data'
  ApplType    As Long       'Application type'
  ApplId      As String*256 'Application identifier'
  EnvData     As String*128 'Environment data'
  UserData    As String*128 'User data'
End Type

MQMD for a trigger message

Table 2. Settings for the fields in the MQMD of a trigger message generated by the queue manager
Field in MQMD	Value used
`StrucId`	MQMD_STRUC_ID
`Version`	MQMD_VERSION_1
`Report`	MQRO_NONE
`MsgType`	MQMT_DATAGRAM
`Expiry`	MQEI_UNLIMITED
`Feedback`	MQFB_NONE
`Encoding`	MQENC_NATIVE
`CodedCharSetId`	Queue manager's CodedCharSetId attribute
`Format`	MQFMT_TRIGGER
`Priority`	Initiation queue's DefPriority attribute
`Persistence`	MQPER_NOT_PERSISTENT
`MsgId`	A unique value
`CorrelId`	MQCI_NONE
`BackoutCount`	0
`ReplyToQ`	Blanks
`ReplyToQMgr`	Name of queue manager
`UserIdentifier`	Blanks
`AccountingToken`	MQACT_NONE
`ApplIdentityData`	Blanks
`PutApplType`	MQAT_QMGR, or as appropriate for the message channel agent
`PutApplName`	First 28 bytes of the queue manager name
`PutDate`	Date when trigger message is sent
`PutTime`	Time when trigger message is sent
`ApplOriginData`	Blanks

An application that generates a trigger message is recommended to set similar values, except for the following:

The Priority field can be set to MQPRI_PRIORITY_AS_Q_DEF (the queue manager will change this to the default priority for the initiation queue when the message is put).
The ReplyToQMgr field can be set to blanks (the queue manager will change this to the name of the local queue manager when the message it put).
Set the context fields as appropriate for the application.