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.

• remote
• alias
• dynamic
• model
• cluster
• trigger
• events
• applicationDefaults
• queueSharingGroup
• dataCollection
• storage
• general
• extended
• timestamps
• status
• applicationHandle

For more information about the PCF equivalents to the queue REST API parameters and attributes, see REST API and PCF equivalents for queues.

remote

qmgrName

String.

Specifies the name of the remote queue manager.

If this remote queue is used as a queue manager alias, this attribute is the name of the queue manager.

If this remote queue is used as a reply-to queue alias, this attribute is the name of the queue manager that is to be the reply-to queue manager.

This attribute is always returned.

queueName

String.

Specifies the name of the queue as it is known on the remote queue manager.

This attribute is always returned.

transmissionQueueName

String.

Specifies the name of the transmission queue that is used for messages that are destined for either a remote queue or for a queue manager alias definition.

alias

targetName

String.

Specifies the name of the queue or topic that the alias resolves to.

This attribute is always returned.

targetType

String.

Specifies the type of object that the alias resolves to.

The value is one of the following values:

queue

Specifies that the object is a queue.

topic

Specifies that the object is a topic.

dynamic

type

String.

Specifies the type of dynamic queue.

This attribute is always returned.

The value is one of the following values:

permanentDynamic

Specifies that the queue is a dynamically defined permanent queue.

sharedDynamic

This attribute is only available on z/OS .

Specifies that the queue is a dynamically defined shared queue.

temporaryDynamic

Specifies that the queue is a dynamically defined temporary queue.

model

type

String.

Specifies the model queue definition type.

This attribute is always returned.

The value is one of the following values:

permanentDynamic

Specifies that the queue is a dynamically defined permanent queue.

sharedDynamic

This attribute is only available on z/OS.

Specifies that the queue is a dynamically defined shared queue.

temporaryDynamic

Specifies that the queue is a dynamically defined temporary queue.

cluster

name

String.

Specifies the name of the cluster that the queue belongs to.

This attribute, or the namelist attribute, is always returned.

namelist

String.

Specifies the namelist that lists the clusters that the queue belongs to.

This attribute, or the name attribute, is always returned.

qmgrId

String.

Specifies the unique identifier of the queue manager.

This attribute is returned only when type=cluster is specified.

qmgrName

String.

Specifies the name of the local queue manager.

This attribute is returned only when type=cluster is specified.

queueType

String.

Specifies the type of queue.

This attribute is returned only when type=cluster is specified.

The value is one of the following values:

local

Specifies that the cluster queue represents a local queue.

alias

Specifies that the cluster queue represents an alias queue.

remote

Specifies that the cluster queue represents a remote queue.

qmgrAlias

Specifies that the cluster queue represents a queue manager alias.

transmissionQueueForChannelName

String.

Specifies the generic name of the cluster-sender channels that use the queue as a transmission queue. The attribute specifies which cluster-sender channels send messages to a cluster-receiver channel from the cluster transmission queue.

workloadPriority

Integer.

Specifies the priority of the queue in cluster workload management.

A value of 0 specifies the lowest priority and 9 specifies the highest priority.

workloadQueueUse

String.

Specifies whether remote and local instances of the clustered queues are used in cluster workload distribution.

The value is one of the following values:

asQmgr

Use the value that is defined on the queue manager.

any

Use remote and local instances of the queues.

local

Use only local instances of the queues.

workloadRank

Integer.

Specifies the rank of the queue in cluster workload management.

A value of 0 specifies the lowest priority and 9 specifies the highest priority.

trigger

enabled

Boolean.

Specifies whether trigger messages are written to the initiation queue.

data

String.

Specifies the user data that is included in the trigger message.

depth

Integer.

Specifies the number of messages that initiates a trigger message to the initiation queue.

initiationQueueName

String.

Specifies the local queue for trigger messages that relate to the queue.

messagePriority

