POST - JSON formatted command

Use the HTTP POST method with this resource to submit administrative commands directly to a queue manager. These administrative commands are submitted in the body of the request, either as a plain text MQSC command, or as a JSON formatted command.

[MQ 9.3.5 Feb 2024]Note: This resource is not available in a stand-alone IBM® MQ Web Server installation. For more information about the installation options for the IBM MQ component that runs the administrative REST API, see The IBM MQ Console and REST API.
You can use the administrative REST API to submit an MQSC command by using the either a plain text MQSC command or with a JSON formatted command:
  • With a plain text MQSC command, the body of the request contains an MQSC command specified as you would type it on a command line. For example:
    
{
  "type": "runCommand",
  "parameters": {
    "command": "DEFINE CHANNEL(NEWSVRCONN) CHLTYPE(SVRCONN)"
  }
}
    The response is returned in a plain text format.
  • With a JSON formatted command, the body of the request contains an MQSC command in a JSON format. For example:
    {
   "type": "runCommandJSON",
   "command": "define",
   "qualifier": "channel",
   "name": "NEWSVRCONN",
   "parameters": {
      "chltype": "svrconn"
   }
}
    The response is returned in JSON format.

For more information about using the plain text MQSC command, see POST - plain text MQSC command.

You can use this REST API command with HTTP to run any MQSC command. However, the following MQSC commands are not supported when you use a JSON formatted command in the request body:
  • DISPLAY ARCHIVE
  • DISPLAY CHINIT
  • DISPLAY GROUP
  • DISPLAY LOG
  • DISPLAY SECURITY
  • DISPLAY SYSTEM
  • DISPLAY THREAD
  • DISPLAY TRACE
  • DISPLAY USAGE

On AIX®, Linux®, and Windows, this REST API command is similar to the MQCMD_ESCAPE (Escape) on Multiplatforms PCF command.

On z/OS®, this REST API command is similar to submitting commands directly to the command server:
  • Messages are put to a request queue. These messages have MsgType set to MQMT_REQUEST, Format set to MQFMT_STRING or MQFMT_NONE, and the payload set to the text of an MQSC command.
  • The command server running in the queue manager reads the messages, validates them, and passes the valid commands to the command processor.
  • The command processor then executes the commands, and puts replies to the commands as messages on the reply-to queues that are specified in the incoming messages.

Resource URL

https://host:port/ibmmq/rest/v2/admin/action/qmgr/qmgrName/mqsc

qmgrName
Specifies the name of the queue manager on which to execute the command.
You can specify a remote queue manager as the qmgrName. If you specify a remote queue manager, you must configure a gateway queue manager. For more information, see Remote administration using the REST API.
The queue manager name is case-sensitive.
If the queue manager name includes a forward slash, a period, or a percent sign, these characters must be URL encoded:
  • A forward slash (/) must be encoded as %2F.
  • A percent sign (%) must be encoded as %25.
  • A period (.) must be encoded as %2E.

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

Request headers

The following headers must be sent with the request:
Content-Type
This header must be sent with a value of application/json optionally followed by ;charset=UTF-8.
ibm-mq-rest-csrf-token
This header must be set, but the value can be anything, including being blank.
Authorization
This header must be sent if you are using basic authentication. For more information, see Using HTTP basic authentication with the REST API.
The following headers can optionally be sent with the request:
ibm-mq-rest-gateway-qmgr
This header specifies the queue manager that is to be used as the gateway queue manager. The gateway queue manager is used to connect to a remote queue manager. For more information, see Remote administration using the REST API.

Request body format

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

The following attributes can be included in the request body:
type
Required.
String.
Specifies the type of action to be performed.
runCommandJSON
Specifies that a JSON formatted MQSC command is to be executed
command
Required.
String.
Specifies the initial keyword of the MQSC command. The value can be any one of the following values:
  • alter
  • archive
  • backup
  • clear
  • define
  • delete
  • display
  • move
  • ping
  • purge
  • recover
  • refresh
  • reset
  • resolve
  • resume
  • rverify
  • set
  • start
  • stop
  • suspend
