Control-O Servers

This chapter contains the following topics:

• Overview

• Preset Environment Concept

• Control-O Server Types

  • Special Servers

  • General Servers

  • Immediate Server ID

• Server IDs

  • Special Server ID

  • General Server ID

  • Immediate Server ID

• Starting a Control-O Server

• Stopping a Control-O Server

• Specifying Actions to Be Performed on a Control-O Server

  • Time-out

Overview

Control-O servers are started tasks that execute DO TSO, DO KSL, and DO SHELL statements issued by rules.

Control-O servers provide the following benefits:

• They increase the efficiency of KOA script and TSO request (command, CLIST, or REXX procedure) execution by using a preset environment established in previous calls (thereby making logon and logoff procedures, for example, unnecessary for subsequent KOA or TSO calls).

• They enforce security controls by assigning a user ID to each KOA script or SHELL script and to each TSO request, according to the runtime security environment of the rule.

• They enable the running of KOA or SHELL scripts and TSO requests even when other started tasks cannot be started (such as those times when JES is not active).

Preset Environment Concept

A preset environment is a state of initialization necessary for the execution of certain DO KSL and DO TSO statements. A preset environment is managed entirely by the procedure specified in the INITPROC subparameter in the rule definition. The procedure is either a KOA script, or a TSO command, CLIST or REXX procedure. Procedures handling KOA or TSO environments must be defined to Control-O prior to activation of the rules that call the procedures. Depending on the type of call (INIT, RESET, TERM) to the procedure, the preset environment is initialized, reset, or terminated.

• An INIT call establishes the preset environment.

• A RESET call restores the preset environment to the state it was in after initialization.

• A TERM call terminates the preset environment.

For example, for a preset environment named CICSP, a KOA script called CICSP should be defined to perform the environment functions shown in Table 195, which are passed as a parameter.

Table 195 Preset Functions for the CICSP Environment - Example

The type of server determines the instances in which each of the calls is performed.

Control-O Server Types

The following types of servers can be distinguished:

• Special servers

• General servers

• Immediate servers

Servers are defined to Control-O through the CTOPARM customization member. For more information on server definition, see the INCONTROL for z/OS Installation Guide.

Special Servers

Each Special server is associated with a specific preset environment. More than one server can be associated with a preset environment.

Control-O dedicates a request queue for all requests (DO KSL and DO TSO statements) sent to each preset environment.

When a request is received for a preset environment, it is executed by the first available Special server associated with that environment.

The first request for a Special server triggers an INIT call which initializes the environment prior to the request execution. Further requests for that Special server trigger a RESET call, and the preset environment is reset to post-initialization status prior to the request execution.

When the server is shutdown, a TERM call is made to the procedure and the preset environment is terminated.

DO KSL TRAN1
INITPROC CICSP

General Servers

General servers are intended to process DO KSL and DO TSO statements which either do not specify a preset environment or which specify a preset environment for which a Special server has not been defined. These DO statements are sent to the general queue shared by all General servers, and execution is performed by the first General server which becomes available.

DO SHELL statements with no IMMEDIATE=Y parameter specified (the default) are also processed by General servers.

The server always calls the environment procedure to perform initialization. After server initialization and the execution of the DO KSL, DO SHELL, or DO TSO statements, the server calls upon the environment procedure to perform a TERM operation, thus terminating the preset environment.

Recommendation

The Control-O server may access many files or will perform many CLIST or REXX procedures, which cause storage fragmentation or accumulation in the user region. After some time (depending of the number of open, closed, or performing CLISTs and REXXs), the Control-O server may abend with S80A or S106, depending on where the fragmentation was created and what type of storage is required.

Performing a DO TSO process by an IBM service that does not release all system storage creates a storage accumulation.

BMC recommends stopping the server automatically with a Control-O rule before it issues abend S80A or S106. This can be done with an ON EVENT rule that does the following:

DO COMMAND F %%$CONTROLO,SERVER=ALL,TERM.

