Extended Automation Mechanism

This chapter contains the following topics:

• Introduction

• Invoking the XAM Interface

• Functions of the XAM Interface

  • The INIT Function – Interface Initialization

  • The TERM Function – Interface Termination

  • The RESOLVE Function – AutoEdit Resolution

  • The SETOLOC Function – AutoEdit Local Variable Setting

  • The SETOGLB Function – AutoEdit Global Variable Setting

  • The DORULE Function – Control-O Rule Triggering

• Special Considerations About Control-O Servers

• REXX External Function Syntax

• REXX External Environment Syntax

• CLIST External Function Syntax

• TSO Command Processor Syntax

• Calling the XAM Functions From a User-Written Program

• XAM Security Aspects

• CTOSCMD XAM Function

  • CTOSCMD Security Aspects

• Provided Samples

Introduction

The XAM (Extended Automation Mechanism) interface of Control-O enables the customer to share information between an external environment and Control-O. The XAM interface can also be used to issue requests which trigger Control-O actions.

Figure 249 XAM (Extended Automation Mechanism) Interface

The XAM interface can be used for:

• AutoEdit expression resolution

• AutoEdit Local variable setting

• AutoEdit Global variable setting

• Control-O rule triggering

Invoking the XAM Interface

XAM interface services can be invoked by the following methods:

• REXX External function

• REXX External environment

• TSO command processor

• CLIST external function

• Direct call from a user-written program

Numerous sample XAM interface invocation scripts or programs are provided. A list of these is provided in Provided Samples.

Functions of the XAM Interface

Table 197 describes the functions that can be passed to the XAM interface.

Table 197 Functions of the XAM Interface

Each of these functions is described in detail in the following sections.

The INIT Function – Interface Initialization

The INIT function initializes the XAM interface.

The INIT function must be the first-called function. Other functions fail when no INIT function has been requested previously.

No parameters need to be specified for the INIT function.

The INIT function creates the necessary environment for the proper interface operations. It provides a new, clean AutoEdit environment.

The TERM Function – Interface Termination

The TERM function terminates the XAM interface.

The TERM function must be the last function called. Other functions fail if requested after the TERM function has been requested.

No parameters need to be specified for the TERM function.

The TERM function causes the interface to clean the obtained areas of storage and cleans the AutoEdit environment.

The RESOLVE Function – AutoEdit Resolution

The RESOLVE function resolves AutoEdit expressions.

The AutoEdit expression to be resolved must be supplied as an argument of the RESOLVE function.

The SETOLOC Function – AutoEdit Local Variable Setting

The SETOLOC function sets AutoEdit Local variables.

The AutoEdit expression that sets the local variable must be supplied as an argument of the SETOLOC function.

The SETOGLB Function – AutoEdit Global Variable Setting

The SETOGLB function sets AutoEdit Global variables.

The AutoEdit expression that sets the Global variable must be supplied as an argument of the SETOGLB function.

The DORULE Function – Control-O Rule Triggering

The DORULE function triggers specified Control-O rules.

The DORULE function is used to request services provided by Control-O rules.

The name of the ON RULE rule to be triggered, followed by its parameters, must be specified as arguments of the DORULE function.

In order to be able to specify the name of the Control-O LIBRARY and TABLE that contains the rule that should be used, you should include the following syntax before the DORULE request:

SETOLOC %%$XAMLB = controlo.tables
SETOLOC %%$XAMTB = table_name

In this syntax

• controlo.tables is the name of the library

• table_name is the name of the table (member) that contains the ALL parameter.

The default in both cases is ALL, which means that Control-O will use the first rule found in the loaded rules with the name used in the DORULE regardless of the name of either the library or the table.

A Control-O rule triggered by the DORULE function shares its local variables with the triggering environment. Changes to AutoEdit variables made by the rule are returned to its caller (such as the REXX program) after the rule terminates and returns control.

Special Considerations About Control-O Servers

When executing interface functions under a Control-O Server (using a DO TSO or DO SHELL statement) Local variables are either shared or not shared with the calling rule, depending on the value specified for the SHARELOC subparameter.

If SHARELOC is set to Y (Yes), changes to Local AutoEdit variables made by the Server are shared with the rule requesting DO TSO or DO SHELL execution.

REXX External Function Syntax

REXX External Function syntax is implemented with the provided CTOREX REXX External function and according to REXX syntax rules. The External function can be called either by using assignment statement syntax or through the REXX CALL statement.

