Issue a command

Use this operation to issue a command by using a system console.

HTTP method and URI path

PUT /zosmf/restconsoles/consoles/consolename
PUT /zosmf/restconsoles/consoles/defcn

where:

consolename: is the name of the EMCS console that is used to issue the command. The name must be 2 - 8 characters long, and cannot be defcn, which is reserved.
defcn: indicates that the name of the console that is used to issue the command is generated by the REST Console API, by adding CN to the logon user ID. For example, if the logon user ID is CJOEY, the console name is CJOEYCN. If the user ID is longer than 6 characters, the user ID is truncated. For example, if the user ID is ZOSMFAD, then the console name is ZOSMFACN.

Query parameters

None.

Description

This operation issues a command, based on the properties that are specified in the request body.

On successful completion, HTTP status code 200 is returned. A JSON object typically contains the command response.

When a command is issued synchronously, the console API attempts to get the solicited messages immediately after the command is issued. If there are no messages available within a certain time interval, approximately 3 seconds when your system workload is not high, the API returns “cmd-response”: “” in the response body.

A value for cmd-response of the empty string, “”, usually means that there is no command response. However, it is also possible that the command response arrived after 3 seconds. If that is the case, you can use the cmd-response-url field in the response body to retrieve the command response. You might do this several times to ensure that all messages related to the command are retrieved.

Alternatively, you might examine unsolicited messages, that is, additional messages that are not part of the command response. To do this, you issue the command with option unsol-key to detect a keyword in the unsolicited messages.

For the properties that you can specify on the request body, see Request content.

For a description of the response content, see Response content.

Request content

The request content is expected to contain a JSON object. See Table 1 for a description of the fields.

Table 1. Request content for the issue command request
Field name	Required or Optional	Description
cmd	Required	Specifies the command to issue.
sol-key	Optional	Specifies a keyword that you want to detect in solicited messages, that is, the command response. Case is not significant.
unsol-key	Optional	Specifies a keyword that you want to detect in unsolicited messages. Case is not significant.
detect-time	Optional	Indicates how long the console attempts to detect the value of unsol-key in the unsolicited messages. The unit is seconds. For example, if the value of detect-time is 10, the console checks the unsolicited messages for 10 seconds. The default is 30 seconds.
async	Optional	Indicates the method of issuing the command: Y Asynchronously N Synchronously. This is the default.
system	Optional	Name of the system in the same sysplex that the command is routed to. The default is the local system.
unsol-detect-sync	Optional	Indicates how to detect the keyword that is specified with the unsol-key field from unsolicited messages: Y Synchronously detect the keyword from unsolicited messages. The request is not returned until the unsol-detect-timeout value has elapsed or the detection result is complete. N Asynchronously detect the keyword from unsolicited messages. The request is returned immediately with the detection-url. The client application must invoke the value of detection-url to poll the result of the detection asynchronously. This is the default is the field is not specified.
unsol-detect-timeout	Optional	Indicates how long, in seconds, the request is blocked when the value for unsol-detect-sync is Y and the detection result has not been completed. The default value, 20 seconds, is used when this field is not specified and the value for unsol-detect-sync is Y.

Authorization requirements

See Required authorizations.

HTTP status codes

For a successful request, HTTP status code 200 is returned and the response body is provided, as described in Request content.

For unsuccessful requests, the service returns the status codes that are described in Table 2.

