GET
Use the HTTP GET method with the qmgr
resource to request basic
information and status information about queue managers.
The information that is returned is similar to the information that is returned by the dspmq (display queue managers) control command, the DISPLAY QMSTATUS MQSC command, and the Inquire Queue Manager Status PCF command. You can also obtain status for high availability (HA) and disaster recovery (DR) configurations on the IBM® MQ Appliance as returned by dspmq -o HA and dspmq -o DR (see dspmq (display queue managers) in the Appliance documentation).
Resource URL
https://host:port/ibmmq/rest/v2/admin/qmgr/{qmgrName}
- qmgrName
- Optionally specifies the name of the queue manager to query.
You can use HTTP instead of HTTPS if you enable HTTP connections. For more information about enabling HTTP, see Configuring HTTP and HTTPS ports.
Optional query parameters
- attributes={extended|*|extended.attributeName,...}
- This parameter is only available on the IBM MQ Appliance, AIX®, Linux®, and Windows.
- status={status|*|status.attributeName,...}
-
- status
- Specifies that all status attributes are returned.
- *
- Specifies all attributes. This parameter is equivalent to status.
- status.attributeName,...
- Specifies a comma-separated list of queue manager status attributes to return.
- state=state
- Specifies that only queue managers with the specified state are returned. The following values
are valid values:On all platforms:
- running
- ended
On AIX, Linux, and Windows:- endedImmediately
- endedPreemptively
- endedUnexpectedly
- starting
- quiescing
- endingImmediately
- endingPreemptively
- beingDeleted
- stateNotAvailable
- runningAsStandby
- runningElsewhere
- ha={*|ha|attributeName,…}
-
Specifies that HA information is returned for HA queue managers. You can specify that all HA attributes are returned (
*
orha
), or specify particular attributes (one or more ofha.type
,ha.floatingIPAddress
, andha.floatingIPInterface
). You can combine DR attributes with any other attributes of theqmgr
resource.If you specify this attribute on a platform other than IBM MQ Appliance, the response is
bad request 400
. - dr={*|dr|attributeName,…}
-
Specifies that DR information is returned for DR queue managers. You can specify that all DR attributes are returned (
*
ordr
), or specify particular attributes (dr.replicationPort
ordr.remoteIPAddress
). You can combine DR attributes with any other attributes of theqmgr
resource.If you specify this attribute on a platform other than IBM MQ Appliance, the response is
bad request 400
.
Request headers
- Authorization
- This header must be sent if you are using basic authentication. For more information, see Using HTTP basic authentication with the REST API.
- ibm-mq-rest-gateway-qmgr
- This header specifies the queue manager that is to be used as the gateway queue manager. The gateway queue manager is used to connect to a remote queue manager. For more information, see Remote administration using the REST API.
Request body format
None.
Security requirements
The caller must be authenticated to the mqweb server and must be a member of
one or more of the MQWebAdmin
, MQWebAdminRO
, or
MQWebUser
roles. For more information about security for the administrative REST API, see IBM MQ Console and REST API security.
If token based security is used, the LTPA token that is used to authenticate the user must be provided with the request as a cookie. For more information about token-based authentication, see Using token-based authentication with the REST API.
- On the IBM MQ Appliance, AIX, Linux, and Windows:
- To return the
started
,channelInitatorState
,ldapConnectionState
, orconnectionCount
attributes, authority to issue the MQCMD_INQUIRE_Q_MGR_STATUS PCF command must be granted. - To return the
publishSubscribeState
attribute, authority to issue the MQCMD_INQUIRE_PUBSUB_STATUS PCF command must be granted.
- To return the
- On z/OS®:
- To return the
started
attribute, authority to issue the MQCMD_INQUIRE_LOG PCF command must be granted. - To return the
channelInitiatorState
attribute, authority to issue the MQCMD_INQUIRE_CHANNEL_INIT PCF command must be granted. - To return the
connectionCount
attribute, authority to issue the MQCMD_INQUIRE_CONNECTION PCF command must be granted. - To return the
publishSubscribeState
attribute, authority to issue the MQCMD_INQUIRE_PUBSUB_STATUS PCF command must be granted.
- To return the
On AIX, Linux, and Windows, you can grant authority to security principals to use IBM MQ resources by using the setmqaut command. For more information, see setmqaut (grant or revoke authority).
On z/OS, see Setting up security on z/OS.
Response status codes
- 200
- Queue manager information retrieved successfully.
- 400
- Invalid data provided.
- 401
- Not authenticated.
- 404
- Queue manager does not exist.
- 500
- Server issue or error code from IBM MQ.
Response headers
- Content-Type
- This header is returned with a value of
application/json;charset=utf-8
. - ibm-mq-rest-gateway-qmgr
- This header is returned if a remote queue manager is specified in the resource URL. The value of this header is the name of the queue manager that is used as the gateway queue manager.
Response body format
The response is in JSON format in UTF-8 encoding. The response contains an outer JSON object that
contains a single JSON array called qmgr
. Each element in the array is a JSON
object that represents information about a queue manager. Each JSON object contains the following
attributes:
- name
- String.
- state
- String.
The following objects can be included in the JSON object that represents information about a queue manager. Which objects and attributes are returned depends on the URL that was specified for the request:
- status
- Contains attributes that are related to status information for the queue manager.
- extended
- These attributes are only available on the IBM MQ Appliance, AIX, Linux, and Windows.
- ha
- These attributes are only available on the IBM MQ Appliance.
- dr
- These attributes are only available on the IBM MQ Appliance.
For more information, see Response body attributes for queue managers.
If an error occurs, the response body contains an error message. For more information, see REST API error handling.
Examples for AIX, Linux, and Windows
- The following example gets basic information about all queue managers. The following URL is used
with the HTTP GET method:
https://localhost:9443/ibmmq/rest/v2/admin/qmgr
{ "qmgr": [{ "name": "QM_T1", "state": "endedImmediately" }, { "name": "RESTQM0", "state": "endedUnexpectedly" }] }
- The following example gets extended information about the queue manager
QM_T1
. The following URL is used with the HTTP GET method:https://localhost:9443/ibmmq/rest/v2/admin/qmgr/QM_T1?attributes=extended
{ "qmgr": [{ "extended": { "installationName": "Installation1", "isDefaultQmgr": false, "permitStandby": "notApplicable" }, "name": "QM_T1", "state": "endedImmediately" }] }
- The following example gets specific information about all queue managers. The following URL is
used with the HTTP GET method:
https://localhost:9443/ibmmq/rest/v2/admin/qmgr?attributes=extended.permitStandby
{ "qmgr": [{ "extended": { "permitStandby": "notApplicable" }, "name": "QM_T1", "state": "endedImmediately" }, { "extended": { "permitStandby": "notApplicable" }, "name": "RESTQM0", "state": "endedUnexpectedly" }] }
- The following example gets status for the queue manager
QM1
. The following URL is used with the HTTP GET method:http://localhost:9443/ibmmq/rest/v2/admin/qmgr/QM1?status=*
{ "qmgr": [{ "name": "QM1", "state": "running", "status": { "started":"2016-11-08T11:02:29.000Z", "channelInitiatorState":"running", "ldapConnectionState":"disconnected", "connectionCount":23, "publishSubscribeState":"running" } }] }
Examples for IBM MQ Appliance
- The following example gets HA information from all queue managers on the appliance. The
following URL is used with the HTTP GET method:
In the example configuration, there is one HA queue manager named HAQM1. The following JSON response is returned:https://appliance.example.com:5554/ibmmq/rest/v2/admin/qmgr/?ha=*
{ "qmgr": [ { "name": "HAQM1", "ha": { "floatingIPAddress": "172.20.37.16", "floatingIPInterface": "eth22", "type": "replicated" }, "state": "endedImmediately" } ] }
- The following example gets DR information from all queue managers on the appliance. The
following URL is used with the HTTP GET method:
In the example configuration, there is one DR queue manager named DRQM1. The following JSON response is returned:https://appliance.example.com:5554/ibmmq/rest/v2/admin/qmgr/?dr=*
{ "qmgr": [ { "name": "DRQM1", "state": "endedUnexpectedly", "dr": { "remoteIPAddress": [ "172.20.39.0" ], "replicationPort": 1419 } ] }
- The following example gets extended information about the queue manager QM1. The following URL
is used with the HTTP GET method:
https://appliance.example.com:5554/ibmmq/rest/v2/admin/qmgr/QM1?attributes=extended
The following JSON response is returned:{ "qmgr": [{ "extended": { "installationName": "MQAppliance", "isDefaultQmgr": false, "encryptedFileSystem": "yes" }, "name": "QM1", "state": "endedImmediately" }] }
Examples for z/OS
- The following example gets basic information about all queue managers. The following URL is used
with the HTTP GET method:
https://REST.example.com:9443/ibmmq/rest/v2/admin/qmgr
{ "qmgr": [{ "name": "MQ5B", "state": "ended" }] }