When you create the request body for creating or modifying a queue with
the administrative REST API, you can specify attributes for the queue within named JSON objects. A
number of objects and attributes are available.
remote
Note: The remote object and the qmgrName attribute are required
when you create a remote queue by using the HTTP POST method. You cannot use the
remote object unless you are creating a remote queue, or updating a remote
queue.
The remote object can contain the following attributes that relate to remote
queues:
- queueName
- String.
- Specifies the name of the queue as it is known on the remote queue manager.
- If this attribute is omitted, a queue manager alias or reply-to queue alias is created.
- qmgrName
- String.
- Specifies the name of the remote queue manager.
- Required when you create a queue by using the HTTP POST method, unless you use the
like optional query parameter.
- If this remote queue is used as a queue manager alias, this attribute is the name of the queue
manager. The value can be the name of the queue manager in the resource URL.
- 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.
- transmissionQueueName
- String.
- Specifies the name of the transmission queue that is to be used for messages that are destined
for either a remote queue or for a queue manager alias definition.
- This attribute is ignored in the following cases:
- The remote queue is used as a queue manager alias and qmgrName attribute is
the name of the queue manager in the resource URL.
- The remote queue is used as a reply-to queue alias.
- If this attribute is omitted, a local queue with the name that is specified by the
qmgrName attribute must exist. This queue is used as the transmission
queue.
alias
Note: The alias object and the targetName attribute are required
when you create an alias queue by using the HTTP POST method. You cannot use the
alias object unless you are creating an alias queue, or updating an alias
queue.
The alias object can contain the following attributes that relate to alias
queues:
- targetName
- String.
- Specifies the name of the queue or topic that the alias resolves to.
- Required when you create a queue by using the HTTP POST method, unless you use the
like optional query parameter.
- targetType
- String.
- Specifies the type of object that the alias resolves to.
- The value must be one of the following values:
- queue
- Specifies that the object is a queue.
- topic
- Specifies that the object is a topic.
- The default value is
queue.
model
Note: The model object and the type attribute are required when
you create a model queue by using the HTTP POST method. You cannot use the model
object unless you are creating a model queue, or updating a model queue.
The model object can contain the following attributes that relate to model
queues:
- type
- String.
- Specifies the model queue definition type.
- The value must be one of the following values:
- permanentDynamic
- Specifies that the queue is a dynamically defined permanent queue.
- sharedDynamic
![[z/OS]](ngzos.gif)
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.
- The default value is
temporaryDynamic.
cluster
The cluster object can contain the following attributes that relate to
clusters:
- name
- String.
- Specifies the name of the cluster that the queue belongs to.
- Specify either the name or namelist cluster
attributes. You cannot specify both attributes.
- namelist
- String.
- Specifies the namelist that lists the clusters that the queue belongs to.
- Specify either the name or namelist cluster
attributes. You cannot specify both attributes.
- 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.
- You can also set this attribute to a cluster-sender channel manually. Messages that are destined
for the queue manager that is connected by the cluster-sender channel are stored in the transmission
queue that identifies the cluster-sender channel. The messages are not stored in the default cluster
transmission queue.
- If you set the transmissionQueueForChannelName attribute to blanks, the
channel switches to the default cluster transmission queue when the channel restarts. The default
cluster transmission queue is
SYSTEM.CLUSTER.TRANSMIT.QUEUE if the queue manager
DefClusterXmitQueueType attribute is set to SCTQ. A specific
cluster transmission queue, SYSTEM.CLUSTER.TRANSMIT.ChannelName,
is used for each cluster-sender channel if the queue manager
DefClusterXmitQueueType attribute is set to CHANNEL.
- By specifying asterisks, *, in transmissionQueueForChannelName, you can
associate a transmission queue with a set of cluster-send channels. The asterisks can be at the
beginning, end, or any number of places in the middle of the channel name string.
- workloadPriority
- Integer.
- Specifies the priority of the queue in cluster workload management.
- The value must be in the range 0 - 9, where 0 is the lowest priority and 9 is the highest.
- workloadRank
- Integer.
- Specifies the rank of the queue in cluster workload management.
- The value must be in the range 0 - 9, where 0 is the lowest priority and 9 is the highest.
- workloadQueueUse
- String.
- Specifies whether remote and local instances of the clustered queues are to be used in cluster
workload distribution.
- The value must be 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.
trigger
The trigger object can contain the following attributes that relate to
triggering:
- data
- String.
- Specifies the user data that is included in the trigger message. This data is made available to
the monitoring application that processes the initiation queue and to the application that is
started by the monitor.
- depth
- Integer.
- Specifies the number of messages that initiates a trigger message to the initiation queue.
- The value must be in the range 1 - 999,999,999.
- This attribute is required when type is set to
depth.
- enabled
- Boolean.
- Specifies whether trigger messages are written to the initiation queue.
- If the value is set to
true, trigger messages are written to the initiation
queue.
- initiationQueueName
- String.
- Specifies the local queue for trigger messages that relate to the queue. The queues must be on
the same queue manager.
- messagePriority
- Integer.
- Specifies the minimum priority that a message must have before it can cause, or be counted for,
a trigger event.
- The value must be in the range 0 - 9.
- 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 must be 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
The events object can contain the following objects and attributes that relate
to queue depth and queue service interval events:
- depth
- JSON object.
- A JSON object that can contain the following attributes that related to queue depth events:
- 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, as specified by the
maximumDepth attribute in the
storage object.
- If the value is set to
true, queue full events are enabled.
- 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.
- If the value is set to
true, queue depth high events are enabled.
- 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, as specified by the
maximumDepth attribute in the
storage object. The value must
be a value in the range 0 - 100.
- 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.
- If the value is set to
true, queue depth low events are enabled.
- 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, as specified by the
maximumDepth attribute in the
storage object. The value must
be a value in the range 0 - 100.
- serviceInterval
- JSON object.
- A JSON object that can contain the following attributes that are related to queue service
interval events:
- duration
- Integer.
- Specifies the service interval duration that is used for comparison to generate queue service
interval high and queue service interval OK events.
- The value must be a value in the range 0 - 999,999,999 milliseconds.
- highEnabled
- Boolean.
- Specifies whether queue service interval high events are generated.
- A queue service interval high event is generated when a check indicates that no messages were
put to, or retrieved from, the queue for at least the amount of time specified by the
duration attribute.
- If the value is set to
true, queue service interval high events are
enabled.
- If you set the highEnabled attribute to
false, you must
also specify a value for the okEnabled attribute. You cannot set both the
highEnabled attribute and the okEnabled attribute to true
at the same time.
- okEnabled
- Boolean.
- Specifies whether queue service interval OK events are generated.
- A queue service interval OK event is generated when a check indicates that a message was
retrieved from the queue within the amount of time that is specified by the
duration attribute.
- If the value is set to
true, queue service interval OK events are enabled.
- If you set the okEnabled attribute to
false, you must also
specify a value for highEnabled. You cannot set both the
highEnabled attribute and the okEnabled attribute to
true at the same time.
applicationDefaults
The applicationDefaults object can contain the following attributes that relate
to default behavior such as message persistence:
- clusterBind
- String.
- Specifies the binding to be used when
MQOO_BIND_AS_Q_DEF is specified on the
MQOPEN call.
- The value must be 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.
- 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 must be 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.
- The value must be in the range 0 - 9, where 0 represents the lowest priority, and 9 represents
the highest priority.
- 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 must be 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.
- putResponse
- String.
- Specifies the type of response that is to be used for put operations to the queue when an
application specifies
MQPMO_RESPONSE_AS_Q_DEF.
- The value must be 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 must be 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
The queueSharingGroup object can contain the following attributes
that relate to queue sharing groups:
- 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.
- The value must be one of the following values:
- copy
- Specifies that the queue definition exists on the page set of the queue manager that runs the
command. The group object of the same name as the name attribute is used to
create the queue.
- 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.
- This value is allowed only in a shared queue manager environment.
- If the creation is successful, the following MQSC command is generated and sent to all active
queue managers in the queue sharing group. The command attempts to make or refresh local copies on
page set zero:
DEFINE queue(q-name) REPLACE QSGDISP(COPY)
The creation of the
group object takes effect even if the generated command with QSGDISP(COPY) fails.
- 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. You can specify
shared only if the following things are true:
- The value of structureName is not blank.
- The value of indexType is not
messageToken.
- The queue is not
SYSTEM.CHANNEL.INITQ or
SYSTEM.COMMAND.INPUT.
- The default value is
qmgr.
- structureName
- String.
- This attribute is only available on z/OS.
- Specifies the name of the coupling facility structure where you want to store messages when you
used shared queues.
- The value cannot have more than 12 characters, it must start with an uppercase letter (A - Z),
and can include only the characters A - Z and 0 - 9.
- The name of the queue sharing group to which the queue manager is connected is prefixed to the
name you supply. The name of the queue sharing group is always 4 characters, padded with the at
sign, @, if necessary. For example, if you use a queue sharing group that is named
NY03 and you supply the name PRODUCT7, the
resultant coupling facility structure name is NY03PRODUCT7. Note the
administrative structure for the queue sharing group (in this case
NY03CSQ_ADMIN) cannot be used for storing messages.
- For local and model queues, the following rules apply. The rules apply if you create a queue
without specifying the noReplace optional query parameter, or if you change the queue:
- On a local queue with a disposition value of
shared,
structureName cannot change. If you need to change the
structureName or the disposition, you must delete and
redefine the queue. To preserve any of the messages on the queue, you must offload the messages
before you delete the queue. Reload the messages after you redefine the queue, or move the messages
to another queue.
- On a model queue with a definitionType value of
sharedDynamic, the structureName cannot be blank.
- For local and model queues, when you create a queue with the noReplace
optional query parameter, the following rules apply:
- On a local queue with a disposition value of
shared, or a
model queue with a definitionType value of sharedDynamic, the
structureName cannot be blank.
dataCollection
The dataCollection object can contain the following attributes that relate to
the collection of data, monitoring, and statistics:
- accounting
- String.
- Specifies whether accounting data is collected for the queue.
- The value must be 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 to be collected, and if so, the rate at which the
data is collected.
- The value must be 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 MQSC parameter
MONQ.
- 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
![[UNIX, Linux, Windows]](ngulw.gif)
![[MQ Appliance]](ngappliance.gif)
This attribute is only available on the IBM MQ Appliance, UNIX, Linux®, and Windows.- String.
- Specifies whether statistics data is to be collected for the queue.
- The value must be 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.
general
The general object can contain the following attributes that relate to general
queue properties:
- description
- String.
- Specifies a description for the queue.
- The characters in the description field are converted from UTF-8 into the CCSID of the queue
manager. Ensure that you use only the characters that can be converted. Certain characters must be escaped:
- Double quotation marks, ", must be escaped as
\"
- A backslash, \, must be escaped as
\\
- A forward slash, /, must be escaped as
\/
- 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.
- The isTransmissionQueue attribute must not normally be changed
while messages are on the queue. The format of messages changes when they are put on a transmission
queue.
extended
The extended object can contain the following attributes that relate to extended
queue properties:
- 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.
- The backout queue does not need to exist when the queue is created, but it must exist when the
backoutThreshold value is exceeded.
- 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.
- If the backoutThreshold value is later reduced, messages that are already
on the queue that were backed out at least as many times as the new value remain on the queue. Those
messages are transferred if they are backed out again.
- The value must be a value in the range 0 - 999,999,999.
- custom
- String.
- Specifies custom attributes for new features.
- This attribute contains the values of attributes, as pairs of attribute name and value, which
are separated by at least one space. The attribute name-value pairs have the form
NAME(VALUE). Single quotation marks, ', must be escaped with another single
quotation mark.
![[V9.0.4 Oct 2017]](ng904.gif)
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 must be 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.
![[V9.0.2 Mar 2017]](ng902.gif)