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.
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.
- 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.
- 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
"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"
}
- 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:
where:{"message-type":{"VERSION":"JSON-version","data-type":"data-value"}}
- 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.
- 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.