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 you 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.

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.

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.
A period (.) must be encoded as %2E.

queueName

Optionally specifies the name of a queue that exists on the queue manager specified.

The queue name is case-sensitive.

If the queue name includes a forward slash 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.

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={object,...|*|object.attributeName,...}

object,...: Specifies a comma-separated list of JSON objects that contain related queue configuration attributes to return.; For example, to return all queue configuration attributes that are related to time stamps, specify timestamps. To return all queue configuration attributes that are related to storage and to data collection, specify storage,dataCollection.; The status and applicationHandle objects cannot be specified with this query parameter. Use the status and applicationHandle query parameters to return these attributes.; You cannot specify the same object more than once. If you request objects that are not valid for a particular queue, the attributes are not returned for that queue. However, if you specify a value for the type parameter that is not all, and request objects that are not valid for that queue type, an error is returned.; For a full list of objects and associated attributes, see Attributes for queues.
*: Specifies all attributes.
object.attributeName,...: Specifies a comma-separated list of queue configuration attributes to return.; Each attribute must specify the JSON object that contains the attribute, in the form object.attributeName. For example, to return the maximumDepth attribute, which is contained in the storage object, specify storage.maximumDepth.; Attributes from the status and applicationHandle objects cannot be specified with this query parameter. Use the status and applicationHandle query parameters to return these attributes.; You cannot specify the same attribute more than once. If you request attributes that are not valid for a particular queue, the attributes are not returned for that queue. However, if you specify the type parameter and request attributes that are not valid for that queue type, an error is returned.; For a full list of attributes and associated objects, see Attributes for queues.

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.; For example, to return the currentDepth attribute, specify status.currentDepth.; For a full list of status attributes, see Status attributes for queues.

If you specify the status optional query parameter, you can specify the type parameter only with the all or local values. You cannot specify the queueSharingGroupDisposition parameter with the group value.

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.; For example, to return the handleState attribute, specify applicationHandle.handleState.; For a full list of application handle attributes, see Application handle attributes for queues.

If you specify the applicationHandle optional query parameter, you can specify the type parameter only with the all or local values. You cannot specify the queueSharingGroupDisposition parameter with the group value.

commandScope=scope

This parameter is only available on z/OS.

Specifies how the command is run when the queue manager is a member of a queue sharing group.

You cannot specify this parameter if the queue manager is not a member of a queue sharing group.

scope can be one of the following values:

The name of a queue manager

Specifies that the command is run on the queue manager that is named. The queue manager must be active within the same queue sharing group as the queue manager that is specified in the resource URL.

You cannot specify the queue manager name that is the queue manager that is specified in the resource URL.

If the queue manager name includes a percent sign, %, this character must be URL encoded as %25.

*

Specifies that the command is run on the local queue manager and also passed to every active queue manager in the queue sharing group.

If this option is used, an ibm-mq-qmgrs response 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

filter=filterValue

Specifies a filter for the queue definitions that are returned.

If you specify a queue name in the resource URL, you can only filter on application handle attributes.

If you filter on an application handle attribute, the only application handles returned are those that match the filter parameter.

You can specify only one filter. If you filter on an application handle attribute, you must specify the applicationHandle query parameter. If you filter on a status attribute, you must specify the status query parameter.

filterValue has the following format:

attribute:operator:value

where:

attribute

Specifies one of the applicable attributes. For a full list of attributes, see Attributes for queues. The following attributes cannot be specified:

name
type
queueSharingGroup.disposition
status.onQueueTime
status.tpipeName
applicationHandle.qmgrTransactionId
applicationHandle.unitOfWorkId
applicationHandle.openOptions

To filter on any attributes that are time stamps, the filter can specify any portion of the time stamp, with a trailing asterisk, *. The format of a time stamp is, YYYY-MM-DDThh:mm:ss. For example, you can specify 2001-11-1* to filter on dates in the range 2001-11-10 to 2001-11-19, or 2001-11-12T14:* to filter any minute in the specified hour of the specified day.

Valid values for the YYYY section of the date are in the range 1900 - 9999.

The time stamp is a string. Therefore, only the equalTo and notEqualTo operators can be used with the time stamp.

Note: If either the filter query parameter, or the name query parameter with a wildcard, are used with the commandScope=* query parameter, and there are no matching queues on at least one of the active queue managers in the queue sharing group, then an error message is returned.

operator

Specifies one of the following operators:

lessThan: Use this operator only with integer attributes.
greaterThan: Use this operator only with integer attributes.
equalTo: Use this operator with any attribute.
notEqualTo: Use this operator with any attribute.
lessThanOrEqualTo: Use this operator only with integer attributes.
greaterThanOrEqualTo: Use this operator only with integer attributes.

value

Specifies the constant value to test against the attribute.

The value type is determined by the attribute type.