Integer.

Specifies the minimum priority that a message must have before it can cause, or be counted for, a trigger event.

processName

String.

Specifies the local name of the IBM MQ process that identifies the application to be started when a trigger event occurs.

If the queue is a transmission queue, the process definition contains the name of the channel to be started.

type

String.

Specifies the condition that initiates a trigger event. When the condition is true, a trigger message is sent to the initiation queue.

The value is one of the following values:

none

Send no trigger messages.

every

Send a trigger message for every message that arrives on the queue.

first

Send a trigger message when the queue depth goes from 0 to 1.

depth

Send a trigger message when the queue depth exceeds the value of the depthattribute.

events

depth

JSON object.

A JSON object that can contain the following attributes that related to queue depth events:

highEnabled

Boolean.

Specifies whether queue depth high events are generated.

A queue depth high event indicates that the number of messages on the queue is greater than or equal to the queue depth high limit, highPercentage.

highPercentage

Integer.

Specifies the threshold against which the queue depth is compared to generate a queue depth high event.

This value is expressed as a percentage of the maximum queue depth.

lowEnabled

Boolean.

Specifies whether queue depth low events are generated.

A queue depth low event indicates that the number of messages on the queue is less than or equal to the queue depth low limit, lowPercentage.

lowPercentage

Integer.

Specifies the threshold against which the queue depth is compared to generate a queue depth low event.

This value is expressed as a percentage of the maximum queue depth.

fullEnabled

Boolean.

Specifies whether queue full events are generated.

A queue full event indicates that no more messages can be put on a queue because the queue is full. That is, the queue depth reached the maximum queue depth.

serviceInterval

JSON object.

A JSON object that can contain the following attributes that are related to queue service interval events:

highEnabled

Boolean.

Specifies whether queue service interval high events are generated.

A queue service interval high event is generated when no messages were put to, or retrieved from, the queue for at least the amount of time specified by the duration attribute.

okEnabled

Boolean.

Specifies whether queue service interval OK events are generated.

A queue service interval OK event is generated when a message was retrieved from the queue within the amount of time that is specified by the duration attribute.

duration

Integer.

Specifies the service interval duration, in milliseconds, that is used to generate queue service interval high and queue service interval OK events.

applicationDefaults

clusterBind

String.

Specifies the binding to be used when MQOO_BIND_AS_Q_DEF is specified on the MQOPEN call.

The value is one of the following values:

onOpen

Specifies that the binding is fixed by the MQOPEN call.

notFixed

Specifies that the binding is not fixed.

onGroup

Specifies that the application can request that a group of messages is allocated to the same destination instance.

messagePropertyControl

String.

Specifies how message properties are handled when messages are retrieved from queues when MQGMO_PROPERTIES_AS_Q_DEF is specified on the MQGET call.

This attribute is applicable to local, alias, and model queues.

The value is one of the following values:

all

Specifies that all properties of the message are included when the message is sent to the remote queue manager. The properties, except those properties in the message descriptor or extension, are place in one of more MQRFH2 headers in the message data.

compatible

Specifies that if the message contains a property with the prefix mcd., jms., usr., or mqext., all message properties are delivered to the application in an MQRFH2 header. Otherwise, all properties, except those properties in the message descriptor or extension, are discarded and are no longer accessible.

force

Specifies that properties are always returned in the message data in an MQRFH2 header regardless of whether the application specifies a message handle. A valid message handle that is included in the MsgHandle field of the MQGMO structure on the MQGET call is ignored. Properties of the message are not accessible by using the message handle.

none

Specifies that all properties of the message are removed from the message before the message is sent to the remote queue manager. Properties in the message descriptor, or extension, are not removed.

version6Compatible

Any application MQRFH2 header is received as it was sent. Any properties set by using MQSETMP must be retrieved by using MQINQMP. They are not added to the MQRFH2 created by the application. Properties that were set in the MQRFH2 header by the sending application cannot be retrieved by using MQINQMP.