Table 2. HTTP error response codes for an issue command request
HTTP Status	Return Code	Reason Code	Reason	Description
400	1	3	No match for method PUT and pathInfo=' %s '.	The path information, `%s`, in the original request contains a URL that is not acceptable for the z/OS Console API. Ensure that the request contains the correct URL. A console name must be 2 - 8 alphanumeric characters, the first of which must be alphabetic or one of the special characters #, $ or @.
400	1	6	The Content-Type ' %s ' cannot be handled, 'application/json' is expected.	The Content-Type, `%s`, in the original request contains an invalid value for the HTTP Content-Type header. The z/OS Console API accepts only application/json for the Content-Type. Update the value of the HTTP Content-Type header and make sure that the request body is in JSON format.
400	1	11	Format of parameter 'rsize' is wrong, it cannot be changed to a number.	The rsize parameter requires a numeric value, but the supplied value is not a number. Change the value to a number.
400	1	12	The body of the request is not in JSON format.	The request body must be in JSON format, but the supplied request body is not in JSON format. Correct the request body to be in JSON format.
400	1	13	Cannot find 'cmd' in request body, or value of 'cmd' is empty. No command will be issued.	No cmd field was found in the request body, or the cmd field is empty. The cmd field specifies the command to be issued. No command is issued. Ensure the request body includes a cmd field with a value.
400	1	14	Invalid console name. The length of console name must be greater than 1 and less than 9.	The console name that is specified in the URL is not valid. Supply a valid console name.
400	1	17	Command length must be less than 127.	The value of the cmd field exceeds the maximum length of a command, which is 126 characters. Please provide an valid command.
400	1	18	Command is invalid.	The command that was issued is invalid. Please provide an valid command.
500	2	7	Internal https connection timeout.	The internal connection to the zOSMF REST TSO service timed out. Retry the request. If the problem persists, contact your zOSMF administrator.
500	2	8	I/O error when connecting TSO service	An error occurred in the internal connection to the zOSMF REST TSO service. Retry the command. If the problem persists, contact your zOSMF administrator.
500	3	1	REST TSO service returned non-200 status code when creating TSO address space.	The internal connection to the zOSMF REST TSO service returned an error HTTP response when creating a TSO address space. Contact your zOSMF administrator.
500	3	2	REST TSO service returned an error message when creating a TSO address space.	The internal connection to the zOSMF REST TSO service returned a success (200) HTTP response with an unexpected message. Contact your zOSMF administrator.
500	3	3	REST TSO service returned non-200 status code when setting up solicited and unsolicited message display.	The attempt to prepare a TSO address space failed. Retry the request. If the problem persists, contact your zOSMF administrator.
500	3	4	Cannot retrieve TSO AS key from data returned by REST TSO service.	The attempt to prepare a TSO address space failed. Retry the request. If the problem persists, contact your zOSMF administrator
500	3	6	Unknown error occurred when creating or getting the TSO AS.	An unknown error occurred during an attempt to create a TSO address space. Retry the request. If the problem persists, contact your zOSMF administrator.
500	3	7	REST TSO service returned a non-200 status code.	The internal connection to the zOSMF REST TSO service returned an error HTTP response when issuing a command. Contact the zOSMF administrator.
500	3	8	Server end program cannot be found.	The server end program of the REST Console API cannot be found. Contact the zOSMF administrator.
500	3	9	JSON serialization failed when calling a REXX program.	An internal error occurred during the process of translating the response from a TSO service. Contact the zOSMF administrator.
500	3	10	Unexpected messages were found when calling a REST TSO service.	TSO error messages were found when calling the REST TSO service to issue a command. Contact the zOSMF administrator.
500	5	1	REST TSO service returned a non-200 status code when creating a console.	The internal connection to the zOSMF REST TSO service returned an error HTTP response when creating a console. Contact the zOSMF administrator.
500	5	2	Invalid parameters were passed in when creating a console object.	An internal error occurred during an attempt to create a console. Contact the zOSMF administrator.
500	5	3	Cannot retrieve local time zone.	An internal error occurred during an attempt to prepare a console. Retry the request. If the problem persists, contact the z/OSMF administrator.
500	5	4	Cannot retrieve local time zone.	An internal error occurred during an attempt to prepare a console. Retry the request. If the problem persists, contact the z/OSMF administrator.
500	5	5	Cannot retrieve local time zone.	An internal error occurred during an attempt to prepare a console. Retry the request. If the problem persists, contact the z/OSMF administrator.
500	5	6	Cannot retrieve local time zone.	An internal error occurred during an attempt to prepare a console. Retry the request. If the problem persists, contact the z/OSMF administrator.
500	5	7	Create console failed due to a TSO console command error.	An internal error occurred during an attempt to prepare a console. Retry the request. If the problem persists, contact the z/OSMF administrator.
500	5	8	The number of consoles has reached the limit.	The maximum number of consoles supported by the z/OS Console API was reached. Retry the request. If the problem persists, contact the z/OSMF administrator.
500	8	13	Recovery of persistence data is not complete, try later.	The z/OS Console API recovery process was not complete when you issued the request. Wait a few seconds, then retry the request.
500	8	14	Cannot get the command response.	The z/OS Console API failed to get the command response. Retry the request. If the problem persists, contact the z/OSMF administrator.

