POST - JSON formatted command

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.
We 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.
We can use this REST API command with HTTP to run any MQSC command. However, the following MQSC commands are not supported when we 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 UNIX, Linux, and Windows, this REST API command is similar to the 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
Request headers
Request body format
Security requirements
Response status codes
Response headers
Response body format
Examples

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.

We can specify a remote queue manager as the qmgrName. If you specify a remote queue manager, we 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.

We can use HTTP instead of HTTPS if you enable HTTP connections. For more information about enabling HTTP, see Configure 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 we 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 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.

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

We 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, we 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, we must specify a value of YES if the attribute applies. For example, for TRIGGER on a local queue:
"trigger" : "yes"
We cannot specify "trigger" : "no". Instead, we must use the attribute NOTRIGGER:
"notrigger" : "yes"
Similarly, for the attribute REPLACE, we must specify the following string:
"replace" : "yes"
We cannot specify "replace" : "no". To indicate that the MQ object should not be replaced, we 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.

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

On UNIX, Linux, and Windows, we 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).

On z/OS, see Set 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

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.

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”,
    ...
}
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: On UNIX, Linux, and Windows:
{
    "commandResponse": [
        {
            "completionCode": 0,
            "message": ["AMQ8006I: IBM MQ queue created."],
            "reasonCode": 0
        }
    ],
    "overallCompletionCode": 0,
    "overallReasonCode": 0
}
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
}
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
}
Parent topic: /admin/action/qmgr/{qmgrName}/mqsc

Last updated: 2020-10-04