![[MQ 9.2.0 Jul 2020]](ng920.gif)
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.
- 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:
The response is returned in a plain text format.{ "type": "runCommand", "parameters": { "command": "DEFINE CHANNEL(NEWSVRCONN) CHLTYPE(SVRCONN)" } }
- With a JSON formatted command, the body of the request contains an MQSC command in a JSON
format. For
example:
The response is returned in JSON format.{ "type": "runCommandJSON", "command": "define", "qualifier": "channel", "name": "NEWSVRCONN", "parameters": { "chltype": "svrconn" } }
For more information about using the plain text MQSC command, see POST - plain text MQSC command.
- 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.
- Messages are put to a request queue. These messages have
MsgType
set toMQMT_REQUEST
,Format
set toMQFMT_STRING
orMQFMT_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 use HTTP instead of HTTPS if you enable HTTP connections. For more information about enabling HTTP, see Configuring HTTP and HTTPS ports.
Request headers
- 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.
- 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.
- type
- Required.
- command
- Required.
- qualifier
- String.
- name
- Optional.
- responseParameters
- Optional.
- parameters
- Optional.
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.
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).
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.
- 401
- Not authenticated.
- 403
- Not authorized.
- 404
- Queue manager does not exist.
- 500
- Server issue or error code from IBM MQ.
- 503
- Queue manager not running.
Response headers
- 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.
{
"commandResponse" : [
{
"completionCode" : number,
"reasonCode" : number,
"message" : [
"string",
...
]
},
...
]
"overallCompletionCode" : number,
"overAllReasonCode" : number
}
- commandResponse
- A JSON array of JSON objects that represent individual responses from the execution of the command.
sourceQmgr
- The queue manager from which the response was received.
- 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.
![[MQ 9.2.0 Jul 2020]](ng920.gif)
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
A response code of 200 is returned, as the REST command succeeded. The response body that is returned contains the following JSON:{ "type": "runCommandJSON", "command": "define", "qualifier": "qlocal", "name": "Q1", "parameters": { "share": "yes", "trigdata": "lowercasetrigdata", "trigdpth": 7, "usage": "normal" } }
On AIX, 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
A response code of 200 is returned, as the REST command succeeded. The response body that is returned contains the following JSON:{ "type": "runCommandJSON", "command": "display", "qualifier": "qlocal", "name": "Q1" }
{ "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
andtrigdpth
parameters are returned. The following URL is used with the HTTP POST method:https://localhost:9443/ibmmq/rest/v2/admin/action/qmgr/QM1/mqsc
A response code of 200 is returned, as the REST command succeeded. The response body that is returned contains the following JSON:{ "type": "runCommandJSON", "command": "display", "qualifier": "qlocal", "name": "*", "responseParameters": ["alttime","trigdpth"] }
{ "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
A response code of 200 is returned, as the REST command succeeded. The response body that is returned contains the following JSON:{ "type": "runCommandJSON", "command": "display", "qualifier": "qlocal", "name": "q0", "parameters": { "cmdscope": "*" } }
{ "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 }
- Example of using the where parameter:
The response body that is returned contains the following JSON:{ "type": "runCommandJSON", "command": "DISPLAY", "qualifier": "CHSTATUS", "name": "*", "parameters": { "where": "CHLTYPE EQ RCVR" } }
{ "commandResponse": [{ "completionCode": 0, "reasonCode": 0, "parameters": { "current": "YES", "stopreq": "NO", "substate": "RECEIVE", "rqmname": "MQBB", "chldisp": "PRIVATE", "chltype": "RCVR", "conname": "192.168.0.1", "chstatus": "MQAA.TO.MQBB", "status": "RUNNING" } }], "overallReasonCode": 0, "overallCompletionCode": 0 }