MQMONITOR resource definitions

An MQMONITOR resource defines attributes for IBM® MQ message consumers, such as the trigger monitor transaction CKTI. Using an MQMONITOR enables the associated transaction that services an MQ queue to restart automatically when the connection to the IBM MQ queue manager is established.

You can use MQMONITOR resources to process incoming messages on MQ queues including initiation queues. You can have more than one MQMONITOR resource processing incoming messages on an MQ queue.

An installed and started MQMONITOR resource monitors the MQ queue that is either specified in the resource attribute QNAME or supplied to the transaction through the MONDATA attribute.

When you define an MQMONITOR resource for processing incoming messages on an MQ initiation queue, ensure that the TRANSACTION attribute specifies CKTI or is blank and that the QNAME attribute specifies the name of the MQ initiation queue to be monitored.

When a user-written MQ monitor program, rather than the default CKTI, is to be used with an MQMONITOR resource, it is the responsibility of the user-written program to get messages directly from application queues and perform the required logic. When you code your program, ensure to follow the guidelines described in Developing and using user-written MQ trigger monitors and MQ message consumers.

In order for CICS® to attempt to automatically start the transaction associated with an MQMONITOR, the MQMONITOR must be installed with attributes AUTOSTART(YES) and STATUS(ENABLED). When the connection between CICS and MQ has been established, CICS will start MQ monitors that have been installed with attributes AUTOSTART(YES) and STATUS(ENABLED) if the user ID associated with the task that set the MQCONN resource to CONNECTED has sufficient authority to start the associated transactions.

MQMONITORs are automatically stopped when CICS disconnects from the IBM MQ queue manager.

What affects MQMONITORs

Active z/OS® Workload Manager Health service: If z/OS Workload Manager Health service is active in the CICS region, the MQMONITOR reacts to the region's health state and might be subject to the setting of the z/OS Workload Manager Health service open status. For details, see Effect of z/OS Workload Manager Health service on MQMONITOR resources.
CICS under MXT condition: If CICS encounters an MXT condition, a restriction is imposed on the number of MQGET calls an MQMONITOR can issue per second while this condition exists. For more information, see Alert monitor (CKAM).

Note: To determine whether MXT gating has taken place, see Interpreting transaction statistics.

Installation considerations

You can install an MQMONITOR only if you have previously installed an MQCONN. See Defining and installing MQMONITOR resources for instructions.
When you define an MQMONITOR, CICS checks for consistency with other resource definitions in the same group or list. For more information, see Defining and installing MQMONITOR resources.

For information about working with BAS, see Working with BAS MQMONITOR resource definitions.

Security considerations

User ID for the transaction

If security checking is active (that is, the SEC system initialization parameter is set to YES), the user ID to be associated with the transaction is obtained from the MONUSERID attribute of the MQMONITOR resource.

If security checking is disabled (that is, SEC is set to NO), the user ID to be associated with the MQ monitor transaction is the user ID of the transaction that set the state of the MQMONITOR resource to started.

Security checks performed by CICS when setting the MQ monitor state to started

If security checking is active, when setting the MQ monitor state to started, CICS performs security checks on the user ID of the transaction that attempts to set the MQ monitor state to started, as follows:

Note: In the case of setting the MQ monitor state through a CICSPlex® SM API interface such as CICS Explorer®, the user ID to be associated with the MQ monitor transaction is either the region user ID or the PLTPIUSR user ID (if specified).

CICS verifies that the user ID is a surrogate of the user ID defined in MONUSERID.
CICS verifies that the user ID is authorized to start transactions associated with the user ID defined in MONUSERID.

DFHMQINI

When you install an MQCONN resource that specifies a value in the INITQNAME attribute, CICS also dynamically creates and installs an MQMONITOR resource with the reserved name of DFHMQINI representing the default initiation queue.

DFHMQINI has the following attributes:

QNAME

Specifies the initiation queue name.

TRANSACTION

CKTI (by default)

MONUSERID

This attribute is obtained as follows:

From the PLTPIUSR system initialization parameter, if available
Otherwise, from the CICS region user ID

USERID

The value is the CICS default user ID.

DFHMQINI is automatically started when the MQ connection is established, and the user ID associated with the CKTI transaction is obtained from MONUSERID.

You can use the EXEC CICS INQUIRE MQMONITOR or CEMT INQUIRE MQMONITOR command to inquire on the QNAME attribute of the dynamically created MQMONITOR resource. If you want to change this QNAME value, you must first change the INITQNAME attribute of the MQCONN resource and then reinstall the MQCONN resource. When you discard an MQCONN resource that includes a setting for the INITQNAME attribute, the dynamically created MQMONITOR resource and any user-defined MQMONITOR resources are also discarded.