qualifier
String.
Specifies the secondary keyword in the MQSC command.
For example, for an ALTER QLOCAL(qName) command, the qualifier is QLOCAL.
name
Optional.
String.
Specifies the primary argument of the MQSC command.
For example, for an ALTER QLOCAL(qName) command, the name attribute is qName.
For some commands, this attribute is not required. For example, a REFRESH SECURITY command does not require a primary argument.
responseParameters
Optional.
String array.
Specifies which parameters are returned in the response to a request where the value of the command attribute is DISPLAY.
You can specify a value of ["all"] to return all applicable parameters for MQSC commands where the all parameter is supported.
parameters
Optional.
Nested JSON Object.
Specifies the parameters for the command in name and value pairs.
You can specify the parameters in any order, and in any case. Any double quotation marks or backslash characters used within a value must be escaped:
  • A double quotation mark must be represented as \"
  • A backslash must be represented as \\
The name and value pairs are constructed based on the following mapping from the MQSC command:
name
The name part of the name and value pair is the same as the name of the MQSC parameter.
For example, the TRIGTYPE parameter on a DISPLAY QLOCAL MQSC command maps to "trigtype" in the JSON format.
value
The value part of the name and value pair is the value that is used with the MQSC parameter. The JSON that is used to represent the value depends on the type of the value:
  • For an MQSC value that is a string or an enumerated type, then the value used in the JSON format is a JSON string. For example: 
    "chltype" : "SDR",
"descr" : "A String Description."
    Unlike using plain-text MQSC, if the string is case-sensitive, or if it contains special characters, you do not need to enclose the string in single quotation marks.
  • For an MQSC value that is an integer, then the value that is used in the JSON format is an integer. For example: 
    "maxmsgl" : 50000
  • For an MQSC parameter that has no associated value, you must specify a value of YES if the attribute applies. For example, for TRIGGER on a local queue: 
    "trigger" : "yes"
    You cannot specify "trigger" : "no". Instead, you must use the attribute NOTRIGGER: 
    "notrigger" : "yes"
    Similarly, for the attribute REPLACE, you must specify the following string:
    "replace" : "yes"
    You cannot specify "replace" : "no". To indicate that the MQ object should not be replaced, you must use the attribute NOREPLACE:
    "noreplace" : "yes"
  • For an MQSC value that is a list, then the value that is used in the JSON format is a JSON array. Each element in the array is a member of the list. A list with no members must be specified as an empty array. For example: 
    "msgexit" : ["exit1", "exit2", "exit3"],
"rcvexit" : []
    The following MQSC attributes are lists:
    • addrlist
    • arcwrtc
    • authadd
    • authlist
    • authrmv
    • comphdr
    • compmsg
    • comprate
    • comptime
    • connopts
    • exclmsg
    • exittime
    • logs
    • msgdata
    • msgexit
    • names
    • nettime
    • nid, except on CONN commands
    • openopts
    • protocol, only on CHANNEL commands
    • rcvdata
    • rcvexit
    • recip
    • security, except on REFRESH commands
    • senddata
    • sendexit
    • signer
    • suiteb
    • userid, only on TRACE commands
    • userlist
    • xbatchsz
    • xqtime
Single quotation marks that are used in the value are automatically escaped. For example, a descr attribute with the value single 'quotation' marks is represented in the JSON request body as "descr" : "single 'quotation' marks".
For examples of how to format the JSON request, see Examples
For more information about the MQSC commands, see MQSC commands reference.

Security requirements

The caller must be authenticated to the mqweb server and must be a member of one or more of the MQWebAdmin, MQWebAdminRO, or MQWebUser roles. For more information about security for the administrative REST API, see IBM MQ Console and REST API security.