The servers do not need to be restarted, as they will restart upon the triggering of the next rule that performs a DO TSO, DO KSL, or DO SHELL.

Immediate Servers

Immediate servers are intended to process DO TSO, DO KSL, and DO SHELL statements which must be processed immediately without waiting in a queue. An Immediate server is started for the execution of a single DO statement; it executes the statement and then terminates upon completion of the statement execution. A request is processed by an Immediate server if at least one of the following conditions is true:

• The DO statement specifies IMMEDIATE Y.

• A DO statement is targeted for execution by a General server but no General server is defined in the Control-O installation.

• Queue time-out (described later) occurred for that DO statement. Immediate servers handle a preset environment, specified in the INITPROC parameter, in the same manner as General servers (that is, first the server is initialized, then the DO statement is executed, and then the server is terminated).

Server IDs

Each of the servers defined in a Control-O site is assigned a server ID. The server ID identifies servers in Control-O MODIFY commands and in the Automation Options screen (Screen OA). The formats of the types of servers are described below.

Special Server ID

The format is xxxxxnn.

In this format

• xxxxx is the preset environment name associated with the Special server

• nn is the sequence number attributed to each of the Special servers attached to the same preset environment

For example, if two Special servers are defined for the CICSP preset environment, one Special server for the CICST preset environment, and three Special servers for the IOA preset environment, the server IDs of the various Special servers are

• CICSP01, CICSP02

• CICST01

• IOA01, IOA02, IOA03

General Server ID

The format is GENRLnn.

In this format

• nn is the sequence number (01, 02, 03,...) used to identify the various General servers. The number of General servers is determined at installation time. The maximum is99.

Immediate Server ID

The format is IMMEDnn.

In this format

• nn is the sequence number (01, 02, 03,...) that allows to differentiate between the various Immediate servers. The number of Immediate servers is set at installation time. The maximum is99. At least one Immediate server must be specified.

Starting a Control-O Server

Control-O servers are started implicitly by the Control-O monitor the first time a rule issues a DO statement to be executed by the server. Special and General servers may also be started explicitly by issuing a MODIFY operator command to the Control-O monitor or by the SERVERS option in the Automation Options screen (Screen OA). Once started, a Special or General server remains active until explicitly stopped or until Control-O shutdown.

Stopping a Control-O Server

Control-O monitor shutdown terminates all Control-O servers. In addition, Control-O servers can be terminated explicitly by issuing MODIFY operator commands to the Control-O monitor or by the SERVERS option in the Automation Options screen (Screen OA).

The STOP, FORCE, and TERMINATE commands will stop a server. However

• a server stopped with the STOP or FORCE command will not be restarted implicitly, even when there are requests queued for execution of that server; it remains inactive until explicitly started

• a server stopped with the TERMINATE command can be restarted implicitly or explicitly

Specifying Actions to Be Performed on a Control-O Server

MODIFY commands to Control-O can be used to specify the action to be performed on a server. These actions can also be performed by the SERVERS option in the Automation Options screen (Screen OA).

The format of the command to modify servers is

F CONTROLO,SERVER=serverid,action

In this command,

• serverid is the ID of the server to be modified. The value ALL can be specified to apply the action to all the servers.

• action is one of the actions described in Table196.

Table 196 MODIFY Command Actions to Be Performed on a Server

Time-out

The following types of timeout may occur for a DO TSO, DO KSL, or DO SHELL statement:

• Queue time-out

  Queue timeout occurs when a DO statement is queued to a server beyond the time period defined for that server in Control-O installation parameters. When the timeout occurs, the DO statement is removed from the server queue and rerouted for execution by an Immediate server.

• Execution time-out

  Execution time-out occurs when a DO statement has been executing in a server beyond the time period specified for that DO statement in the TIMEOUT parameter. Following execution time-out, the response of the server depends upon the value of the STOP parameter in the DO statement of the rule. Valid values are:

  • Y (Yes) – The executing request is canceled.

  • N (No) – The request continues to execute.