GET
Use the HTTP GET method with the queue resource to request information about queues.
Note: This resource URL is available only in version 1 of the REST API. To request information about queues using version 2 of the REST API, use the /admin/action/qmgr/{qmgrName}/mqsc resource.The information that is returned is similar to the information returned by the Inquire Queue and Inquire Queue Status PCF commands, and the DISPLAY QUEUE and DISPLAY QSTATUS MQSC commands.
Note: On z/OS, the channel initiator must be running before we use the queue resource with the HTTP GET method in either of the following situations:- The type optional query parameter is not specified.
- The type optional query parameter is specified as either all or cluster.
- Resource URL
- Optional query parameters
- Request headers
- Request body format
- Security requirements
- Response status codes
- Response headers
- Response body format
- Examples
Resource URL
https://host:port/ibmmq/rest/v1/admin/qmgr/{qmgrName}/queue/{queueName}
- qmgrName
- Specifies the name of the queue manager on which to query the queues.
- queueName
- Optionally specifies the name of a queue that exists on the queue manager specified.
We can use HTTP instead of HTTPS if you enable HTTP connections. For more information about enabling HTTP, see Configure HTTP and HTTPS ports.
Optional query parameters
- attributes={object,...|*|object.attributeName,...}
-
- object,...
- Specifies a comma-separated list of JSON objects that contain related queue configuration attributes to return.
- *
- Specifies all attributes.
- object.attributeName,...
- Specifies a comma-separated list of queue configuration attributes to return.
- 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 status attributes to return.
- applicationHandle={applicationHandle|*|applicationHandle.attributeName,...}
-
- applicationHandle
- Specifies that all application handle attributes are returned.
- *
- Specifies all attributes. This parameter is equivalent to applicationHandle.
- applicationHandle.attributeName,...
- Specifies a comma-separated list of application handle attributes to return.
- commandScope=scope
This parameter is only available on z/OS.- filter=filterValue
- Specifies a filter for the queue definitions that are returned.
- name=name
- This query parameter cannot be used if we specify a queue name in the resource URL.
- queueSharingGroupDisposition=disposition
- This parameter is only available on z/OS.
- type=type
- Specifies the type of queue to return information about.
Request headers
The following headers must be sent with the request:
- Authorization
- This header must be sent if we are using basic authentication. For more information, see Use 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
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 Use token-based authentication with the REST API.
The security principal of the caller must be granted the ability to issue the following PCF commands for the specified queue manager:- If the status or applicationHandle query parameters
are not specified:
- For the queue that is specified by the {queueName} portion of the resource URL, or for queues that match the specified query parameters, authority to issue the MQCMD_INQUIRE_Q PCF command must be granted.
- If the status or applicationHandle query parameters
are specified:
- For the queue that is specified by the {queueName} portion of the resource URL, or for queues that match the specified query parameters, authority to issue the MQCMD_INQUIRE_Q PCF command must be granted.
- For the queue that is specified by the {queueName} portion of the resource URL, or for queues that match the specified query parameters, authority to issue the MQCMD_INQUIRE_QSTATUS PCF command must be granted.
A principal has display authority if the principal can issue one or both of the MQCMD_INQUIRE_Q and MQCMD_INQUIRE_QSTATUS PCF commands. If the principal has display authority for only some of the queues that are specified by the resource URL and query parameters, then the array of queues that is returned from the REST request is limited to those queues that the principal has authority to display. No information is returned about queues that cannot be displayed. If the principal does not have display authority for any of the queues that are specified by the resource URL and query parameters, an HTTP status code of 403 is returned.
On UNIX, Linux, and Windows, we 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 Set up security on z/OS.
Response status codes
- 200
- Queue information retrieved successfully.
- 400
- Invalid data provided.
- 401
- Not authenticated.
- 403
- Not authorized.
- 404
- Queue does not exist.
- 500
- Server issue or error code from IBM MQ.
- 503
- Queue manager not running.
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-qmgrs
- On z/OS, if the optional query parameter
commandScope=* is used, this header is returned with a comma-separated list of the queue managers
that generated a response. For example, the header might look like the following header:
ibm-mq-qmgrs: MQ21, MQ22
- 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 queue. Each element in the array is a JSON object that represents information about a queue. Each of these JSON objects contains the following attributes:
- name
- String.
- type
- String.
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:
- remote
- Contains attributes that are related to remote queues.
- alias
- Contains attributes that are related to alias queues.
- dynamic
- Contains attributes that are related to dynamic queues.
- model
- Contains attributes that are related to model queues.
- cluster
- Contains attributes that are related to clusters.
- trigger
- Contains attributes that are related to triggering.
- events
- Contains two objects, one for queue depth and one for queue service interval events. Each object contains attributes that are related to the event type.
- applicationDefaults
- Contains attributes that are related to default behavior such as message persistence, message priority, shared input settings, and read ahead settings.
- queueSharingGroup
- Contains attributes that are related to queue sharing groups on z/OS.
- dataCollection
- Contains attributes that are related to data collection, monitoring, and statistics.
- storage
- Contains attributes that are related to message storage, such as the maximum depth of the queue, and the maximum length of messages that are allowed on the queue.
- general
- Contains attributes that are related to general queue properties, such as whether get or put operations are inhibited, the description of the queue, and transmission queue settings.
- extended
- Contains attributes that are related to extended queue properties, such as backout queue settings, and shared input settings.
- timestamps
- Contains attributes that are related to date and time information, such as the time stamp of when a queue was created.
- status
- Contains attributes that are related to queue status information.
- applicationHandle
- Contains attributes that are related to application handle information.
For more information, see Response body attributes for queues.
If a damaged object is found, and the REST request did not specify a queue, an extra JSON array that is called damaged is returned. This JSON array contains a list of the objects that are damaged, specifying the object names. If the REST request specifies a queue name within the resource URL, but the object is damaged, an error is returned.
If an error occurs, the response body contains an error message. For more information, see REST API error handling.
Examples
Note: Information about the SYSTEM.* queues is returned. It is expected that all queues are returned. However, for brevity, the results shown in the following examples do not include all the expected results.- The following example lists all queues on the queue manager QM1. The following
URL is used with the HTTP GET method:
https://localhost:9443/ibmmq/rest/v1/admin/qmgr/QM1/queue
The following JSON response is returned:{ "queue": [{ "name": "localQueue", "type": "local" }, { "name": "remoteQueue", "type": "remote", "remote": { "queueName": "queueOnQM1", "qmgrName": "QM1" } }, { "name": "aliasQueue", "type": "alias", "alias": { "targetName": "localQueue" } }, { "name": "modelQueue", "type": "model", "model": { "type": "permanentDynamic" } }, { "name": "permanentDynamicQueue", "type": "local", "dynamic": { "type": "permanentDynamic" } },{ "name": "aliasQueue2", "type": "cluster", "cluster": { "name": "CLUSTER1", "qmgrName" : "QM2", "queueType": "alias" } }] } - The following example lists all local queues on the queue manager QM1, showing
whether they are get or put enabled. The following URL is used with the HTTP GET method:
https://localhost:9443/ibmmq/rest/v1/admin/qmgr/QMGR2/queue?type=local&attributes=general.inhibitPut,general.inhibitGet
The following JSON response is returned:{ "queue": [{ "name": "localQueue", "type": "local", "general": { "inhibitPut": true, "inhibitGet": false, } }, { "name": "permanentDynamicQueue", "type": "local", "dynamic": { "type": "permanentDynamic" }, "general": { "inhibitPut": false, "inhibitGet": false, } }] } - The following example lists the status attributes for the queue Q1, on queue
manager QM1. The following URL is used with the HTTP GET method:
https://localhost:9443/ibmmq/rest/v1/admin/qmgr/QM1/queue/Q1?status=*
The following JSON response is returned:{ "queue": [{ "name": "Q1", "status": { "currentDepth": 0, "lastGet": "2016-12-05T15:56:28.000Z", "lastPut": "2016-12-05T15:56:28.000Z", "mediaRecoveryLogExtent": "", "oldestMessageAge": 42, "onQueueTime": { "longSamplePeriod": 3275, "shortSamplePeriod": 3275 }, "openInputCount": 1, "openOutputCount": 1, "uncommittedMessages": 2 }, "type": "local" }] } - The following example lists the application handle attributes for a queue Q1,
on queue manager QM1. The following URL is used with the HTTP GET method:
https://localhost:9443/ibmmq/rest/v1/admin/qmgr/QM1/queue/Q1?applicationHandle=*
The following JSON response is returned:{ "queue": [{ "applicationHandle": [{ "asynchronousState": "none", "channelName": "", "connectionName": "", "description": "", “state": "inactive", "openOptions": [ "MQOO_INPUT_SHARED", "MQOO_BROWSE", "MQOO_INQUIRE", "MQOO_SAVE_ALL_CONTEXT", "MQOO_FAIL_IF_QUIESCING" ], "processID": 9388, "qmgrTransactionID": "AAAAAAhAAAA=", "recoveryID": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA==", "tag": "IBM\\Java70\\jre\\bin\\javaw.exe", "threadID": 0, "transactionType": "qmgr", "type": "userApplication", "userID": "myID" }, { "asynchronousState": "none", "channelName": "", "connectionName": "", "description": "", “state": "inactive", "openOptions": [ "MQOO_OUTPUT", "MQOO_FAIL_IF_QUIESCING" ], "processID": 9388, "qmgrTransactionID": "AAAAAAhAAAA=", "recoveryID": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA==", "tag": "IBM\\Java70\\jre\\bin\\javaw.exe", "threadID": 0, "transactionType": "qmgr", "type": "userApplication", "userID": "myID" }], "name": "Q1", "type": "local" }] } -
The following example shows how to get all information, including status and application handles, for the queue Q2 on queue manager QM1. The following URL is used with the HTTP GET method:
https://localhost:9443/ibmmq/rest/v1/admin/qmgr/QM1/queue/Q2?attributes=*&status=*&applicationHandle=*
-
The following example shows how to get all queue configuration and status information for queues with an openInputCount greater than three, for the queue manager QM1. The following URL is used with the HTTP GET method:
https://localhost:9443/ibmmq/rest/v1/admin/qmgr/QM1/queue?attributes=*&status=*&filter=status.openInputCount:greaterThan:3
- Response body attributes for queues
When we use the HTTP GET method with the queue object to request information about queues, the following attributes are returned within named JSON objects.
Parent topic: /admin/qmgr/{qmgrName}/queue