Start an application in a TSO/E address space
You can use this operation to start an application in a TSO/E address space.
HTTP method and URI path
POST /zosmf/tsoApp/app/<servletKey>/<appKey>where:
- zosmf/tsoApp identifies the TSO/E address space services.
- app informs the service that the request is for an application running in a TSO/E address space.
- <servletKey> identifies the TSO/E address space in which to start the application.
- <appKey> identifies the application to be started.
Standard headers
Use the following standard
HTTP header with this request:
Content-Type: application/json
Custom headers
None.
Request content
Your request must include a JSON object that contains the command required to start the
application, for example:
Figure 1. Starting an application: request content
{"startcmd": "{command} {INMSG} 0x4 {OUTMSG} 0x8004"}where:
- {command}
- Any TSO/E command that can be used to start the application. For example, the ISFWEB parameter starts the SDSF application.
- {INMSG} 0x4 {OUTMSG} 0x8004
- The API uses a z/OS UNIX message queue to facilitate communication between the client and the
application running in a TSO/E address space. Specifically, the API assigns an input and output
message type ID to be used when reading messages from the application (output messages) or writing
messages to the application (input messages). The input message type ID is 0x4 (hexadecimal 4) and output message type ID is 0x8004 (hexadecimal 8004). You must specify variables that the application will recognize. For example, if the application recognizes ISFMSGTYPEW as the input message type and ISFMSGTYPER as the output message type, specify the following value:
ISFMSGTYPEW 0x4 ISFMSGTYPER 0x8004
Processing overview
When the client requests
to start an application in a TSO/E address space, the API completes
the following actions:
- Assigns input and output message types to use for communication with the application to be started. The message types will be used only for the application identified by the appKey.
- Replaces the variables in the command with the assigned message types.
- Sends the TSO/E command to the TSO/E address space identified by the servlet key.
- Attempts to read a TSO/E or application response message. If no messages are received in the time allotted, a timeout indication will be returned. Any TSO/E messages are prioritized over application messages. Typically, when a caller receives a TSO/E message while attempting to receive application messages, the caller processes the TSO/E messages, then attempts to retrieve the queued application messages.
Usage considerations
Required authorizations
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 that contains the application response messages, or a timeout indication. For more details, see Content type used for HTTP request and response data.
Example
To start application BkApp001 in the TSO/E address space associated with servlet key
ZOSMFAD-71-aabcaaaf, submit the request depicted in Figure 2.
Figure 2. Sample request to start an application in a TSO/E address space
POST /zosmf/tsoApp/app/ZOSMFAD-71-aabcaaaf/BkApp001 HTTP/1.1
Host: zosmf1.yourco.com
{"startcmd":"ISFWEB ISFMSGTYPEW 0x4 ISFMSGTYPER 0x8004"}A sample response is shown in Figure 3.
Figure 3. Sample response from a start an application in a 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","ver":"0100",
"appData":...,"timeout":false}