Request body attributes for queues

When you create the request body for creating or modifying a queue with the administrative REST API, we can specify attributes for the queue within named JSON objects. A number of objects and attributes are available.

The following objects are available:

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


remote

Note: The remote object and the qmgrName attribute are required when you create a remote queue by using the HTTP POST method. We cannot use the remote object unless we 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 we 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. We cannot use the alias object unless we 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 we 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. We cannot use the model object unless we 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
      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. We 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. We 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.
    We 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, we 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, we must also specify a value for the okEnabled attribute. We 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, we must also specify a value for highEnabled. We 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. We 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 we 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 we 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 we change the queue:

    • On a local queue with a disposition value of shared, structureName cannot change. For to change the structureName or the disposition, we must delete and redefine the queue. To preserve any of the messages on the queue, we 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
    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.


storage

The storage object can contain the following attributes that relate to message 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 must be 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.

    The default value is none.

    maximumDepth
    Integer.
    Specifies the maximum number of messages that are allowed on the queue.
    The value must be in the range 0 - 999,999,999.

    maximumMessageLength
    Integer.
    Specifies the maximum message length that is allowed for messages on the queue.
    Do not set a value that is greater than the maximumMessageLength attribute for the queue manager.
    The value must be in the range 0 - 104,857,600 bytes.

    messageDeliverySequence
    String.
    Specifies whether messages are delivered in priority order or by sequence.
    The value must be 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 to be assigned to non-persistent messages that are put to the queue.
    The value must be 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.

    storageClass
    This attribute is only available on z/OS.
    String.
    Specifies the name of the storage class.


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

    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.

Parent topic: POST