Get a command response
Use this operation to get the response to a command that was issued asynchronously with the Issue Command service.
HTTP method and URI path
GET /zosmf/restconsoles/consoles/console-name/solmsgs/Ckey-number
GET /zosmf/restconsoles/consoles/defcn/solmsgs/Ckey-number where:
- consolename
- is the name of the EMCS console that was used in the Issue Command request.
- defcn
- indicates that name of the console that was used to issue the command was generated by the REST Console API.
- Ckey-number
- is the command response key from the Issue Command request.
The URL is returned by the Issue Command request in the cmd-response-url field.
Query parameters
None.
Description
This operation gets the messages that were issued in response to a command that was issued asynchronously with the Issue Command service. For the properties that you can specify, see Request content.
On successful completion, HTTP status code 200 is returned. The response content is described in Response content.
The Issue Command service returns the URL of the command response in the cmd-response-url field. For more information about the response content of the Issue Command service, see Response content.
Request content
None.
Authorization requirements
HTTP status codes
On successful completion, HTTP status code 200 is returned and the response body is provided, as described in Response content.
Otherwise, the HTTP status codes in Table 1 are returned for the indicated errors.
| HTTP Status | Return Code | Reason Code | Reason | Description |
|---|---|---|---|---|
| 400 | 1 | 3 | No match for method GET 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 | 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 | 18 | Command is invalid. | The command that was issued is invalid. Please provide a valid command. |
| 500 | 3 | 1 | REST TSO service returned a non-200 status code when creating a 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 | 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 a 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 numbers 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 | 10 | 1 | The message you requested cannot be retrieved due to earlier shutdown of zOSMF server. | 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. Table 2 lists the fields in the JSON object.
| Field name | Description |
|---|---|
| cmd-response | Command response |
| sol-key-detected | Returned when sol-key was specified on the Issue Command service. If the keyword specified with sol-key was found in the command response, the value is true. Otherwise, the value is false. |
If a failure occurs, the response body contains a JSON object with a description of the error.
| Field name | Description |
|---|---|
| return-code | Category of the error. |
| reason-code | Specific error. |
| reason | Text that describes the cause of the error. |
Example HTTP interaction
The example in Figure 1 shows a request to get the response to a system command that was issued asynchronously. The
command was issued with a generated console name. The command response key returned by the issue
command request is C003715.
Figure 1. Sample request to get the response for a system command that was issued
asynchronously
GET https://pev061.pok.ibm.com:443/zosmf/restconsoles/consoles/ibmusecn/solmsgs/C508135The following is the response body for the request.
Figure 2. Sample response body for a get command response request
{"cmd-response":"IEE215I 07.36.34 2016.011 PARMLIB DISPLAY 513\R PARMLIB DATA SETS SPECIFIED\R AT IPL\R ENTRY FLAGS
VOLUME DATA SET\R 1 S PEVTS3 CIMSSRE.R22ONLY.PARMLIB\r 2 S PEVTS3
CIMSSRE.R14ONLY.PARMLIB\r 3 S PEVTS3 CIMSSRE.R13ONLY.PARMLIB\r 4 S PEVTS3
CIMSSRE.R12ONLY.PARMLIB\r 5 S PEVTS3 CIMSSRE.PARMLIB\r 6 S PEVTST HDENNIS..ZOS17.PARMLIB\r
7 S CTTPAK XESCT.PARMLIB\r 8 S CTTPAK SYS1.PARMLIB\r 9 S SDR22 SYS1.PARMLIB.POK\r
S SDR22 SYS1.PARMLIB.INSTALL"}