For string and boolean attributes, you can omit the value field after the colon. For string attributes, omit the value to return queues with no value for the specified attribute. For boolean attributes, omit the value to return any queues that have the specified attribute set to false. For example, the following filter returns all queues where the description attribute is not specified:

filter=general.description:equalTo:

You can use a single asterisk, *, at the end of the value as a wildcard. You cannot use only an asterisk.

If the value includes a space, a forward slash, a percent sign, or an asterisk that is not a wildcard, these characters must be URL encoded:

A space must be encoded as %20
A forward slash, /, must be encoded as %2F.
A percent sign, %, must be encoded as %25.
An asterisk, *, must be encoded as %2A.

If the filter query parameter is used with the commandScope=* query parameter, and there are no matching values on at least one of the active queue managers in the queue sharing group, an error message is returned.

name=name

This query parameter cannot be used if you specify a queue name in the resource URL.

Specifies a wildcard queue name to filter on.

The name specified must include an asterisk, *, as a wildcard. You can specify one of the following combinations:

*: Specifies that all queues are returned.
prefix*: Specifies that all queues with the specified prefix in the queue name are returned.
*suffix: Specified that all queues with the specified suffix in the queue name are returned.
prefix*suffix: Specifies that all queues with the specified prefix and the specified suffix in the queue name are returned.

If the name query parameter is used with a wildcard, the commandScope=* query parameter is specified, and there are no matching values on at least one of the active queue managers in the queue sharing group, an error message is returned.

queueSharingGroupDisposition=disposition

This parameter is only available on z/OS.

Specifies where the queue for which information is to be returned is defined and how it behaves. That is, it specifies the disposition of the queue for which information is to be returned.

You cannot specify the queueSharingGroupDisposition parameter if you specify type=cluster for the type parameter.

The value can be one of the following values:

live: Specifies that the queue is defined as qmgr or copy.; In a shared queue manager environment, live also displays information for queues that are defined with shared.; If the commandScope optional query parameter is specified with the live option, then any queue definitions with a disposition of shared are returned only by the queue manager that received the REST request. Other queue managers in the group do not return these queue definitions.; If you specify live with the attributes parameter, and specify the commandScope parameter with a queue manager name, queue attributes are not returned for shared queues.
all: Specifies that the queue is defined as qmgr or copy.; In a shared queue manager environment, all also displays information for queues that are defined with group or shared.; If the commandScope optional query parameter is specified with all, then any queue definitions with a disposition of group or shared are returned only by the queue manager that received the REST request. Other queue managers in the group do not return these queue definitions.; If you specify all with the attributes parameter, and specify the commandScope parameter with a queue manager name, queue attributes are not returned for shared queues.; If you specify all and specify type=all, no cluster queues are returned.
copy: Specifies that the queue is defined as copy.
group: Specifies that the queue is defined as group.; If you specify group, you cannot specify the commandScope optional query parameter.
private: Specifies that the queue is defined as copy or qmgr.
qmgr: Specifies that the queue is defined as qmgr.
shared: Specifies that the queue is defined as shared.; You cannot specify the commandScope optional query parameter with this option, unless the status or applicationHandle optional query parameter is also specified.; You cannot specify this option with the attributes parameter if you also specify the commandScope parameter with a queue manager name.; If you specify shared and specify type=all, all shared queues are returned, including cluster queues with a disposition of shared.

The default value is live.

type=type

Specifies the type of queue to return information about.

The value can be one of the following values:

all: Specifies that information about all queues, including cluster queues, is returned.; On z/OS, ensure that the channel initiator is running when you use this option.
local: Specifies that information about local queues is returned.
alias: Specifies that information about alias queues is returned.
remote: Specifies that information about remote queues is returned.
cluster: Specifies that information about cluster queues is returned.; You cannot specify type=cluster if you specify the queueSharingGroupDisposition parameter.; On z/OS, ensure that the channel initiator is running when you use this option.
model: Specifies that information about model queues is returned.

The default value is all.

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

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.

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.

[UNIX, Linux, Windows] On UNIX, 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).

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

Response status codes

200: Queue information retrieved successfully.
400: Invalid data provided.; For example, invalid queue attributes 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.
403: Not authorized.; The caller is authenticated to the mqweb server and is associated with a valid principal. However, the principal does not have access to all, or a subset of the required IBM MQ resources. For more information about the access that is required, see Security requirements.
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

If an error occurs before the command is issued to the queue managers, the response header does not contain the list of queue managers. For example, a request that generates a 200 or 201 status code has the header because the command was successful. A request that generates a 401 (not authenticated) status code does not have the header because the request was rejected. A request that generates a 403 (not authorized) status code has the header because individual queue managers decide whether the command is authorized.

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.; Specifies the name of the queue.; This attribute is always returned.

type

String.

Specifies the type of queue.

The value is one of the following values:

local
alias
remote
cluster
model

This attribute is always returned.

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.; If a queue has no application handles, but information about application handles is requested, an empty object is returned.

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
```