Response content

On successful completion, the service returns a response body, which contains a JSON object. The JSON object varies depending on whether the request was synchronous or asynchronous. For a description of fields in the JSON object, see Table 3 and Table 4.

Table 3. Response content for a successful synchronous issue command request
Field name	Description
cmd-response	Command response.
cmd-response-url	URL that can be used to retrieve the command response later when the value for cmd-response is empty.
cmd-response-uri	URI that can be used to retrieve the command response later when the value for cmd-response is empty. The URI starts with /zosmf.
cmd-response-key	Key that can be used to retrieve the command response later when the value for cmd-response is empty.

Table 4. Response content for a successful asynchronous issue command request
Field name	Description
cmd-response-url	URL that can be used to retrieve the command response.
cmd-response-uri	URI that can be used to retrieve the command response. The URI starts with /zosmf.
cmd-response-key	Key that can be used to retrieve the command response.
sol-key-detected	Returned when sol-key was specified, and unsol-detect-sync was specified as N or not specified. If the keyword was detected in the command response, the value is true. Otherwise, the value is false.
detection-url	The URL that can be used later to retrieve the detection result for detecting a keyword from unsolicited messages. Returned when unsol-key was specified to detect a keyword in unsolicited messages, and unsol-detect-sync was specified as N or not specified.
detection-uri	The URI that can be used later to retrieve the detection result for detecting a keyword from unsolicited messages. Returned when unsol-key was specified to detect a keyword in unsolicited messages, and unsol-detect-sync was specified as N or not specified.
detection-key	Returned when unsol-key was specified to detect a keyword in unsolicited messages. You can use this to retrieve the result.
status	Status of the unsolicited detection request. Returned when sol-key was specified, and unsol-detect-sync is specified as Y. The values are: expired The detection request has expired. No matching record in the unsolicited messages was found in the time specified by detect-time. detected Matching records in the unsolicited messages were found in the time specified by detect-time. msg contains the message that contains the keyword. timeout The unsol-detect-timeout elapsed before the detection result completed. detection-url The URL that could be used to retrieve the detection result for detecting a keyword from unsolicited messages. detection-uri The URI that could be used to retrieve the detection result for detecting a keyword from unsolicited messages. detection-key The key that could be used to retrieve the unsolicited keyword detection result.

The client application can use any one of detection-url, detection-uri, ordetection-key to retrieve the detection result.

If a failure occurs, the response body contains a JSON object that describes the error.

Table 5. Response content for an unsuccessful issue command request
Field name	Description
return-code	Category of the error.
reason-code	Specific error.
reason	Text that describes the cause of the error.

Example HTTP interactions

The example in Figure 1 shows a request to issue the system command d a,pegasus synchronously.

Figure 1. Sample request to issue a command synchronously

PUT https://pev061.pok.ibm.com/zosmf/restconsoles/consoles/ibmusecn

{"cmd":"d a,PEGASUS"}

The following is the response body for the request. In the response, \r is the return character.

Figure 2. Sample response body

{"cmd-response": "IEE115I 07.30.59 2016.011 ACTIVITY 070\r JOBS  MVS   TS USERS   SYSAS   INITS  ACTIVEVMAX
VTAM   OAS\r 00003  00013   00002   00032  00011   00001\V00020   00015\r PEGASUS NOT FOUND", 
"cmd-response-uri":"\/zosmf\/restconsoles\/consoles\/ibmusecn\/solmsgs\/C005291", 
"cmd-response-url":"https:\/\/pev061.pok.ibm.com:443\/zosmf\/restconsoles\/consoles\/ibmusecn\/solmsgs\/C005291", 
"cmd-response-key":"C005291"}

The example in Figure 3 shows a request to issue the system command d a,PEGASUS synchronously, and attempt to detect PEGASUS in the command response.

