TSO/E address space services

The TSO/E address space services is 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, as described in this topic.

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]

Using 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 requires that your user ID 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 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 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 be permitted 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 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. Note that 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 used to format the message.
data-type
Keyword that describes the type of data included in the data-value variable. The value can be DATA, HIDDEN, or ACTION.

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

appData
Messages received during the request from an application running in a TSO/E address space. 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 waiting 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 time allotted, 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 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, message text, and stack trace 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 IBM z/OS Management Facility Configuration Guide.