General Information

A DO TSO statement can be used to initiate any TSO command, CLIST or REXX procedure that does not require terminal input (that is, one that is executable from READY mode without prompting for additional information).

Use of the TSO option can be resource-consuming (because of the nature of TSO). For performance reasons, whenever possible, use regular Control-O functions or Control-M activated tasks.

Control-O AutoEdit variables embedded in a DO TSO statement are automatically resolved (replaced) at time of rule activation. For more information about the AutoEdit facility, see AutoEdit Facility.

Wait Completion Mode

Execution of the DO statements that follow a DO TSO statement can be delayed until the TSO command, CLIST, or REXX procedure has finished executing, thereby enabling checking of the completion code. This delay is achieved by specifying Y (Yes) for the WAITMODE subparameter, which places the rule in Wait (Completion) mode. The TIMEOUT subparameter can be used to specify how long (in seconds) to wait for completion of the TSO command, CLIST, or REXX procedure.

When rule execution is resumed, the %%TSORC AutoEdit system variable will contain either the completion code of the TSO command, CLIST, or REXX procedure, or the value 522, which means that the TIMEOUT limit was reached before completion of the TSO command, CLIST, or REXX procedure.

Wait mode can also be specified for a TSO command, CLIST, or REXX procedure execution by specifying a DO SET=%%WAITTSO = Y statement before the DO TSO statement. Using this method, a TIMEOUT period may be specified through a DO SET %%TIMEOUT=value statement. This method is supported for historical reasons.

Using a Preset Environment

DO TSO statements are executed by Control-O servers. Servers are started tasks that are managed automatically by Control-O. You can define Immediate, Special, and General servers. These server types are discussed in detail in Chapter 5, "Control-O Servers." However, when defining a DO TSO statement, bear in mind the following information:

• Immediate servers

  Immediate servers are useful for either

  • TSO commands, CLIST, or REXX procedures that need to be executed immediately, for example, those that need to bypass the wait queue of the server
  • TSO commands, CLIST, or REXX procedures that should not be executed by a Special or General server, for example, long running scripts that delay the running of other scripts waiting to be executed

  To request an Immediate server, type Y (Yes) in the IMMEDIATE subparameter.

• Special servers

  Special servers are useful when the same environment is used frequently for TSO requests. This generally occurs when different TSO commands, CLIST, or REXX procedures (in the same or different rules) use the same environment. Use of the same environment by many TSO requests improves performance considerably.

  To request a Special server, do the following:

  1. Type N (No) in the IMMEDIATE subparameter, or leave it blank.
  2. Enter the name of the TSO command, CLIST, or REXX procedure that handles the preset environment in the INITPROC subparameter.
  3. Ensure that a Special server with the name specified in the INITPROC subparameter has been defined to Control-O.

• General servers

  General servers are useful when scripts infrequently use a specific environment and/or do not use a preset environment.

  To request a General server, do the following:

  1. Type N (No) in the IMMEDIATE subparameter, or leave it blank.
  2. Ensure that the necessary environment is established by either the script specified in the DO TSO statement or by the TSO command, CLIST, or REXX procedure specified in the INITPROC subparameter.
  3. Ensure that there is no Special server defined to Control-O with the same name as the TSO command, CLIST, or REXX procedure specified in the INITPROC subparameter (if one was specified).

  Whenever INITPROC is specified, Control-O ensures that the indicated TSO command, CLIST or REXX procedure is automatically invoked to maintain the preset environment.

  Ensure that the procedure specified in the DO TSO statement does not perform any of the functions performed by the procedure specified in INITPROC.

  For information on how to define servers, see the INCONTROL for z/OS Installation Guide.