Figure 3. Sample request to issue a command and detect a keyword

PUT https://pev076.pok.ibm.com/zosmf/restconsoles/consoles/ibmusecn

{"cmd":"d a,PEGASUS","sol-key":"PEGASUS"}

The following is the response body for the request.

Figure 4. Sample response body

{"cmd-response": "IEE115I 07.30.59 2016.011 ACTIVITY 070\r JOBS  MVS   TS USERS   SYSAS   INITS  ACTIVEVMAX
VTAM   OAS\r 00003  00013   00002   00032  00011   00001\V00020   00015\r PEGASUS NOT FOUND", 
"sol-key-detected":true, "cmd-response-uri":"\/zosmf\/restconsoles\/consoles\/ibmusecn\/solmsgs\/C005291", 
"cmd-response-url":"https:\/\/pev076.pok.ibm.com:443\/zosmf\/restconsoles\/consoles\/ibmusecn\/solmsgs\/C005291",
"cmd-response-key":"C005291"}

The example in Figure 5 shows a request to issue the system command s PEGASUS asynchronously and attempt to detect PEGASUS in the unsolicited messages.

Figure 5. Sample request to issue a system command asynchronously

PUT https://pev076.pok.ibm.com/zosmf/restconsoles/consoles/defcn

{"cmd":"s PEGASUS","unsol-key":"PEGASUS","async":"Y"}

The following is the response body for the request.

Figure 6. Sample response body

{"cmd-response-uri":"\/zosmf\/restconsoles\/consoles\/ibmusecn\/solmsgs\/C005291",
"detection-url":"https:\/\/pev076.pok.ibm.com:443\/zosmf\/restconsoles\/consoles\/ibmusecn\/detections\/dec6800",
"detection-uri":"\/zosmf\/restconsoles\/consoles\/ibmusecn\/detections\/dec6800",
"detection-key":"dec6800",
"cmd-response-url":"https:\/\/pev076.pok.ibm.com:443\/zosmf\/restconsoles\/consoles\/ibmusecn\/solmsgs\/C005291",
"cmd-response-key":"C005291"}

The example in Figure 7 shows a request to issue an s PEGASUS command synchronously, using the default console, and detect keyword PEGASUS in the unsolicited messages synchronously. The keyword is found in unsolicited messages before the timeout is reached.
Figure 7. Sample request to issue an s PEGASUS command synchronously and detect the keyword PEGASUS
```
PUT https://pev061.pok.ibm.com/zosmf/restconsoles/consoles/defcn

{"cmd":"s PEGASUS","unsol-key":"PEGASUS","unsol-detect-sync":"Y"}
```
The following is the response body for the request.
Figure 8. Sample response body
```
{"status":"detected","cmd-response":"BPXM023I (ZOSMFAD) CFZ02300I: Configuration property 
httpAuthType is not supported. Setting ignored.","msg":"$HASP100 PEGASUS ON STCINRDR"}
```

The example in Figure 7 shows a request to issue an s PEGASUS command asynchronously, using the default console, and detect keyword XIAOX in the unsolicited messages synchronously. The detection result is not complete before the timeout (the default of 20 seconds) was reached.

Figure 9. Sample request to issue an s PEGASUS command asynchronously and detect the keyword XIAOX

PUT https://pev061.pok.ibm.com/zosmf/restconsoles/consoles/defcn

{"cmd":"s PEGASUS","async":"Y","unsol-key":"XIAOX","unsol-detect-sync":"Y"}

The following is the response body for the request.

Figure 10. Sample response body

{"cmd-response-uri":"\/zosmf\/restconsoles\/consoles\/defcn\/solmsgs\/C2790426","detection
-url":"https:\/\/pev061.pok.ibm.com:443
\/zosmf\/restconsoles\/consoles\/defcn\/detections\/D5303564","detection-uri":"
\/zosmf\/restconsoles\/consoles\/defcn\/detections
\/D5303564","detection-key":"D5303564","status":"timeout","cmd-response-url":"https:
\/\/pev061.pok.ibm.com:443\/zosmf\/restconsoles\/consoles\/defcn\/solmsgs\/C2790426",
"cmd-response-key":"C2790426"}