Start or reconnect to a TSO/E address space

You can use this operation to start a new TSO/E address space or to reconnect to a dormant TSO/E address space.

HTTP method and URI path

POST /zosmf/tsoApp/tso?<parms>
where:
  • zosmf/tsoApp identifies the TSO/E address space services.
  • tso informs the service that the request is for a TSO/E address space.
  • <parms> qualifies the request with one or more of the parameters described in Table 1.

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.

When the interface reconnects to a dormant TSO/E address space, the interface reuses the session resources including the z/OS UNIX message queue.

Note: A dormant TSO/E address space is an address space that has been deactivated for communication through its z/OS UNIX message queue but remains available at a TSO/E READY prompt for a period of time.

Supported parameters

Table 1. Supported parameters for the start and reconnect TSO/E session requests
Parameter Required Description
proc Yes Name of the TSO/E logon procedure to use to log onto the TSO/E address space.
chset Yes Character set to use for the caller’s TSO/E address space. This value is used by the applications running in the TSO/E address space to convert messages and responses from UTF-8 to EBCDIC. The default character set, which is 697 decimal, will be used if zero is specified as the value.
cpage Yes Codepage to use for the caller’s TSO/E address space. This value is used by the applications running in the TSO/E address space to convert messages and responses from UTF-8 to EBCDIC. The default codepage, which is 1047 decimal, will be used if zero is specified as the value.
rows Yes Number of rows to be displayed on the screen. The default number of rows, which is 24, will be used if zero is specified as the value.
cols Yes Number of columns to be displayed on the screen. The default number of columns, which is 80, will be used if zero is specified as the value.
acct No TSO/E user account number.
ugrp No Name of the TSO/E user group.
rsize No Region size to use for the TSO/E address space.
appsessid No (for new), Yes (for reconnect) Identifier that uniquely identifies the TSO/E address space. This parameter is optional when starting a new TSO/E address space, and it is required when reconnecting to an existing TSO/E address space. If an address space with the specified identifier does not exist, a new TSO/E address space will be created and assigned the identifier specified.

Standard headers

Use the following standard HTTP header with this request:

Content-Type: application/json

Custom headers

None.

Request content

None.

Usage considerations

See Usage considerations for the z/OSMF REST services.

Required authorizations

See Required authorizations.

In addition, only the z/OSMF user that started the TSO/E address space is authorized to use the z/OS UNIX message queue associated with that address space.

Expected response

On completion, the service returns an HTTP response, which includes a status code indicating whether your request completed. Status code 200 indicates success. A status code of 4nn or 5nn indicates that an error has occurred. For more details, see Error handling.

The response also includes a JSON object with additional information about the results of the request. For more details, see Content type used for HTTP request and response data.

Example: Creating a new TSO/E address space

To create a new address space with the following settings, submit the request depicted in Figure 1:
  • Procedure name: IKJACCNT
  • Character set: 697
  • Code page: 1047
  • Screen rows: 204
  • Screen columns: 160
  • Region size: 50000
  • Account number: DEFAULT
Figure 1. Sample request to create a new TSO/E address space
POST /zosmf/tsoApp/tso?proc=IKJACCNT&chset=697&cpage=1047&rows=204
&cols=160&rsize=50000&acct=DEFAULT HTTP/1.1

Host: zosmf1.yourco.com
A sample response is shown in Figure 2.Start of change
Figure 2. Sample response from create TSO/E address space request
HTTP/1.1 200 OK
Date: Thu, 13 Jan 2011 05:39:28 +0000GMT
Connection: close

{"servletKey":"ZOSMFAD-71-aabcaaaf","queueID":"4","ver":"0100","tsoData":[{"TSO MESSAGE":
{"VERSION":"0100","DATA":"ZOSMFAD LOGON IN PROGRESS AT 11:27:28 ON 
OCTOBER 12, 2011"}},{"TSO MESSAGE":{"VERSION":"0100","DATA":"NO BROADCAST 
MESSAGES"}}],"timeout":false, "reused":false}
End of change

Example: Reconnecting to an existing TSO/E address space

To reconnect to the TSO/E address space associated with application session ID sdsf_23715376543765, specify the following settings, and submit the request depicted in Figure 3:
  • Procedure name: IKJACCNT
  • Character set: 697
  • Code page: 1047
  • Screen rows: 204
  • Screen columns: 160
  • Region size: 50000
  • Account number: DEFAULT
  • Application Session ID: sdsf_23715376543765
Figure 3. Sample request to reconnect to an existing TSO/E address space
POST /zosmf/tsoApp/tso?proc=IKJACCNT&chset=697&cpage=1047&rows=204
&cols=160&rsize=50000&acct=DEFAULT&appsessid=sdsf_23715376543765 HTTP/1.1

Host: zosmf1.yourco.com
A sample response is shown in Figure 4.Start of change
Figure 4. Sample response from a reconnect to TSO/E address space request
HTTP/1.1 200 OK
Date: Thu, 13 Jan 2011 05:39:28 +0000GMT
Connection: close

{"servletKey":"ZOSMFAD-71-aabcaaaf","queueID":"4","ver":"0100","timeout":false,"reused":true}
End of change
Parent topic: TSO/E address space services