If token based security is used, the LTPA token that is used to authenticate the user must be provided with the request as a cookie. For more information about token-based authentication, see Using token-based authentication with the REST API.

The security principal of the caller must be granted the ability to issue MQSC commands against the specified queue manager.

[AIX, Linux, Windows]On AIX, Linux, and Windows, you can grant authority to security principals to use IBM MQ resources by using the setmqaut command. For more information, see setmqaut (grant or revoke authority).

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

Response status codes

200
The specified command was passed successfully to the queue manager for processing.
400
Invalid data provided.
For example, an invalid MQSC command 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.
403
Access prohibited for one of the following reasons:
  • 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 the required IBM MQ resources.
  • [MQ 9.3.5 Feb 2024]Access prohibited in the current server environment. The administrative REST API is not available in a stand-alone IBM MQ Web Server installation.
404
Queue manager does not exist.
500
Server issue or error code from IBM MQ.
503
Queue manager not running.

Response headers

The following headers are returned with the response:
Content-Type
This header is returned with a value of application/json;charset=utf-8.
ibm-mq-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

If an error occurs, the response body contains an error message. For more information, see REST API error handling.

The format of the response body is standardized, with a consistent JSON schema. However, the content is platform-dependent, reflecting the underlying mechanism for executing MQSC commands.

The response body has the following JSON structure: 

{
  "commandResponse" : [
    {
      "completionCode" : number,
      "reasonCode" :  number,
      "message" : [
        "string",
        ...
        ]
    },
    ...
  ]
  "overallCompletionCode" : number,
  "overAllReasonCode" :  number
}
The fields in the response have the following meanings:
commandResponse
A JSON array of JSON objects that represent individual responses from the execution of the command.
Each response contains the following data:
completionCode
The completion code that is associated with the operation.
reasonCode
The reason code that is associated with the operation.
message
A JSON array of strings that contain any messages that are returned.
parameters
If an IBM MQ object is returned by the request, this object returns name and value pairs that represent the IBM MQ object. For example, after a DISPLAY QUEUE command is sent, a local queue q0 is returned:
"parameters": {
   "queue": "q0",
   "type": "QLOCAL",
   "acctq": "QMGR",
   "altdate": "2018-07-16",
    ...
}
[z/OS]sourceQmgr
The queue manager from which the response was received.
This object is returned only if the queue manager that the command is issued to is in a queue sharing group and responses are received from other queue managers in the queue sharing group.
overallCompletionCode
The completion code that is associated with the operation as a whole.
overallReasonCode
The reason code that is associated with the operation as a whole.

