INQUIRE MQMONITOR

Inquire on the status of an installed MQ monitor and return the current attributes of the MQMONITOR resource.

INQUIRE MQMONITOR

Conditions: NOTAUTH, NOTFND

For more information about the use of CVDAs, see CICS-value data areas (CVDAs).

This command is threadsafe.

Description

The INQUIRE MQMONITOR command inquires on the status of an installed MQ monitor and returns the current attributes of the MQMONITOR resource.

Note: Before this command completes, CICS® verifies that the task identified by the TASKNUMBER attribute is actually executing in the region and that the TRANID of the task matches the TRANSACTION value of the MQMONITOR. If either verification fails, CICS considers the MQMONITOR to be stopped.

When you install an MQCONN resource definition in the CICS region with the INITQNAME attribute specified, an MQMONITOR resource with the reserved name of DFHMQINI is also installed. It represents the default initiation queue.

Browsing

You can browse through MQMONITOR definitions in your system by using the browse options START, AT, NEXT, and END, on INQUIRE MQMONITOR commands. See Browsing resource definitions for general information about browsing, including syntax, exception conditions, and examples.

The resource signature

You can use this command to retrieve the resource signature fields. You can use these fields to manage resources by capturing details of when the resource was defined, installed, and last changed. For more information, see Auditing resources. The resource signature fields are BUNDLE, CHANGEAGENT, CHANGEAGREL, CHANGETIME, CHANGEUSRID, DEFINESOURCE, DEFINETIME, INSTALLAGENT, INSTALLTIME, and INSTALLUSRID. See Summary of the resource signature field values for detailed information about the content of the resource signature fields.

Options

AUTOSTART(cvda)

Returns a CVDA value that indicates whether the MQ monitor is started automatically when the connection to the WebSphere® MQ queue manager is established. The possible values are as follows:

AUTOSTART: The MQ monitor is started automatically when the connection to the WebSphere MQ queue manager is established.
NOAUTOSTART: The MQ monitor is not started automatically.

CHANGEAGENT(cvda)

Returns a CVDA value that identifies the agent that made the last change to the resource definition. The possible values are as follows:

AUTOINSTALL: The resource was autoinstalled as a result of specifying an initiation queue name on a CKQC START command, and the previously installed MQCONN definition did not specify a value for INITQNAME.
DYNAMIC: The resource was defined as a result of an MQCONN resource definition with INITQNAME specified.
OVERRIDE: The resource definition was last changed by application of an override rule in the resource overrides file.

CHANGEAGREL(data-area)

Returns a 4-digit number of the CICS release that was running when the resource definition was last changed.

CHANGETIME(data-area)

Returns an ABSTIME value that represents the time stamp when the resource definition was last changed. For more information about the format of the ABSTIME value, see FORMATTIME.

CHANGEUSRID(data-area)

Returns the 8-character user ID that ran the change agent.

DEFINESOURCE(data-area)

Returns the 8-character source of the resource definition. The DEFINESOURCE value depends on the CHANGEAGENT value. For more information, see Summary of the resource signature field values.

DEFINETIME(data-area)

Returns an ABSTIME value that represents the time stamp when the resource definition was created.

ENABLESTATUS(cvda)

Returns a CVDA value that indicates the status of the MQMONITOR resource. The possible values are as follows:

ENABLED: The MQMONITOR resource is enabled for use.
ENABLING: The MQMONITOR resource is enabling.
DISABLED: The MQMONITOR resource is disabled.
DISABLING: The MQMONITOR resource is disabling.
DISCARDING: The MQMONITOR resource is being discarded.

INSTALLAGENT(cvda)

Returns a CVDA value that identifies the agent that installed the resource. The possible values are as follows:

AUTOINSTALL: The resource was autoinstalled as a result of specifying an initiation queue name on a CKQC START command, and the previously installed MQCONN definition did not specify a value for INITQNAME.
DYNAMIC: The resource was installed as a result of the installation of an MQCONN with INITQNAME specified.
CREATESPI: The resource was installed by an EXEC CICS CREATE command.
CSDAPI: The resource was installed by a CEDA transaction or the programmable interface to DFHEDAP.
GRPLIST: The resource was installed by GRPLIST INSTALL.

INSTALLTIME(data-area)

Returns an ABSTIME value that represents the time stamp when the resource was installed.

INSTALLUSRID(data-area)

Returns the 8-character user ID that installed the resource.

MONDATA(data-area)

Displays the data that is passed to the transaction monitoring the MQ queue.

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.

MONSTATUS(cvda)

Returns a CVDA value that indicates the status of the MQ monitor. The possible values are as follows:

STARTED: The MQ monitor is started.
STARTING: The MQ monitor is starting.
STOPPED: The MQ monitor is stopped.
STOPPING: The MQ monitor is stopping.

Note: Before this command completes, CICS verifies that the task identified by the TASKNUMBER attribute is actually executing in the region and that the TRANID of the task matches the TRANSACTION value of the MQMONITOR. If either verification fails, CICS considers the MQMONITOR to be stopped.

MONUSERID(data-area)

Returns the userid that is 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). 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 the 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).

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.

QNAME(data-area)

Returns the name of the MQ queue that is being monitored by the MQ monitor.

TASKNUMBER(data-area)

Returns the number of the task that is currently monitoring the MQ queue.

TRANSACTION(data-area)

Returns the 4-character ID of the CICS transaction monitoring the MQ queue.

USERID(data-area)

Returns the 8-character user ID to be used by default for issuing the start request for the application transaction if a suitable user ID is not available from any other source.

Conditions

NOTAUTH

RESP2 values:

100: Command authorization failure.

NOTFND

RESP2 values:

1: The specified MQMONITOR resource cannot be found.