TSO/E address space services

TSO/E address space services are an application programming interface (API), which is implemented through industry standard Representational State Transfer (REST) services. A set of REST services is provided for working with TSO/E address spaces on a z/OS® system.

Table 1 lists the operations that the TSO/E address space services provide.

Table 1. Operations provided through the TSO/E address space services.
Operation	HTTP method and URI path
Start or reconnect to a TSO/E address space	POST /zosmf/tsoApp/tso?`parms`
Start an application in a TSO/E address space	POST /zosmf/tsoApp/app/`servletKey`/`appKey`
Receive messages from a TSO/E address space	GET /zosmf/tsoApp/tso/`servletKey`
Receive messages from an application	GET /zosmf/tsoApp/app/`servletKey`/`appKey`
Send messages to a TSO/E address space	PUT /zosmf/tsoApp/tso/`servletKey`?[readReply=true\|false]
Send messages to an application	PUT /zosmf/tsoApp/app/`servletKey`/`appKey`
Ping a TSO/E address space	PUT /zosmf/tsoApp/tso/ping/`servletKey`
End a TSO/E address space	DELETE /zosmf/tsoApp/tso/`servletKey`?[tsoforcecancel=true\|false]

How to use the Swagger interface

You can use the Swagger interface to display information about the TSO/E address space services REST APIs. For more information, see Using the Swagger interface.

Required authorizations

Generally, your z/OSMF user ID requires the same authorizations for using the TSO/E address space services as when you perform these operations through a TSO/E session on the z/OS system. For example, to start an application in a TSO/E address space, your user ID must be authorized to operate that application.

In addition, to use TSO/E address space services, you must have:

READ access to the account resource in class ACCTNUM, where account is the value that is specified in the COMMON_TSO ACCT option in parmlib.
READ access to the CEA.CEATSO.TSOREQUEST resource in class SERVAUTH.
READ access to the proc resource in class TSOPROC, where proc is the value that is specified with the COMMON_TSO PROC option in parmlib.
READ access to the <SAF_PREFIX>.*.izuUsers profile in the EJBROLE class. Or, at a minimum, READ access to the <SAF_PREFIX>.IzuManagementFacilityTsoServices.izuUsers resource name in the EJBROLE class.

You must also ensure that the z/OSMF started task user ID, which is IZUSVR by default, has READ access to the CEA.CEATSO.TSOREQUEST resource in class SERVAUTH.

To create a TSO/E address space on a remote system, you require the following authorizations:

You must be authorized to the SAF resource profile that controls the ability to send data to the remote system (systemname), as indicated:
```
CEA.CEATSO.FLOW.systemname
```
To flow data between different systems in the sysplex, you must be authorized to do so by your external security manager, such as a RACF® database with sysplex-wide scope. For example, to flow data between System A and System B, you must have access to the following resource profiles:
```
CEA.CEATSO.FLOW.SYSTEMA
CEA.CEATSO.FLOW.SYSTEMB
```

The TSO/E address space services authority might already be defined if you are using z/OS data set and file REST services, as those services require similar authority.

For information about client authentication in z/OSMF, see Authenticating to z/OSMF.

Content type used for HTTP request and response data

The JSON content type ("Content-Type: application/json") is used for request and response data. The following JSON object is used by all TSO/E address space services for returning data and status about the requested operations. The attributes that are provided in the JSON object depend on the requested operation.

{
 "sevletKey": "serlet-key",
 "ver": "structure-version",
 "queueID": "message queue ID",
 "remoteSys":"remote system",
 "ceatsoconn":"CEA connection handler",
 "tsoData": "TSO/E-messages",
 "appData": "application-messages",
 "timeout": "timeout-indicator",
 "reused": "reconnected-indicator",
 "msgData": "z/OSMF-messages"
 "messages": "unexpected z/OSMF-messages"
}

Where:

sevletKey

Unique identifier for the servlet entry. It maps to the TSO/E address space ID and provides additional information about the address space. To communicate with the TSO/E address space, the client must provide the servlet key.

ver

Version of the TSO/E address space services and the JSON object structure that is used for this request. The version sequence starts at 0100, and is incremented only if the services or the JSON structure changes. In your application, check the value of the returned structure and verify that your application is compatible with the current API.

queueID

When the TSO/E address space interface starts a new TSO/E session, it also creates a new z/OS UNIX message queue to enable communication between the client and the TSO/E address space. This value is the identifier for the z/OS UNIX message queue.

remoteSys