messagePersistence

String.

Specifies the default for message persistence on the queue. Message persistence determines whether messages are preserved across restarts of the queue manager.

The value is one of the following values:

persistent

Specifies that the messages on the queue are persistent, and are preserved when the queue manager restarts.

nonPersistent

Specifies that the messages on the queue are not persistent, and are lost when the queue manager restarts.

messagePriority

Integer.

Specifies the default priority of messages that are put on the queue.

putResponse

String.

Specifies the type of response that is used for put operations to the queue when an application specifies MQPMO_RESPONSE_AS_Q_DEF.

The value is one of the following values:

synchronous

The put operation is run synchronously, returning a response.

asynchronous

The put operation is run asynchronously, returning a subset of MQMD fields.

readAhead

String.

Specifies the default read-ahead behavior for non-persistent messages that are delivered to the client.

The value is one of the following values:

no

Specifies that non-persistent messages are not read ahead unless the client application is configured to request read ahead.

yes

Specifies that non-persistent messages are sent ahead to the client before an application requests them. Non-persistent messages can be lost if the client ends abnormally or if the client does not consume all the messages that it is sent.

disabled

Specifies that non-persistent messages are not read ahead, regardless of whether read ahead is requested by the client application.

sharedInput

Boolean.

Specifies the default share option for applications that open this queue for input.

If the value is set to true, queues are enabled to get messages with shared access.

queueSharingGroup

disposition

String.

This attribute is only available on z/OS.

Specifies where the queue is defined and how it behaves. That is, it specifies the disposition of the queue.

This value is always returned if the queue manager is a member of the queue sharing group.

The value is one of the following values:

copy

Specifies that the queue definition exists on the page set of the queue manager that runs the command. For local queues, messages are stored on the page sets of each queue manager and are available only through that queue manager.

group

Specifies that the queue definition exists in the shared repository.

qmgr

Specifies that the queue definition exists on the page set of the queue manager that runs the command. For local queues, messages are stored on the page sets of each queue manager and are available only through that queue manager.

shared

This value is only valid for local queues.

Specifies that the queue exists in the shared repository. Messages are stored in the coupling facility and are available to any queue manager in the queue sharing group.

qmgrName

String.

This attribute is only available on z/OS.

Specifies the name of the queue manager that generates the response to the REST request.

This attribute is only returned if the queue manager to which the REST request is made is part of a queue sharing group, and the commandScope optional query parameter is specified.

structureName

String.

This attribute is only available on z/OS.

Specifies the name of the coupling facility structure where messages are stored when we used shared queues.

dataCollection

accounting

String.

Specifies whether accounting data is collected for the queue.

The value is one of the following values:

asQmgr

Specifies that the queue inherits the value from the queue manager MQSC parameter ACCTQ.

off

Specifies that accounting data is not collected for the queue.

on

Specifies that accounting data is collected for the queue if the ACCTQ MQSC parameter on the queue manager is not set to none.

monitoring

String.

Specifies whether online monitoring data is collected, and if so, the rate at which the data is collected.

The value is one of the following values:

off

Specifies that online monitoring data is not collected for the queue.

asQmgr

Specifies that the queue inherits the value from the queue manager MONQ MQSC parameter.

low

Specifies that online monitoring data is collected for the queue if the MONQ MQSC parameter on the queue manager is not set to none. The rate of data collection is low.

medium

Specifies that online monitoring data is collected for the queue if the MONQ MQSC parameter on the queue manager is not set to none. The rate of data collection is moderate.

high

Specifies that online monitoring data is collected for the queue if the MONQ MQSC parameter on the queue manager is not set to none. The rate of data collection is high.

statistics

This attribute is only available on the IBM MQ Appliance, UNIX, Linux, and Windows.

String.

Specifies whether statistics data is collected for the queue.

