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 control command, the DISPLAY QMSTATUS MQSC command, and the Inquire Queue Manager Status PCF command.

Resource URL
Optional query parameters
Request headers
Request body format
Security requirements
Response status codes
Response headers
Response body format
Examples

Resource URL

[V9.0.4 Oct 2017] IBM® MQ 9.0.4 and later:

https://host:port/ibmmq/rest/v1/admin/qmgr/{qmgrName}

IBM MQ 9.0.3 and earlier:

https://host:port/ibmmq/rest/v1/qmgr/{qmgrName}

qmgrName

Optionally specifies the name of the queue manager to query.

You can specify a remote queue manager as the qmgrName. If you specify a remote queue manager, you must configure a gateway queue manager. For more information, see Remote administration using the REST API.

If you specify a remote queue manager, only the following attributes are returned:

name
started
channelInitiatorState
ldapConnectionState
connectionCount
publishSubscribeState

The queue manager name is case-sensitive.

If the queue manager name includes a forward slash, a period, or a percent sign, these characters must be URL encoded:

A forward slash (/) must be encoded as %2F.
A percent sign (%) must be encoded as %25.

[V9.0.1 Nov 2016] 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, UNIX, Linux®, and Windows.

This parameter is not valid if you specify a remote queue manager in the resource URL.

extended: Specifies that all extended attributes are retrieved.
*: Specifies all attributes. This parameter is equivalent to extended.
extended.attributeName,...: Specifies a comma-separated list of extended attributes to return.; For example, to return the installationName attribute, specify extended.installationName.; For a full list of extended attributes, see Extended attributes for queue managers.

status={status|*|status.attributeName,...}

Note: In IBM MQ 9.0.1, the status optional query parameter was used to filter returned queues based on the running state of the queue. From IBM MQ 9.0.2, this optional query parameter is known as state.

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.; The queue manager must be running to return the status attributes.; For example, to return the connectionCount attribute, specify status.connectionCount.; For a full list of status attributes, see Status attributes for queue managers.

state=state

Note: In IBM MQ 9.0.1, the state optional query parameter was known as status. From IBM MQ 9.0.3, the status optional query parameter is used to retrieve status attributes for the queue manager.

Specifies that only queue managers with the specified state are returned. The following values are valid values:

On all platforms:

running
ended

On UNIX, Linux, and Windows:

endedImmediately
endedPreemptively
endedUnexpectedly
starting
quiescing
endingImmediately
endingPreemptively
beingDeleted
stateNotAvailable
runningAsStandby
runningElsewhere

You can specify the state=state optional query parameter only if you do not specify a queue manager name within the resource URL. That is, you cannot request information about a specific queue manager in a specific state.

Request headers

The following headers must be sent with the request:

Authorization: This header must be sent if you are using basic authentication. For more information, see Using HTTP basic authentication with the REST API.

The following headers can optionally be sent with the request:

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

[V9.0.2 Mar 2017] 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.

When the status optional query parameter is specified, the ability to issue certain PCF commands is required. If only a subset of the status attributes is to be returned, only the permissions for the corresponding PCF commands are required. The security principal of the caller must be granted the ability to issue the following PCF commands for the specified queue manager:

On the IBM MQ Appliance, UNIX, Linux, and Windows:
- To return the started, channelInitatorState, ldapConnectionState, or connectionCount 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.
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.

[UNIX, Linux, Windows] On UNIX, Linux, and Windows, you can grant authority to security principals to use IBM MQ resources by using the mqsetaut command. For more information, see mqsetaut.

[z/OS] On z/OS, see Setting up security on z/OS.

Response status codes

200: Queue manager information retrieved successfully.
400: Invalid data provided.; For example, invalid queue manager specified.
401: Not authenticated.; 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, see Security requirements.
404: Queue manager does not exist.
500: Server issue or error code from IBM MQ.

Response headers

The following headers are returned with the response:

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.

The queue manager name.

state

String.

Note: In IBM MQ 9.0.1, the state attribute was known as status. From IBM MQ 9.0.3, the status object contains status attributes for the queue manager.

This attribute is not returned if the queue manager that is specified in the resource URL is a remote queue manager.

One of the following values:

On all platforms:

running
ended

On UNIX, Linux, and Windows:

endedImmediately
endedPreemptively
endedUnexpectedly
starting
quiescing
endingImmediately
endingPreemptively
beingDeleted
stateNotAvailable
runningAsStandby
runningElsewhere

The following objects can be included in the JSON object that represents information about a queue. 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.; Note: In IBM MQ 9.0.1, the status attribute returned information about the running state of the queue. From IBM MQ 9.0.2, this attribute is known as state.
extended: These attributes are only available on the IBM MQ Appliance, UNIX, Linux, and Windows.; These attributes are not returned if the queue manager that is specified in the resource URL is a remote queue manager.; Contains extended attributes.

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 UNIX, Linux, and Windows

The following example gets basic information about all queue managers. The following URL is used with the HTTP GET method:

IBM MQ 9.0.4 and later:

https://localhost:9443/ibmmq/rest/v1/admin/qmgr

IBM MQ 9.0.3:

https://localhost:9443/ibmmq/rest/v1/qmgr

The following JSON response is returned:

{
    "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:

IBM MQ 9.0.4 and later:

https://localhost:9443/ibmmq/rest/v1/admin/qmgr/QM_T1?attributes=extended

IBM MQ 9.0.3 and earlier:

https://localhost:9443/ibmmq/rest/v1/qmgr/QM_T1?attributes=extended

The following JSON response is returned:

{
    "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:

IBM MQ 9.0.4 and later:

https://localhost:9443/ibmmq/rest/v1/admin/qmgr?attributes=extended.permitStandby

IBM MQ 9.0.3 and earlier:

https://localhost:9443/ibmmq/rest/v1/qmgr?attributes=extended.permitStandby

The following JSON response is returned:

{
    "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:

IBM MQ 9.0.4 and later:

http://localhost:9443/ibmmq/rest/v1/admin/qmgr/QM1?status=*

IBM MQ 9.0.3 and earlier:

http://localhost:9443/ibmmq/rest/v1/qmgr/QM1?status=*

The following JSON response is returned:

{
    "qmgr": 
    [{
        "name": "QM1",
        "state": "running",
        "status":
        {
            "started":"2016-11-08T11:02:29.000Z",
            "channelInitiatorState":"running",
            "ldapConnectionState":"disconnected",
            "connectionCount":23,
            "publishSubscribeState":"running"
        }
    }]
}

Examples for z/OS

The following example gets basic information about all queue managers. The following URL is used with the HTTP GET method:
IBM MQ 9.0.4 and later:
```
https://REST.example.com:9443/ibmmq/rest/v1/admin/qmgr
```
IBM MQ 9.0.3 and earlier:
```
https://REST.example.com:9443/ibmmq/rest/v1/qmgr
```
The following JSON response is returned:
```
{
    "qmgr": [{
        "name": "MQ5B",
        "state": "ended"
    }]
}
```