Examples

  • Define a local queue, Q1. The following URL is used with the HTTP POST method: 
    https://localhost:9443/ibmmq/rest/v2/admin/action/qmgr/QM1/mqsc
    The following JSON payload is sent: 
    {
	"type": "runCommandJSON",
	"command": "define",
	"qualifier": "qlocal",
	"name": "Q1",
	"parameters": {
		"share": "yes",
		"trigdata": "lowercasetrigdata",
		"trigdpth": 7,
		"usage": "normal"
	}
}
    A response code of 200 is returned, as the REST command succeeded. The response body that is returned contains the following JSON:
    [AIX, Linux, Windows]On AIX, Linux, and Windows:
    {
    "commandResponse": [
        {
            "completionCode": 0,
            "message": ["AMQ8006I: IBM MQ queue created."],
            "reasonCode": 0
        }
    ],
    "overallCompletionCode": 0,
    "overallReasonCode": 0
}
    [z/OS]On z/OS: 
    {
  "commandResponse": [],
  "overallCompletionCode": 0,
  "overallReasonCode": 0
}
  • Display the queue. The following URL is used with the HTTP POST method: 
    https://localhost:9443/ibmmq/rest/v2/admin/action/qmgr/QM1/mqsc
    The following JSON payload is sent: 
    {
	"type": "runCommandJSON",
	"command": "display",
	"qualifier": "qlocal",
	"name": "Q1"
}
    A response code of 200 is returned, as the REST command succeeded. The response body that is returned contains the following JSON: 
    {
    "commandResponse": [
        {
            "completionCode": 0,
            "parameters": {
                "acctq": "QMGR",
                "altdate": "2019-06-06",
                "alttime": "12.01.21",
                "boqname": "",
                "bothresh": 0,
                "clchname": "",
                "clusnl": "",
                "cluster": "xxxx",
                "clwlprty": 0,
                "clwlrank": 0,
                "clwluseq": "QMGR",
                ...
                "share": "YES",
                ...
                "trigtype": "FIRST",
                "type": "QLOCAL",
                "usage": "NORMAL"
            },
            "reasonCode": 0
        }
    ],
    "overallCompletionCode": 0,
    "overallReasonCode": 0
}
  • Display all the queues on the queue manager, requesting that the alttime and trigdpth parameters are returned. The following URL is used with the HTTP POST method: 
    https://localhost:9443/ibmmq/rest/v2/admin/action/qmgr/QM1/mqsc
    The following JSON payload is sent: 
    {
	"type": "runCommandJSON",
	"command": "display",
	"qualifier": "qlocal",
	"name": "*",
	"responseParameters": ["alttime","trigdpth"]
}
    A response code of 200 is returned, as the REST command succeeded. The response body that is returned contains the following JSON: 
    {
    "commandResponse": [
        {
            "completionCode": 0,
            "parameters": {
                "alttime": "13.36.31",
                "queue": "Q0",
                "trigdpth": 1,
                "type": "QLOCAL"
            },
            "reasonCode": 0
        },
        {
            "completionCode": 0,
            "parameters": {
                "alttime": "13.37.59",
                "queue": "Q1",
                "trigdpth": 7,
                "type": "QLOCAL"
            },
            "reasonCode": 0
        }
    ],
    "overallCompletionCode": 0,
    "overallReasonCode": 0
}
  • [z/OS]On z/OS, display the local queue Q0, which is defined on both QMGR1 and QMGR2 in a queue sharing group. The following URL is used with the HTTP POST method: 
    https://localhost:9443/ibmmq/rest/v2/admin/action/qmgr/QMGR1/mqsc
    The following JSON payload is sent: 
    {
	"type": "runCommandJSON",
	"command": "display",
	"qualifier": "qlocal",
	"name": "q0",
	"parameters": {
		"cmdscope": "*"
	}
}
    A response code of 200 is returned, as the REST command succeeded. The response body that is returned contains the following JSON: 
    {
    "commandResponse": [
        {
            "completionCode": 0,
            "parameters": {
                "acctq": "QMGR",
                "altdate": "2019-01-21",
                "alttime": "10.23.43",
                "boqname": "",
                "bothresh": 0,
                "cfstruct": "",
                "clchname": "",
                "clusnl": "",
                "cluster": "",
                "clwlprty": 0,
                "clwlrank": 0,
                "clwluseq": "QMGR",
                ...
                "trigtype": "FIRST",
                "type": "QLOCAL",
                "usage": "NORMAL"
            },
            "reasonCode": 4,
            "sourceQmgr": "QMGR1"
        },
        {
            "completionCode": 0,
            "parameters": {
                "acctq": "QMGR",
                "altdate": "2019-03-19",
                "alttime": "13.05.02",
                "boqname": "",
                "bothresh": 0,
                "cfstruct": "",
                "clchname": "",
                "clusnl": "",
                "cluster": "",
                "clwlprty": 0,
                "clwlrank": 0,
                ...
                "trigtype": "FIRST",
                "type": "QLOCAL",
                "usage": "NORMAL"
            },
            "reasonCode": 4,
            "sourceQmgr": "QMGR2"
        }
    ],
    "overallCompletionCode": 0,
    "overallReasonCode": 0
}