The value is one of the following values:

asQmgr

Specifies that the queue inherits the value from the queue manager STATQ MQSC parameter.

off

Specifies that statistics data is not collected for the queue.

on

Specifies that statistics data is collected for the queue if the STATQ MQSC parameter on the queue manager is not set to none.

storage

indexType

This attribute is only available on z/OS.

String.

Specifies the type of index that is maintained by the queue manager to expedite MQGET operations on the queue. For shared queues, the type of index determines what type of MQGET calls can be used.

The value is one of the following values:

none

Specifies that there is no index. Messages are retrieved sequentially.

correlationId

Specifies that the queue is indexed by using correlation identifiers.

groupId

Specifies that the queue is indexed by using group identifiers.

messageId

Specifies that the queue is indexed by using message identifiers.

messageToken

Specifies that the queue is indexed by using message tokens.

maximumMessageLength

Integer.

Specifies the maximum message length that is allowed, in bytes, for messages on the queue.

maximumDepth

Integer.

Specifies the maximum number of messages that are allowed on the queue.

messageDeliverySequence

String.

Specifies whether messages are delivered in priority order or by sequence.

The value is one of the following values:

priority

Specifies that messages are returned in priority order.

fifo

Specifies that messages are returned in first in, first out order.

nonPersistentMessageClass

This attribute is only available on the IBM MQ Appliance, UNIX, Linux, and Windows.

String.

This attribute is valid only on local and model queues.

Specifies the level of reliability that is assigned to non-persistent messages that are put to the queue.

The value is one of the following values:

normal

Specifies that non-persistent messages persist for the lifetime of the queue manager session. They are discarded if the queue manager restarts.

high

Specifies that the queue manager attempts to retain non-persistent messages for the lifetime of the queue. Non-persistent messages might still be lost if a failure occurs.

pageSet

This attribute is only available on z/OS.

Integer.

Specifies the ID of the page set.

storageClass

This attribute is only available on z/OS.

String.

Specifies the name of the storage class.

general

description

String.

Specifies the description of the queue.

inhibitGet

Boolean.

Specifies whether get operations are allowed on the queue.

If the value is set to true, get operations are not allowed on the queue.

inhibitPut

Boolean.

Specifies whether put operations are allowed on the queue.

If the value is set to true, put operations are not allowed on the queue.

isTransmissionQueue

String.

Specifies whether the queue is for normal usage or for transmitting messages to a remote queue manager.

If the value is set to true, the queue is a transmission queue for transmitting messages to a remote queue manager.

extended

allowSharedInput

Boolean.

Specifies whether multiple instances of applications can open the queue for input.

If the value is set to true, multiple instances of applications can open the queue for input.

backoutRequeueQueueName

String.

Specifies the name of the queue to which a message is transferred if it is backed out more times than the value of backoutThreshold.

backoutThreshold

Integer.

Specifies the number of times that a message can be backed out before it is transferred to the backout queue that is specified by the backoutRequeueQueueName attribute.

custom

String.

Specifies custom attributes for new features.

enableMediaImageOperations

This attribute is available only on the IBM MQ Appliance, UNIX, Linux, and Windows.

Specifies whether a local or permanent dynamic queue object is recoverable from a media image, if linear logging is being used.

String.

The value is one of the following values:

yes

Specifies that this queue object is recoverable.

no

The rcdmqimg and rcrmqobj commands are not permitted for these objects. If automatic media images are enabled, the media images are not written for these objects.

asQmgr

Specifies that the queue inherits the value from the queue manager ImageRecoverQueue attribute.

This is the default value for this attribute.

hardenGetBackout

This attribute is only available on z/OS.

Boolean.

Specifies whether the count of the number of times that a message was backed out is saved, to ensure that it is accurate across restarts of the queue manager.

If the value is set to true, the backout count is always accurate across restarts of the queue manager.

supportDistributionLists

