POST - plain text MQSC 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.

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 JSON formatted MQSC command, see POST - JSON formatted command.

You can use this REST API command with HTTP to run any MQSC command in plain text format.

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

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.

The following attributes can be included in the request body:

type

Required.

String.

Specifies the type of action to be performed.

runCommand: Specifies that a plain text MQSC command is to be executed

parameters

Required.

Nested JSON Object.

Specifies the parameters for the action.

This nested object contains only one attribute.

command: Required.; A valid plain text MQSC command to be executed.; 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: 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,
      "text" : [
        "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.
text: A JSON array of strings that contain the response text that is associated with the operation for this instance. Note that embedded newlines are stripped from this text.; On AIX, Linux, and Windows, this field contains a single string that contains the response from the command, with any newlines escaped in the usual JSON manner.; On z/OS, this field contains multiple entries. For further information, see Interpreting the reply messages from the command server.

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

The following sequence shows how to create a new server-connection channel that is called NEWSVRCONN on AIX, Linux, and Windows queue managers - our example queue manager is called QM_T1.

First check that the channel does not exist. The following URL is used with the HTTP POST method:
```
https://localhost:9443/ibmmq/rest/v2/admin/action/qmgr/QM_T1/mqsc
```
The following JSON payload is sent:
```
{
  "type": "runCommand",
  "parameters": {
    "command": "DISPLAY CHANNEL(NEWSVRCONN)"
  }
}
```
A response code of 200 is returned, as the REST command succeeded. The response body that is returned contains the following JSON.
```
{
  "commandResponse": [
    {
      "completionCode": 2,
      "reasonCode": 2085,
      "text": [
        "AMQ8147: IBM MQ object NEWSVRCONN not found."
      ]
    }
  ],
  "overallCompletionCode": 2,
  "overallReasonCode": 3008
}
```
The individual response shows a reason code of 2085 (MQRC_UNKNOWN_OBJECT_NAME) and the MQSC command has an overall reason code of 3008 (MQRCCF_COMMAND_FAILED) as it failed to display the requested channel's details.

Now create the channel. The same URL is used with the HTTP POST method:

https://localhost:9443/ibmmq/rest/v2/admin/action/qmgr/QM_T1/mqsc

The following JSON payload is sent:

{
  "type": "runCommand",
  "parameters": {
    "command": "DEFINE CHANNEL(NEWSVRCONN) CHLTYPE(SVRCONN)"
  }

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,
      "reasonCode": 0,
      "text": [
        "AMQ8014: IBM MQ channel created."
      ]
    }
  ],
  "overallCompletionCode": 0,
  "overallReasonCode": 0
}

Finally, check that the channel does exist. Again the same URL is used with the HTTP POST method:

https://localhost:9443/ibmmq/rest/v2/admin/action/qmgr/QM_T1/mqsc

The following JSON payload is sent:

{
  "type": "runCommand",
  "parameters": {
    "command": "DISPLAY CHANNEL(NEWSVRCONN) ALL"
  }
}

A response code of 200 is returned, as the REST command succeeded. The response body that is returned contains the following JSON. The response body is edited for brevity after the CHLTYPE attribute.

{
  "commandResponse": [
    {
      "completionCode": 0,
      "reasonCode": 0,
      "text": [
        "AMQ8414: Display Channel details.   CHANNEL(NEWSVRCONN)                     CHLTYPE(SVRCONN)"
      ]
    }
  ],
  "overallCompletionCode": 0,
  "overallReasonCode": 0
}

The following sequence shows how to create a new server-connection channel that is called NEWSVRCONN on a z/OS queue manager - our example queue manager is called QM21.

First check that the channel does not exist. The following URL is used with the HTTP POST method:

https://localhost:9443/ibmmq/rest/v2/admin/action/qmgr/QM21/mqsc

The following JSON payload is sent:

{
  "type": "runCommand",
  "parameters": {
    "command": "DISPLAY CHANNEL(NEWSVRCONN)"
  }
}

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,
      "reasonCode": 0,
      "text": [
        "CSQN205I   COUNT=       3, RETURN=00000000, REASON=00000000",
        "CSQM297I ]MQ21 CSQMDRTS NO CHANNEL FOUND MATCHING REQUEST CRITERIA ",
        "CSQ9022I ]MQ21 CSQMDRTS ' DISPLAY CHANNEL' NORMAL COMPLETION "
      ]
    }
  ],
  "overallCompletionCode": 0,
  "overallReasonCode": 0
}

The completion and reason codes here are zero, as on z/OS the command is regarded as succeeding, although no matching channel was found.

Now create the channel. The same URL is used with the HTTP POST method:

https://localhost:9443/ibmmq/rest/v2/admin/action/qmgr/QM21/mqsc

The following JSON payload is sent:

{
  "type": "runCommand",
  "parameters": {
    "command": "DEFINE CHANNEL(NEWSVRCONN) CHLTYPE(SVRCONN)"
  }

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,
      "reasonCode": 0,
      "text": [
        "CSQN205I   COUNT=       2, RETURN=00000000, REASON=00000000",
        "CSQ9022I ]MQ21 CSQMACHL ' DEFINE CHANNEL' NORMAL COMPLETION"
      ]
    }
  ],
  "overallCompletionCode": 0,
  "overallReasonCode": 0
}

Finally, check that the channel does exist. Again the same URL is used with the HTTP POST method:

https://localhost:9443/ibmmq/rest/v2/admin/action/qmgr/QM21/mqsc

The following JSON payload is sent:

{
  "type": "runCommand",
  "parameters": {
    "command": "DISPLAY CHANNEL(NEWSVRCONN) ALL"
  }
}

A response code of 200 is returned, as the REST command succeeded. The response body that is returned contains the following JSON. The response body is edited for brevity after the TRPTYPE attribute.

{
  "commandResponse": [
    {
      "completionCode": 0,
      "reasonCode": 0,
      "text": [
        "CSQN205I   COUNT=       3, RETURN=00000000, REASON=00000000",
        "CSQM415I ]MQ21 CHANNEL(NEWSVRCONN          ) CHLTYPE(SVRCONN   ) QSGDISP(QMGR      ) DEFCDISP(PRIVATE   ) TRPTYPE(LU62      )",
        "CSQ9022I ]MQ21 CSQMDRTS ' DISPLAY CHANNEL' NORMAL COMPLETION "
      ]
    }
  ],
  "overallCompletionCode": 0,
  "overallReasonCode": 0
}