Syntax

Queue monitor attributes

Application attributes

Attributes

AUTOSTART({YES|NO})

Specifies whether to start the MQ monitor automatically.

YES

The MQ monitor is started automatically in either of the following situations:

When the connection to the IBM MQ queue is established.
If the z/OS Workload Manager (WLM) health service is active (see WLMHEALTH), every increment in the z/OS WLM HEALTH value of the CICS region from zero to 100%. For more information, see Effect of z/OS Workload Manager Health service on MQMONITOR resources and Alert monitor (CKAM).

NO

The MQ monitor is not started automatically.

DESCRIPTION(text)

In this field, you can provide a description of the resource that you are defining. The description text can be up to 58 characters in length. No restrictions apply to the characters that you can use. However, if you use parentheses, ensure that each opening parenthesis ( has a matching closing one ). If you use the CREATE command, for each single apostrophe in the text code, use two apostrophes.

GROUP(groupname)

Every resource definition must have a GROUP name. The resource definition becomes a member of the group and is installed in the CICS system when the group is installed.

Acceptable characters:

A-Z 0-9 $ @ #

Valid characters are listed as they render when the code page is IBM-037. If a different EBCDIC code page is used, be aware of variant characters, as documented in Variant characters.

Any lowercase characters that you enter are converted to uppercase.

The GROUP name can be up to 8 characters in length.

MQMONITOR(name)

Specifies the 8-character name of this resource definition.

Acceptable characters:

A-Z 0-9 $ @ #

Valid characters are listed as they render when the code page is IBM-037. If a different EBCDIC code page is used, be aware of variant characters, as documented in Variant characters.

Unless you are using the CREATE command, any lowercase characters that you enter are converted to uppercase.

MONDATA(text)

You can specify data to be passed to the transaction monitoring the MQ queue. For example, you can use this field to pass parameters to the MQ bridge monitor transaction CKBR. The attribute can contain up to 200 mixed-case characters.

Note:

When displayed and retrieved by the monitoring task, the MONDATA data is prepended with the following 18 bytes:

Byte 1: < (left chevron)
Bytes 2 - 9: MQMONITOR resource name
Bytes 10 - 17: USERID
Byte 18: > (right chevron)

Bytes 19 - 218 contains MONDATA as entered by the user.

Therefore, user-written programs must allow for a maximum length of 218 bytes to retrieve MONDATA, and use the MQMONITOR name as specified in bytes 2 - 9 from the retrieved MONDATA for setting the MONSTATUS attribute of the MQ monitor, thereby indicating its current status. Also note that when security checking is active, CICS performs security checks on the user ID associated with the transaction that attempts to set the MQ monitor state to started. For more information, see the security considerations described in MQMONITOR resources.

Any user-defined character strings &applid. or &APPLID. will be replaced by the APPLID of the local region when the MQMONITOR is installed. This will facilitate generic use of this resource.

MONUSERID(userid)

Specifies the user ID to be associated with the transaction monitoring the MQ queue. This attribute is only effective when security checking is active (that is, the SEC system initialization parameter is set to YES). If security checking is disabled (that is, SEC is set to NO), the user ID to be associated with the MQ monitor transaction is the user ID of the transaction that set the state of the MQMONITOR resource to started.

Note: If security checking is active, CICS verifies that the user ID associated with the transaction that attempts to set the MQ monitor state to started is a surrogate of the user ID defined in MONUSERID and is authorized to start transactions associated with the MONUSERID. In the case of setting the MQ monitor state through a CICSPlex SM API interface such as CICS Explorer, the user ID to be associated with the MQ monitor transaction is either the region user ID or the PLTPIUSR user ID (if specified).

QNAME(name)

Specifies the name of the MQ queue to be monitored.

When you specify the QNAME attribute, you can use one or more symbolic parameters, &applid. or &APPLID., anywhere in the value to identify the APPLID of a CICS region. Any user-defined character strings &applid. or &APPLID. will be replaced by the APPLID of the local region when the MQMONITOR is installed. This will facilitate generic use of this resource.

If QNAME is omitted, the value is set to &APPLID..INITIATION.QUEUE by default when the resource is installed.

STATUS({ENABLED|DISABLED})

Specifies the initial status of the MQMONITOR resource when it is installed.

DISABLED: The MQMONITOR resource is not available for use.
ENABLED: The MQMONITOR resource is available for use.

TRANSACTION(name)

Specifies the 4-character ID of the CICS transaction that is used by the task monitoring the MQ queue.

If TRANSACTION is omitted, the value is set to CKTI by default.

USERID(id)

Specifies the user ID to be used by default for starting the transaction associated with the application if no suitable user ID is available from any other source.

If USERID is omitted, the CICS default user ID is used.