This attribute is only available on the IBM MQ Appliance, UNIX, Linux, and Windows.

Boolean.

Specifies whether distribution-list messages can be placed on the queue.

If the value is set to true, distribution lists can be placed on the queue.

timestamps

The timestamps object contains attributes that are related to date and time information.

altered

String.

Specifies the date and time at which the queue was last altered.

For more information about the time stamp format that is used to return the date and time, see REST API time stamps.

clustered

String.

Specifies the date and time at which the information became available to the local queue manager.

For more information about the time stamp format that is used to return the date and time, see REST API time stamps.

created

String.

Specifies the date and time at which the queue was created.

For more information about the time stamp format that is used to return the date and time, see REST API time stamps.

status

currentDepth

Integer.

Specifies the current queue depth.

lastGet

String.

Specifies the date and time at which the last message was destructively read from the queue.

For more information about the time stamp format that is used to return the date and time, see REST API time stamps.

lastPut

String.

Specifies the date and time at which the last message was successfully put to the queue.

For more information about the time stamp format that is used to return the date and time, see REST API time stamps.

mediaRecoveryLogExtent

This attribute is only available on the IBM MQ Appliance, UNIX, Linux, and Windows.

String.

Specifies the name of the oldest log extent that is required to perform media recovery of the queue.

The name that is returned is of the form Snnnnnnn.LOG and is not a fully qualified path name.

oldestMessageAge

Integer.

Specifies the age, in seconds, of the oldest message on the queue.

If the queue is empty, 0 is returned. If the value is greater than 999 999 999, it is returned as 999 999 999. If no data is available, -1 is returned.

onQueueTime

JSON object.

A JSON object that can contain the following attributes that related to the amount of time that a message remains on the queue:

longSamplePeriod

Integer.

Specifies an indication of the time, in microseconds, that a message remains on the queue based on activity over a long period.

shortSamplePeriod

Integer.

Specifies an indication of the time, in microseconds, that a message remains on the queue based on activity over a short period.

This attribute cannot be used to filter results.

openInputCount

Integer.

Specifies the number of handles that are currently valid for removing messages from the queue by using the MQGET call.

openOutputCount

Integer.

Specifies the number of handles that are currently valid for putting messages to the queue by using the MQPUT call.

monitoringRate

String.

Specifies the rate at which monitoring data is collected for the queue.

The value is one of the following values:

off

Specifies that no data is collected.

low

Specifies a low rate of data collection.

medium

Specifies a medium rate of data collection.

high

Specifies a high rate of data collection.

tpipeName

This attribute is only available on z/OS.

Array.

Specifies the TPIPE names that are used for communication with OTMA by using the IBM MQ IMS bridge, if the bridge is active.

This attribute cannot be used to filter results.

uncommittedMessages

Integer.

Specifies the number of uncommitted changes that are pending for the queue.

On z/OS, the value can be only either 0 or 1. A value of 1 indicates that there is at least one uncommitted message on the queue.

applicationHandle

description

String.

Specifies a description for the application.

tag

This attribute is only available on z/OS.

String.

Specifies the tag of the open application.

type

String.

Specifies the type of application.

This value is one of the following values:

queueManagerProcess

Specifies that the open application is a queue manager process.

channelInitiator

Specifies that the open application is a channel initiator.

userApplication

Specifies that the open application is a user application.

batchConnection

This attribute is only available on z/OS.

Specifies that the open application is using a batch connection.

rrsBatchConnection

This attribute is only available on z/OS.

Specifies that the open application is an RRS-coordinated application that uses a batch connection.

cicsTransaction

This attribute is only available on z/OS.

Specifies that the open application is a CICS transaction.

imsTransaction

This attribute is only available on z/OS.

Specifies that the open application is an IMS transaction.

systemExtension

Specifies that the open application is an application that performs an extension of function that is provided by the queue manager.

asynchronousConsumerState

String.