System name of the remote system on which the TSO/E address space is to be started.

ceatsoconn

100-byte binary key (in hexadecimal), which is used by callers to perform subsequent operations with a remote TSO/E address space. To use this value with CEA APIs, the caller must first convert it to raw binary. This hexadecimal string includes 200 characters, where 2 characters represent 1 byte.

tsoData

TSO/E messages that were received during the request. The tsoData attribute is included in the JSON object only if TSO/E messages were received.

The value that is returned in the tsoData attribute is a JSON object that describes the messages that were received. For example, the TSO/E message JSON format has the following syntax:

{"message-type":{"VERSION":"JSON-version","data-type":"data-value"}}

where:

message-type: Keyword that identifies the type of TSO/E message. The value can be TSO MESSAGE, TSO PROMPT, or TSO RESPONSE.
JSON-version: A four-digit number that identifies the JSON version that is used to format the message.
data-type: Keyword that describes the type of data that is included in the data-value variable. The value can be DATA, HIDDEN, or ACTION.

Example: {"TSO RESPONSE":{"VERSION":"0100","DATA":"ALLOC DA"}}

appData

Messages that are received from an application that is running in a TSO/E address space during the request. The appData attribute is included in the JSON object only if messages were received from an application and no TSO/E messages were received during the request.

timeout

Indicator of whether the request timed out while it waited for a response. The value is "true" if the request timed out. Otherwise, the value is "false".

If the service creates a new TSO/E address space, the service attempts to read the initial startup TSO/E messages. If no messages are received in the allotted time, this value is set to "true".

If the service reconnects the user to an existing TSO/E address space, no startup messages are expected; therefore, the service does not wait for any startup TSO/E messages.

reused

Indicator of whether the service connected the user to an existing TSO/E session instead of a new session. The reused attribute is included in the JSON object only if the appsessid parameter is provided for the start TSO/E address space request. The value that is returned for the reused attribute is "true" if a TSO/E address space with that appsessid exists. Otherwise, the value is "false".

msgData

z/OSMF messages received during the request. The messages attribute is included in the JSON object only if an error occurred during the request. The message ID and message text are provided for each z/OSMF message received.

messages

z/OSMF messages received for unexpected errors.

Error handling

For errors that occur during the processing of a request, the API returns an appropriate HTTP status code to the calling client. An error is indicated by a 4nn code or a 5nn code. Some errors might also include a returned JSON object that contains a message that describes the error.

The following HTTP status codes are valid:

HTTP 200 OK: Success.
HTTP 400 Bad request: Request contained incorrect parameters.
HTTP 401 Unauthorized: Submitter of the request did not authenticate to z/OSMF or is not authorized to use the TSO/E address space services.
HTTP 404 Bad URL: Target of the request (a URL) was not found.
HTTP 500 Internal server error: Programming error.

Error logging

Errors from the TSO/E address space services are logged in the z/OSMF log. You can use this information to diagnose the problem or provide it to IBM® Support, if required.

For information about working with z/OSMF log files, see z/OSMF log files in IBM z/OS Management Facility Configuration Guide.

Usage Notes

Establish the SYSCALL environment in your REXX script.
If you want to run a REXX script and get the response from the TSO/E REST APIs, establish the SYSCALL environment in your REXX script with a SYSCALL request that begins with ADDRESS SYSCALL. For example,
```
if syscalls('ON')>3 then
   do
   say 'Unable to establish the SYSCALL environment'
   return
   end
```
For more information on how to establish the SYSCALL environment, see Establishing the SYSCALL environment in z/OS Using REXX and z/OS UNIX System Services
Things to consider when you use the TSO/E command ALLOCATE:
If you plan to use ALLOCATE to create a data set or file with the APIs provided, you need to use the TSO/E command FREE to release it after you finish working on it. Otherwise, the TSO/E address space locks the data set or file it creates. This is important if you are using the API PUT /zosmf/tsoApp/{version}/tsowith cmdState=stateless. Ensure that the ALLOCATE and FREE commands are invoked in pairs.
How to use 8-character user ID:
By default, TSO/E address space services only support user IDs with 7 characters at the most. If you want to use TSO/E address space services with an 8-character user ID, update the USERIDMAX parameter for IKJTSOxx.

For more information, see Statements and parameters for IKJTSOxx in z/OS MVS Initialization and Tuning Reference.

For information about working with z/OSMF log files, see z/OSMF log files in IBM z/OS Management Facility Configuration Guide.