TSO/E address space services

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.

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 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.

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.