Specifies the state of the asynchronous consumer on the queue.

The value is one of the following values:

active

Specifies that an MQCB call set up a function to call back to process messages asynchronously, and the connection handle has started so that asynchronous message consumption can proceed.

inactive

Specifies that an MQCB call set up a function to call back to process messages asynchronously, but the connection handle is not started, or is stopped or suspended.

suspended

Specifies that the asynchronous consumption callback is suspended so that asynchronous message consumption cannot proceed on the handle.

This situation can be either because an MQCB or MQCTL call with Operation MQOP_SUSPEND was issued against this object handle by the application, or because it was suspended by the system. If it was suspended by the system, as part of the process of suspending asynchronous message consumption the callback function is called with the reason code that describes the problem that resulted in suspension. This situation is reported in the reason field in the MQCBC structure passed to the callback. In order for asynchronous message consumption to proceed, the application must issue an MQCB or MQCTL call with Operation MQOP_RESUME.

suspendedTemporarily

Specifies that the asynchronous consumption callback is temporarily suspended by the system so that asynchronous message consumption cannot proceed on this handle.

As part of the process of suspending asynchronous message consumption the callback function is called with the reason code that describes the problem that resulted in suspension. This situation is reported in the reason field in the MQCBC structure passed to the callback. The callback function is called again when asynchronous message consumption is resumed by the system after the temporary condition is resolved.

none

Specifies that an MQCB call was not issued against this handle, so asynchronous message consumption is not configured on the handle.

addressSpaceId

This attribute is only available on z/OS.

String.

Specifies a four character address space identifier for the application.

channelName

String.

Specifies the channel name.

connectionName

String.

Specifies the connection name.

state

String.

Specifies the state of the handle.

This value is one of the following values:

active

Specifies that an API call from a connection is in progress for the queue. This state can occur when an MQGET WAIT call is in progress.

inactive

Specifies that no API call from a connection is in progress for the queue. This state can occur when no MQGET WAIT call is in progress.

openOptions

JSON array.

Specifies the open options that are in force for the queue.

Any of the valid MQOO options can be present in the array. For more information about the MQOO_* options, see MQOO_* (Open Options).

processId

This attribute is only available on the IBM MQ Appliance, UNIX, Linux, and Windows.

Integer.

Specifies the process ID of the open application.

processSpecificationBlockName

This attribute is only available on z/OS.

String.

Specifies the eight character name of the program specification block that is associated with the running IMS transaction.

processSpecificationTableId

This attribute is only available on z/OS.

String.

Specifies the four character identifier of the program specification table region identifier for the connected IMS region.

qmgrTransactionId

String.

Specifies the unit of recovery that is assigned by the queue manager.

This identifier is represented as 2 hexadecimal digits for each byte of the recovery identifier.

This attribute cannot be used to filter results.

cicsTaskNumber

This attribute is only available on z/OS.

Integer.

Specifies a seven digit CICS task number.

threadId

This attribute is only available on the IBM MQ Appliance, UNIX, Linux, and Windows.

Integer.

Specifies the thread ID of the open application.

A value of 0 indicates that the handle was opened by a shared connection. A handle that is created by a shared connection is logically open to all threads.

cicsTransactionId

This attribute is only available on z/OS.

String.

Specifies a four character CICS transaction ID.

unitOfWorkId

String.

Specifies the recovery identifier for the unit of recovery. The format of this value is determined by the value of unitOfWorkType.

This identifier is represented as 2 hexadecimal digits for each byte of the recovery identifier.

This attribute cannot be used to filter results.

unitOfWorkType

String.

Specifies the type of external unit of recovery identifier as perceived by the queue manager.

The value is one of the following values:

qmgr

cics

This value is only available on z/OS.

ims

This value is only available on z/OS.

rrs

This value is only available on z/OS.

xa

userId

String.

Specifies the user identifier of the open application.

Parent topic: GET