Issue a TSO/E command with z/OSMF REST API

You can use this operation to issue a TSO/E command and get a corresponding response.

HTTP method and URI path

PUT /zosmf/tsoApp/{version}/tso

Where:

/zosmf/tsoAPP identifies the TSO/E address space services.
version identifies the version of the TSO/E REST API service. The following value is valid: v1.
/tso informs the service that the request is for a TSO/E address space.

Query parameters

None.

Standard headers

Use the following standard HTTP header with this request:Content-Type: application/json.

Request body

Table 1. Supported parameters for the TSO/E command with z/OSMF REST API.
The request content is expected to contain a JSON object. See Table 1for a description of the fields.
Parameter	Required or Optional	Description
tsoCmd	Required	Specifies the command to issue.
system	Optional	Name of the system in the same sysplex that the command is routed to. The default is the local system.
maxWaitTime	Optional	Specify the max amount of time in seconds that the Issue command API will continue to get responses. The API tries to get as many responses as possible until the amount of time elapsed or until the TSO PROMPT is received. The TSO PROMPT indicates that the TSO address space is ready for more input from the client. The input can either be a new command or the next part of the previous command. After the TSO PROMPT is received, there is no further response for a TSO command. If you do not specify the value for maxWaitTime, the API gets as many messages as possible until any of the three things happen: The TSO PROMPT is received. The API returns if there is no new response during last 5 seconds. 30 seconds elapses. The minimal value is 1 second. The maximum value is 300, which means 5 mins.
cmdState	Optional	Specify the state of the TSO/E command you want to issue: stateless The tsoCmd is a stateless TSO/E command. You can use a single ‘Issue TSO/E command REST API’ to fulfill the request. Note: for a stateless command, all the command responses are returned in the API response. You cannot perform any further action against the TSO/E address space, which is used to issue the command. This is the default. For a single user, you can issue up to 45 stateless command APIs concurrently. Case is not significant. stateful The tsoCmd is a stateful TSO/E command, which means you need to issue a series of TSO/E commands that are related to each other. You need to issue them one after another by the Issue command REST API. Case is not significant. The address space serves these stateful commands, which are identified by the servletKey and kept alive for 10 minutes. If there is no further Issue stateful command or get response request from the user during that time, the address space is released. For a single user, you can issue up to 45 stateful command APIs concurrently. The API is differentiated by the servletKey. It is active for 10 minutes, and is counted as 1 of the 45 during that 10 minutes. This is true even if you do not issue any stateful commands/get response API in the TSO/E address space that is identified by the servletKey.
servletKey	Optional	Unique identifier for a stateful TSO/E command entry. It maps to the TSO/E address space in which the stateful TSO/E command is issued. You can get servletKey from the response of the Issue TSO/E command API. The servletKey is only valid if you previously issued a stateful TSO/E command with Issue Command REST API. For the first command of a serial of stateful TSO/E commands, you do not specify servletKey. You get the value of servletKey from the response JSON. The servletKey is invalid if you do not specify cmdState as stateful.
keyword	Optional	Specifies a regular expression that you want to detect in the command response. For example, suppose that you want to use a regular expression to find the phrase "a regular" in the message "This is a regular expression". If you are not sure how many spaces exist between "a" and "regular" in the message, you can use following key: a[\s]+regular

Note:

If you use a stateful Issue command API, you can use the servletKey to lock a TSO/E address space for following stateful commands/get response for 600 seconds. The address space, which is identified by servletKey will be released after 600 seconds if there’s no further Issue stateful command/get response request from user.
z/OSMF TSO/E services use CEA to create and maintain TSO/E address spaces. The default value of MAXSESSPERUSER for CEA is 10, which means CEA can create and maintain up to 10 TSO/E address spaces for a single user. The default value of MAXSESSIONS is 50, which means CEA can create and maintain up to 50 TSO/E address spaces on the system. You can issue command f cea,d,parms to check these values on your system. The maximum value for MAXSESSPERUSER is 99, and for MAXSESSIONS it is 2000. z/OSMF TSO/E services can maintain up to 45 TSO/E address spaces for stateless request, and up to 45 TSO/E address spaces for stateful request per user. You need to change the MAXSESSPERUSER to 99 and update the MAXSESSIONS to achieve 45/45 address spaces.
For more information about how to change a CEA parameter, see Working with TSO/E address spaces started by CEA in z/OS MVS™ Programming: Callable Services for High-Level Languages and CEAPRMxx (common event adapter parameters) in z/OS MVS Initialization and Tuning Reference.

