TSO/E address space services

In addition, you must be logged in to z/OSMF, and your user ID must have READ access to SAF resource CEA.CEATSO.* in the SERVAUTH class. If your installation is using RACF and you want to assign administrators and users READ access to the resource, you can create a profile like the following:

//* Permit the Administrators group to this profile             *
 PERMIT CEA.CEATSO.* CLASS(SERVAUTH) ID(IZUADMIN) ACCESS(READ)

//* Permit the Users group to this profile                      *
 PERMIT CEA.CEATSO.* CLASS(SERVAUTH) ID(IZUUSER) ACCESS(READ)

//* Permit the started task USERID to this profile              *
 PERMIT CEA.CEATSO.* CLASS(SERVAUTH) ID(IZUSVR) ACCESS(READ)

//* Make changes effective                                      *
 SETROPTS RACLIST(SERVAUTH) REFRESH

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",
 "tsoData": "TSO/E-messages",
 "appData": "application-messages",
 "timeout": "timeout-indicator",
 "reused": "reconnected-indicator",
 "msgData": "z/OSMF-messages"
 "messages": "unexpected z/OSMF-messages"
}

where:

servlet-key

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.

structure-version

Version of the TSO/E address space services and the JSON object structure 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.

message queue ID

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.

TSO/E-messages

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 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"}}

application-messages

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

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.

reconnected-indicator

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.

z/OSMF-messages

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.

unexpected z/OSMF messages

z/OSMF messages received for unexpected errors.

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.