The assignment statement syntax is

rexxvar = CTOREX(function,parameter)

The syntax of the REXX CALL statement is

CALL CTOREX functionparameter

INIT0 = CTOREX("INIT")
SAY "INITIALIZATION =" INIT0
SETLC1 = CTOREX("SETOLOC","%%MYVAR = %%$TIME")
SAY "SETLC1 =" SETLC1
CALL CTOREX "TERM"
SAY "TERMINATION=" RESULT

REXX External Environment Syntax

REXX External Environment syntax is implemented with the provided CONTROLO REXX External environment, and follows the syntax of the REXX ADDRESS statement.

Syntax

ADDRESS CONTROLO function parameter

INIT0 = CTOREX("INIT")
SAY "INITIALIZATION =" INIT0
ADDRESS CONTROLO
"SETOLOC %%MYLOCAL = %%$TIME"
"TERM"

CLIST External Function Syntax

CLIST External Function syntax is implemented as a SYSX External CLIST function, by using the standard IKJCT44B exit of TSO.

Syntax

SET clistvar = &STR(&SYSXfunction(parameter))

PROC 0
SET INIT0 = &STR(&SYSXINIT)
WRITE INITIALIZATION = &INIT0
SET SETLC1 = &STR(&SYSXSETOLOC(%%MYVAR = %%$TIME))
WRITE SETLC1 = &SETLC1
SET TERM0 = &STR(&SYSXTERM)
WRITE TERMINATION = &TERM0
EXIT

TSO Command Processor Syntax

TSO Command Processor syntax is implemented with the provided CTOEXE command processor.

Syntax

CTOEXE 'function' 'parameter'

PROC 0
SET INIT0 = &STR(&SYSXINIT)
WRITE INITIALIZATION = &INIT0
CTOEXE 'SETOLOC' '%%MYLOCAL = %%$TIME'
SET TERM0 = &STR(&SYSXTERM)
WRITE TERMINATION = &TERM0
EXIT

Calling the XAM Functions From a User-Written Program

All XAM functions can be called from a user-written program. This means that Control-O XAM functions can be directly requested from customer-written applications. Sample Assembler program CTOXAMUR in the IOA SAMPLE library demonstrates how the different functions can be directly called.

XAM Security Aspects

Access of the XAM facility is controlled by Control-O Exit 15. For detail see the Control-O security chapter of the INCONTROL for z/OS Security Guide.

CTOSCMD XAM Function

CTOSCMD is an implementation of the XAM interface. It allows the user to issue an operator command from a REXX or CLIST. If a response is needed (for example to return to the calling REXX command), it returns a REXX variable stack or a CLIST variable.

To implement the CTOSCMD XAM function, perform the following steps:

1. Create the XAM interface by calling the "INIT" function.

2. Implement CTOSCMD by specifying the following:

   CTOSCMD ‘command' CMDRESP(response_type) PREFIX(prefix) CMDWAIT(timeout)

   where:

   • command is the command to be issued.

   • response_type is the response option. Valid values:

     • NOWHERE–No response is needed.

     • TERMINAL–Send response to the terminal.

     • CLIST–Send response to a CLIST variable.

     • REXX–Send response to a REXX stack.

   • prefix is the CLIST variable prefix or REXX stack to which the command response will return.

   • timeout is the timeout value, after which, the response is to return to the caller.

Terminate the XAM environment using the "TERM" function upon completion.

CTOSCMD Security Aspects

To implement security for the CTOSCMD function, use the CTOSE15 security module. In addition, you can use this module to protect the INIT and TERM XAM functions and to implement security for an operating system command that may be issued through CTOSCMD. For details, see the Control-O security chapter of the INCONTROL for z/OS Security Guide.

Provided Samples

The following libraries contains basic samples of the interface features. They can be used to test each feature of the XAM facility.

The most comprehensive ones are:

• CTOLSHRT
  Shows how local variables are shared.

• CTOUCMDR
  Shows how to issue a command and obtain the command’s response.

• CTOUKOA2
  Shows how to capture a screen of a VTAM application (such as CICS) and present it to the TSO user.

The above mentioned samples trigger and control the sequence of events. However, they also involve members from the same and other libraries, and they illustrate how the different parts of Control-O can be used together to obtain the desired result.

Table 198 is a list of all provided members containing samples for implementation of the XAM interface. These members are listed according to the library in which they are stored.

Table 198 XAM Interface Implementation Sample Members