Required authorizations

To issue the TSO/E command and get response by the TSO/E address space services, you must have:

- READ access to resource account in class ACCTNUM, where account is the value that is specified in the COMMON_TSO ACCT option in parmlib.
- READ access to resource proc in class TSOPROC, where proc is the value that is specified with the COMMON_TSO PROC option in parmlib.

Expected response

On completion, the service returns an HTTP response, which includes a status code that indicates whether your request is complete. Status code 200 indicates success. A status code of 4nn or 5nn indicates an error. For more information, see Error handling.

Table 2. Response content for a successful issue command request
Field name	Description
cmdResponse	Command response in a JSON array.
servletKey	Unique identifier for the servlet entry. It maps to the TSO/E address space in which the TSO/E command is issued. servletKey is returned only when cmdState is stateful.
tsoPromptReceived	Whether the TSO PROMPT sign is received in the command response: Y TSO PROMPT is received. N TSO PROMPT is not received yet.
keywordDetected	The result of the response detection request. This is returned when the keyword is specified. The values are: Y Matching record in the response was found. N Matching record in the response was not found.

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

Table 3. Response JSON object for an unsuccessful issue command request
Field name	Description
returnCode	Identifies the category of error.
returnCode	Identifies the specific error.
reason	Text that describes the cause of the error.

HTTP status codes

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

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

