PATCH

Use the HTTP PATCH method with the queue resource to modify a queue on a specified queue manager.

This REST API command is similar to the Change Queue PCF command, and the ALTER queues MQSC commands.


Resource URL

Version 9.0.4 and later:
https://host:port/ibmmq/rest/v1/admin/qmgr/{qmgrName}/queue/{queueName}

Version 9.0.3 and earlier:
https://host:port/ibmmq/rest/v1/qmgr/{qmgrName}/queue/{queueName}

    qmgrName
    Specifies the name of the queue manager on which the queue to modify exists.
    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 period (.) must be encoded as %2E.
    • A percent sign (%) must be encoded as %25.
    queueName
    Specifies the name of the queue to modify.
    We 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.

We can use HTTP instead of HTTPS if you enable HTTP connections. For more information about enabling HTTP, see Configure HTTP and HTTPS ports.


Optional query parameters

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

    force
    Specifies that the command is forced to complete, regardless of whether completing affects an open queue.
    This parameter is not valid for model queues.
    An open queue is affected in the following cases:

    • The queue is an alias queue. The targetName is modified, and an application has the alias queue open.
    • The queue is a local queue. The allowedSharedInput attribute is modified, and more than one application has the queue open for input.
    • The queue is a local queue. The isTransmissionQueue attribute is modified, and messages are on the queue, or applications have the queue open.
    • The queue is a remote queue. The transmissionQueueName attribute is modified, and an application has a remote queue open that would be affected by this change.
    • The queue is remote queue. The queueName, qmgrName, or transmissionQueueName attributes are modified, and one or more applications has a queue open that resolved through this definition as a queue manager alias.


Request headers

The following headers must be sent with the request:

    Content-Type
    This header must be sent with a value of application/json;charset=utf-8.
    ibm-mq-rest-csrf-token
    This header must be sent with a value that is the content of the csrfToken cookie. The content of the csrfToken cookie is used to confirm that the credentials that are being used to authenticate the request are being used by the owner of the credentials. That is, the token is used to prevent cross-site request forgery attacks.
    The csrfToken cookie is returned after a request is made with an HTTP GET method. We cannot use a cached version of the content of the cookie because the content of the cookie can change. You must use the latest value of the cookie for each request.
    The preceding information applies to releases up to and including IBM MQ Version 9.0.4. From IBM MQ Version 9.0.5, this header must be set, but the value can be anything, including being blank.

    The csrfToken cookie is no longer sent in responses from the REST API in Version 9.0.5 and later.

    Authorization
    This header must be sent if you are using basic authentication. For more information, see Use HTTP basic authentication with the REST API.

The following headers can optionally be sent with the request:

    ibm-mq-rest-gateway-qmgr
    This header specifies the queue manager that is to be used as the gateway queue manager. The gateway queue manager is used to connect to a remote queue manager. For more information, see Remote administration using the REST API.


Request body format

The request body must be in JSON format in UTF-8 encoding. Within the request body attributes are specified, and named JSON objects are created to specify extra attributes to modify. Any attributes that are not specified are not changed.

For example, the following JSON contains the attribute type, and then the named JSON objects, events and storage. The named JSON objects define the additional attributes to modify the queue to disable queue depth high events, and change the maximum queue depth to 2000: 
{
   "type": "local",
   "events" : {
      "serviceInterval" : {
          "highEnabled" : false,
          "okEnabled" : false
    },
   "storage" : {
      "maximumDepth" : 2000
   }
}

For more examples, see examples.

The following attributes can be included in the request body:

    type
    String.
    Specifies the type of queue.
    The value can be one of the following values:

    • local
    • alias
    • model
    • remote
    The default value is local.

The following objects can be included in the request body to specify extra attributes:

    remote
    Contains attributes that are related to remote queues. The attributes in this object are supported only for remote queues.
    alias
    Contains attributes that are related to alias queues. The attributes in this object are supported only for alias queues.
    model
    Contains attributes that are related to model queues. The attributes in this object are supported only for 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.

For more information, see Request body attributes for queues.


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.

The security principal of the caller must be granted the ability to issue the following PCF commands for the specified queue manager:

  • For the queue that is specified by the {queueName} portion of the resource URL, authority to issue the MQCMD_CHANGE_Q PCF command must be granted.

On UNIX, Linux , and Windows, we can grant authority to security principals to use IBM MQ resources by using the mqsetaut command. For more information, see mqsetaut.

On z/OS, see Set up security on z/OS.


Response status codes

    204
    Queue modified successfully.

    400
    Invalid data provided.
    For example, invalid queue data is 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. The ibm-mq-rest-csrf-token header must also be specified.. 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:

    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 body is empty if the queue is modified successfully. If an error occurs, the response body contains an error message. For more information, see REST API error handling.


Examples

  • The following example modifies an alias queue called aliasQueue. The following URL is used with the HTTP PATCH method: Version 9.0.4 and later: 
    https://localhost:9443/ibmmq/rest/v1/admin/qmgr/QM1/queue/aliasQueue
    Version 9.0.3 and earlier: 
    https://localhost:9443/ibmmq/rest/v1/qmgr/QM1/queue/aliasQueue
    The following JSON payload is sent:
    {
   "type": "alias",
   "alias": {
      "targetName": "aDifferentLocalQueue"
  }
}