Table 4. Response codes for unsuccessful issue command requests
HTTP Status	Return code	Reason code	Reason	Description
500	8	4	`An error occurred in the TSO/E address space. The error description: %s`	The request failed because an error occurred. The error description is provided in the message text: %s. To obtain more details about the error, check the z/OSMF logs. Correct any errors. If the problem persists, contact the IBM Support Center and provide the error details.
500	8	12	`The system cannot get the local node name and cannot start the TSO/E address space.`	The attempt to prepare a TSO/E address space failed. The z/OSMF TSO/E service failed to retrieve the local node name of the system. Retry the request. If the problem persists, contact your z/OSMF administrator.
400	8	13	`Unsupported Encoding Exception: %s`	The system cannot support %s encoding. For more information, check the z/OSMF logs. Retry the request. If the problem persists, contact the IBM Support Center and provide the error details.
400	8	14	`An error occurred when parsing the TSO/E response data.`	The z/OSMF TSO/E service failed to parse the TSO/E response data. For more information, check the z/OSMF logs. Retry the request. If the problem persists, contact the IBM Support Center and provide the error details.
500	8	16	`An I/O Exception occurred when parsing the issue command request JSON body.`	The z/OSMF TSO/E service failed to parse the issue command request JSON body. For more information, check the z/OSMF logs. Correct any errors. If the problem persists, contact the IBM Support Center and provide the error details.
500	8	17	`The TSO/E API cannot recognize the json field: %s`	The JSON field %s in the request body, is not a supported field.
500	8	18	`The tsoCmd cannot be null.`	The JSON field “tsoCmd” in the request body cannot be null.
500	8	19	`The maxWaitTime must be a positive integer between 1 to 300, cannot be %d.`	The value of the“maxWaitTime” in the request JSON body must be a positive integer 1 - 300 .
500	8	21	`The servletKey cannot be null.`	The JSON field “servletKey” in the request body cannot be null.
500	8	22	`The maximum number of TSO/E address spaces that are allowed for the current user has been reached.`	Refer to message IZUG1127E for a detailed explanation. Display the active TSO/E address spaces and remove or cancel any address spaces that the user no longer needs. To display the active TSO/E address spaces, enter the command D TS,ALL from the operator console. To cancel a TSO/E address space, issue the C u=user-ID,a=ASIDcommand from the operator console, where user-ID is the user's TSO/E ID and ASID is the address space identifier.
500	8	23	`No TSO/E address space exist for servletKey:%s.Check your servletKey.`	No TSO/E address space exists for servletKey:%s. Check your servletKey in the request JSON body.
500	8	25	`Your attempt to start a TSO/E address space for your command has timed out. Try again later.`	Your attempt to start a TSO/E address space for your command timed out. Try again later.
500	8	26	`The TSO/E address space is temporarily unavailable. Refer to IZUG1113E for details and try again later.`	The TSO/E address space is temporarily unavailable. Refer to IZUG1113E for details and try again later.
500	8	27	`The TSO/E address space cannot be created, %s.`	The TSO/E address space cannot be created. The context of the error is provided in the message text: %s. Refer to IZUG1117E for details.
500	8	28	`System I/O exception.`	System I/O exception. To obtain more details about the error, check the z/OSMF logs.
500	8	29	`The TSO/E address space could not be created because an error occurred with the logon procedure or the user settings.`	Verify that the logon procedure exists and is valid. For more information, see message IZUG1121E.
500	8	30	`The TSO/E address space for the request cannot be found.`	The TSO/E address space for the request cannot be found. For more information, check the z/OSMF logs.
500	8	31	`The maximum number of TSO/E address spaces for the system has been reached.`	Refer to IZUG1105E for a detailed explanation. Display the active TSO/E address spaces and remove or cancel any address spaces that are no longer needed. To display the active TSO/E address spaces, enter the command D TS, ALL from the operator console. To cancel a TSO/E address space, enter the command C u=user-ID,a=ASID from the operator console, where user-ID is the user's TSO/E ID and ASID is the address space identifier.
500	8	32	`Failed to create a TSO/E address space. TSO/E user account number has not been defined for use, %s`	Refer to message IKJ56486I for a detailed explanation. One of the following scenarios occurred: The specified account number is not defined to the RACF database. The RACF administrator must first define the account number as a RACF resource and then give the user access that uses the PERMIT command. However, if the procedure is not in the procedure library, the logon attempt continues to fail. The RACF class ACCTNUM is not active. The RACF administrator must activate the RACF class.
500	8	33	`Failed to create a TSO/E address space. TSO/E user account number has not been authorized for the user, %s`	Refer to message IKJ56487I for a detailed explanation. The specified account number is defined to the RACF database. However, this particular user ID is not allowed to use it.
500	8	34	`Failed to create a TSO/E address space. TSO/E user account number is invalid: %s`	Refer to message IKJ56702I for a detailed explanation. The specified account number is incorrect.
500	8	35	`Failed to create a TSO/E address space. Following messages returned by system: %s`	z/OSMF TSO/E service failed to create TSO/E address space. The context of the error is provided in the message text: %s. To obtain more details about the error, check the z/OSMF logs. Correct any errors. If the problem persists, contact the IBM Support Center and provide the error details.
500	8	36	`Failed to create a TSO/E address space. %s`	z/OSMF TSO/E service failed to create TSO/E address space due to the region size exceeds the limit size. The context of the error is provided in the message text: %s. To obtain more details about the error, check the z/OSMF logs. Correct any errors. If the problem persists, contact the IBM Support Center and provide the error details.
500	8	37	`The system you specified is incorrect.`	Specify your request with the correct name of the target system and try again.
500	8	38	`The maximum number of TSO/E address spaces that are allowed for the current user to issue a stateless command has been reached.`	For a single user, you can have up to 45 active TSO/E address space to issue a stateless command.
500	8	39	`The maximum number of TSO/E address spaces that are allowed for the current user to issue a stateful command has been reached.`	For a single user, you can have up to 45 active TSO/E address space to issue stateful command.

Example

In the following example, the PUT method is used to issue a TSO/E command TIME and get corresponding response. On completion, the command response is returned to the user.

Request:
PUT https:// your.company.com/zosmf/tsoApp/v1/tso

Request body:
{
    "tsoCmd" : "TIME"
}

Response:
HTTP/1.1 200 OK
{
  "cmdResponse": [
    {
      "message": "TIME-07:35:12 AM. CPU-00:00:00 SERVICE-21 SESSION-00:00:01 APRIL 6,2021"
    },
    {
      "message": "READY "
    }
  ],
  "tsoPromptReceived": "Y"
}