KeyStroke OpenAccess (KOA)

The KeyStroke OpenAccess facility (KOA) permits two-way communication between Control-O and any VTAM application. Examples of VTAM applications are performance monitors, online systems, and so on. Information can be collected from these applications and used as part of the Control-O decision process. Commands under these applications can also be triggered based on Control-O rules. The possible uses of KOA include:

• KOA Language Overview

• KOA Implementation Considerations

• KOA Recording

You can also do the following:

• Acquiring performance data from online performance monitors (for example, OMEGAMON or MV Manager for INCONTROL) and reacting to the acquired data.

• Logging on to problem management systems to open or update problem tickets.

• Logging on to electronic mail systems and sending alert messages to Customer Support.

• Logging on to online communication systems (for example, CICS, IMS/DC, IDMS/DC, COM-PLETE) to verify the availability and serviceability of online systems and their applications.

• Logging on to the IOA Online facility (using the IOA VTAM monitor).

• Logging on to online communication systems to activate facilities.

• Logging on to VM, as well as its operator ID.

• Logging on to network management products (such as NetView).

• An open interface to VTAM applications is an integral part of Control-O as a console automation product. The KeyStroke OpenAccess facility uses the same syntax and the same concepts as the standard IOA KeyStroke Language (KSL). Therefore, the same language and syntax can be used both for accessing VTAM applications and for reporting. The KeyStroke OpenAccess facility simulates the keystrokes of a user working in VTAM application screens the same way KSL does for users working in IOA screens. Extended AutoEdit capabilities allow communication between Control-O/KOA and VTAM applications.

KOA Language OverviewLink copied to clipboard

The KOA language commands form a "superset" (extended version) of the KSL language commands. All KSL commands and parameters are included in the KOA language, but in addition, KOA includes communication commands that provide and control access to VTAM applications.

KOA syntax is the same as the syntax for KSL, which is described earlier in this chapter. KOA commands are described in detail later in this chapter.

KOA LogicLink copied to clipboard

KOA commands are combined and stored in scripts. When the script is activated, KOA processes the commands listed in the script. A typical script initiates a session with a VTAM application, and includes the following basic steps:

Session LogonLink copied to clipboard

KOA runs as a VTAM application, which emulates a terminal (according to specified parameters) and establishes a session with the VTAM application through the LOGON command.

Session ProcessingLink copied to clipboard

The script runs, performing tasks – such as extracting and saving data from an online application; running reports; and sending ("shouting") messages to various destinations.

Session LogoffLink copied to clipboard

The VTAM application session is disconnected through the LOGOFF command.

With KOA, several VTAM application sessions can be active at the same time. A unique session identifier is assigned to each session, so that a KOA script can switch back and forth between active sessions.

Figure 1 VTAM Session LOGOFF

Two-way communication is established and maintained throughout a VTAM application session. An implied "send and receive" relationship forms the basis of communication – for every keyboard input that is sent by KOA, a matching response is received from the VTAM application. For example, KOA transmits (sends) the PF01 key command, and the VTAM application responds by displaying help information.

This two-way communication represents the default method of exchanging information between KOA and VTAM. The KOA language also contains commands that allow you to change this method. For example, updated screens from the VTAM application can be received repeatedly without KOA first sending a request.

For information about creating and running scripts, see Activating the KOA Language.

Principles of KOA OperationLink copied to clipboard

KOA scripts can be generated automatically by the KOA Recorder, which is described in KOA Recording, or manually, as described below.

To manually write a script, imagine yourself in front of a terminal that is connected to VTAM only – for example, the opening screen that you receive when your terminal is switched on. You are not yet connected to any specific application. You must then log on to an application.

To explain how the script language works, we will use simplified examples of KOA scripts.

LOGON APPLID CICSP SESSID CICPLABEL CHECK
CURSOR POS 1 15
IFSCREEN `WELCOME TO CICS/MVS’ GOTO CONTINUE
GETSCREEN
GOTO CHECK
LABEL CONTINUE
CLEAR
TYPE `CEMT INQUIRE DATASET(*) OPEN’
ENTER
PRINTSCREEN 1 24
PF03
CLEAR
TYPE `CSSF LOGOFF’
ENTER
LOGOFF
END

Sample KOA Scripts and ReportsLink copied to clipboard

The IOA SAMPLE library contains examples of KOA scripts and KSL reports. Each script and report invokes a few CALLMEM members to perform its functions.

Additional KOA samples are located in the Control-O SolveWare libraries, and described in the Control-O SolveWare Reference Guide.

Activating the KOA LanguageLink copied to clipboard

The following methods are available for activating KOA scripts:

Activate the script within a Control-O rule.

ON COMMAND ...
DO KSL=scriptname %%x %%y %%z
DO ...

DO SET=%%WAITKSL = YES
DO KSL=scriptname %%x %%y %%z
   WAITMODE x
DO IF %%KSLRC EQ 0
       DO ...
ENDIF

Procedure IOARKOA is used to activate the KOA script. Important DD statements are:

Table 9 IOARKOA Important DD Statements

Activate the script as a started task. Pass the script name and script parameters as procedure parameters, using the following syntax:

S IOARKOA,PARM=`TRANID=KOA,scriptname script-parameters’

KOA Commands and Variables SummaryLink copied to clipboard

A brief summary of the KOA commands and variables is shown below. These commands are in addition to the KSL commands discussed elsewhere in this chapter.

Table 10 KOA Screen Commands

Table 11 KOA Flow Commands

Table 12 KOA Communication Commands

Table 13 KOA Special Variables

KOA Commands and VariablesLink copied to clipboard

The KOA commands and variables are described in greater detail below.

Braces ({ }) indicate that one of the items listed between the braces must be specified. Square brackets ([ ]) denote optionality; none or several of the items listed between the brackets can be specified.

Certain commands accept KOA and/or AutoEdit variables. When both KOA and AutoEdit variables are specified, KOA variables are resolved (replaced) first.

KOA CommandsLink copied to clipboard

Table 14 KOA Screen Commands

Table 15 KOA Flow Commands

Table 16 KOA Communication Commands

KOA Special VariablesLink copied to clipboard

Table 17 KOA Special Variables

KOA Implementation ConsiderationsLink copied to clipboard

VTAM application programs (for example, TSO, CICS, IMS/DC, OMEGAMON) communicate using Logical Units. A Logical Unit (LU) is any item that is used to send information to, and receive information from, VTAM application programs. Standard examples of LUs are terminals and terminal emulation programs. The KOA facility initiates VTAM application sessions and communicates with VTAM applications as if it were a terminal. Therefore, KOA can perform any action that a terminal can perform.

For information on installing the KOA facility, see the INCONTROL for z/OS Installation Guide.

Session CharacteristicsLink copied to clipboard

When a Logical Unit (LU) starts a session (LOGON), it provides a set of parameters that identify the LU to the VTAM application. The parameters include screen size; ability to display extended data stream (such as color or highlights); and other parameters that determine session protocol. Parameters describing the screen in a VTAM session are grouped into a LOGMODE entry. LOGMODE entries are, in turn, stored in LOGMODE tables.

KOA emulates different types of terminals according to user specifications. The KOA language provides commands such as SCREENSIZE and COLOR for automatic selection of LOGMODE entries from a predefined list (which is created during KOA installation). Four different terminal sizes are currently available, and each size may or may not support extended data stream.

You can override the KOA-selected LOGMODE by specifying the LOGMODE parameter of command LOGON. In this case, LOGMODE (and not the commands SCREENSIZE and COLOR) determines terminal characteristics.

Certain online systems (such as IMS/DC and, optionally, CICS) require that LUs be predefined, and that they be stored in internal tables. Each definition in the table contains the name and characteristic for that LU. When logging on to these online systems, the LOGMODE information is ignored and the predefined values are used. In this case, the SCREENSIZE, COLOR and LOGMODE commands and parameters have no effect.

Initiating a SessionLink copied to clipboard

A session between a terminal and a VTAM application is initiated by logging on to the application and specifying the name (as defined to VTAM) of the requested VTAM application. KOA command LOGON performs exactly the same function. In addition, for each session that is initiated, KOA selects a terminal name (which is used during communication with the VTAM application). This terminal name is dynamically selected from a predefined pool of terminal names as defined in member CTOPARM.

The TERMINAL parameter of command LOGON can be used to force a specific terminal name for the session. This may be useful when the VTAM application performs security checks based on terminal name.

As part of the logon process, the LU can pass information (messages) to the VTAM application. For example, the user ID can be passed to TSO. The DATA parameter of command LOGON performs this function.

Most cases are handled automatically, and KOA receives the first screen immediately following command LOGON. However, in certain situations the user receives an "empty" screen (or several "empty" screens) before the expected first screen. Scripts must be designed to handle these situations.

Exchanging MessagesLink copied to clipboard

KOA expects to receive a screen (information) back from a VTAM application each time a screen is sent to the application. This implied send and receive method of exchanging information is the default method of communication between KOA and VTAM. This means that whenever a screen is sent to the VTAM application (such as through ENTER, ATTN, CLEAR, or PFxx), KOA automatically performs a receive operation in order to receive an updated screen from the application. (Note that the same process is automatically performed after the logon process completes.) From the point of view of the script, the current screen is the application’s response to the previously sent screen.

To eliminate the implied receive and override the default method, command SCREENMODE NORECEIVE should be used (the default is SCREENMODE RECEIVE). In NORECEIVE mode, KOA does not wait for responses from the VTAM application, and the script continues processing. When operating in NORECEIVE mode, KOA command GETSCREEN should be specified in order to receive a message from the VTAM application.

The KOA default method of exchanging information ensures that, at any stage, the script operates on a screen that is ready to receive input (that is, the VTAM application is waiting for input). For example, when a user communicates with an application, the keyboard is always unlocked (reset) so the user can enter data. KOA scripts must operate under similar conditions. To guarantee these conditions, KOA repeatedly receives messages from the application – until a message is received indicating that the application is now waiting for input from the LU.

Some situations require a different method of exchanging information. For example, a KOA script can determine independently if or when to send data to – or request additional messages from – the VTAM application. This method may be required for situations where the application sends messages at fixed intervals, without first unlocking the screen. To choose this mode of information exchange, command SCREENMODE ANY should be used (the default is SCREENMODE UNLOCKED). More complex KOA scripts must be written to facilitate this method of exchanging information.

When the current KOA SCREENMODE is ANY, a message may not be "sendable" to the application because the screen (keyboard) is locked. A user at a terminal, in this situation, simply presses the attention key and waits until the keyboard is unlocked. In KOA, command ATTN sends an attention request to the application, and receives an unlocked screen from the application.

Terminating a SessionLink copied to clipboard

Two different methods exist for terminating a session between a user’s terminal and a VTAM application:

Application logoffLink copied to clipboard

Issue a (VTAM application) command to terminate the session. For example, /RCL (in IMS/DC), CESF LOGOFF (in CICS), and LOGOFF (in TSO) instruct the application to terminate the session, and free the terminal for other usage. This is the proper method for requesting session termination from the VTAM application.

VTAM logoffLink copied to clipboard

Use the keyboard SysRq (System Request) function or simply switch off the terminal. This will probably free the terminal for other usage, but might not close the application session properly. For example, a TSO session will not be terminated, but is available for a reconnect from another terminal.

KOA supports both methods of session termination. It is recommended that both methods be specified within the script. KOA scripts should terminate the session with an ‘application logoff’ and then use the KOA command LOGOFF to perform a `VTAM logoff’ which releases the terminal for use.

For example, to terminate a CICS session:

Table 19 KOA Sample Script to Terminate a CICS Session

When a session is terminated in an orderly way, the application usually sends an "end-of-session" message (such as when TSO sends an IKJ56470I message) and then releases the terminal. Using the default method of information exchange (implied send/receive), KOA receives that message, and supplies a return code to the script that indicates that the session is no longer active. The script can either handle that return code while it is terminating the session, or ignore (not receive) the last message from the application.

For example, terminate a TSO session:

Table 20 KOA Sample Script to Terminate a TSO Session

Unexpected MessagesLink copied to clipboard

During a session between a VTAM application and a terminal, most received messages are expected. For example, a user knows that pressing PF01 displays a Help screen. However, there are situations where unexpected messages (unsolicited messages) are displayed on the terminal.

An example of an unexpected message is a message sent by the operator to a TSO user. When the message is received, the user simply presses the Enter key and continues working. Similarly, a KOA script can also handle unexpected messages, and can continue processing based on the user’s specifications.

To handle unexpected messages, KOA is designed so that each time the script sends a message to the application, it first checks if the VTAM application has sent a message to KOA. A message to KOA is not expected at this time (because the script was about to send its own message). The unexpected message is handled using one of the methods listed below:

If the current SCREENMODE is IGNUNSOL (default), KOA ignores the unexpected message and sends its own message to the application.

If the current SCREENMODE is GETUNSOL, KOA does not send its own message, and returns to the script with an appropriate return code. Based on the return code, the script determines whether to accept (with command GETSCREEN), or to ignore the unexpected message (by sending the same message as before).

The sample script below illustrates the handling of unexpected messages during a TSO session:

Table 21 KOA Sample Script to Handle Unexpected Messages During a TSO Session

AutoRefresh HandlingLink copied to clipboard

Several products (especially performance monitors) periodically refresh the terminal screen without expecting input from the terminal. This automatic process (AutoRefresh) does not conform to the default KOA information exchange method, as explained in Exchanging Messages.

When a script sends a message to an application, KOA waits until a reply is received. Once the reply is received, the script continues (according to the default method). In order to receive a message from the application without first sending a message (as in the AutoRefresh case), specify command GETSCREEN. This command instructs KOA to receive any immediately available messages from the application. If no messages are currently available, KOA does not wait for a message from the application (as in the default method). Instead, KOA supplies a return code indicating that no message is available. Before retrying the operation, KOA can be instructed to either wait for a specific amount of time, or perform other actions.

The following example demonstrates AutoRefresh handling using OMEGAMON. (Commands /AUPON and /AUPOFF are used to start and stop AutoRefresh.):

Table 22 KOA Sample Script for Handling AutoRefresh using OMEGAMON

Using KOA to Access the IOA Online FacilityLink copied to clipboard

The IOA Online facility can be activated under the VTAM environment, and is therefore available for KOA processing.

Note: The IOA Online facility is also available under various online communication systems (for example, CICS, IMS/DC, TSO). Therefore, KOA scripts can access the IOA Online environment directly through these facilities.

Since KOA is basically an extension of KSL, every KSL script (with minor modifications) can be run as a KOA script. This is achieved by including a few communication commands in the script, as in the sample script (member RUKORDER in IOA SAMPLE library) shown below:

Table 23 KOA Sample Script to Access the IOA Online Facility

Working with Control-O AutoEdit VariablesLink copied to clipboard

The Control-O AutoEdit facility is also available under KOA. All AutoEdit functions available under Control-O rules are supported. This expands the versatility of KOA and provides an additional communication path (method of sending information) to Control-O. The following AutoEdit commands are available:

SETOLOC %%cto-var = expression

SETOGLB %%cto-var = expression

SETVAR %koa-var DATA expression

where expression is any valid Control-O AutoEdit expression, which may contain KOA variables. KOA variables are resolved first.

Since KOA scripts can be executed independently of the Control-O monitor, the following restrictions apply:

• Global variables can be used only when the Control-O monitor is active.

• A Global variable’s scope is limited to the CPU where the KOA script is running.

The following sample script illustrates the use of AutoEdit and KOA variables in a KOA script. The script tracks the number of times CPU usage was higher than 90% (according to information from a performance monitor).

Table 24 KOA Sample Script Using AutoEdit and KOA Variables

Exception HandlingLink copied to clipboard

KOA scripts can communicate with any VTAM application that runs in the SNA network. This type of operating environment is very dynamic, and various events can occur during KOA operation. Therefore, scripts should be designed to handle potential exceptions.

The KOA language supplies the following variables that provide the cause of an exception:

Table 25 KOA Exception Handling Variables

To simplify script design, it is recommended that a general exception handling section be included in the script. This section should establish exception handling procedures for any possible exception, thus eliminating the need to check the result (successful, or unsuccessful) of each individual communication operation.

Command ON SCREENERROR allows specification of a label to which script flow branches if a communication operation is unsuccessful. Flow can be directed to different exception handling sections throughout the script. This is achieved by specifying different labels as parameters to command ON SCREENERROR at different points in the script. A script can also execute without any exception handling section (by specifying command ON SCREENERROR without parameters). In this last case, no exception handling procedures are initiated when an exception occurs.

The exception handling routine usually examines the three KOA variables listed above to check the cause of the exception.

There are two exceptions that are not controlled by the general exception handling section of a script:

When the session receives an unexpected (unsolicited) message, and command SCREENMODE GETUNSOL was specified. In this case, KOA variable %VTAMERR contains the value UNSOLMSG.

When command GETSCREEN is specified, but no data is available from the VTAM application. In this case, KOA variable %VTAMERR contains the value NODATA.

For these two situations, design the script so that it checks return codes after each communication operation.

Communicating With Control-OLink copied to clipboard

KOA scripts communicate with Control-O using several methods:

KOA ParametersLink copied to clipboard

A maximum of nine arguments can be included in a DO KSL statement. These arguments are assigned to KOA variables %A1 through %A9 (where the first argument is assigned to variable %A1, the second argument to %A2, and so on). For more information see the DO KSL parameter in the Control-O User Guide.

KOA Return CodeLink copied to clipboard

KOA scripts supply return codes through variable %RC. Return codes can be checked by a Control-O rule in the following way:

Table 26 KOA Sample Script to Check KOA Return Codes

AutoEditLink copied to clipboard

Control-O Global variables can be accessed or set by a KOA script. KOA command SETOGLB sets Global variables. KOA commands that accept AutoEdit expressions as parameters can access Global variables.

Local and System AutoEdit variables are normally only accessible in the KOA script. However, when the WAITMODE subparameter is set to Y (Yes) and the SHARELOC subparameter is set to Y (Yes) in a DO KSL statement, the calling rule’s Local and System variable environments are shared with the KOA script.

Shout FacilityLink copied to clipboard

KOA’s SHOUT command allows a script to send messages to the console, TSO users, or the IOA Log. Messages to the console can be specified to trigger Control-O rules.

Using a Preset KOA EnvironmentLink copied to clipboard

Execution of DO KSL statements can be optimized by indicating (in the INITPROC subparameter) a script that handles a preset environment. In the text below, KOA scripts for preset environments are discussed in detail.

For information about DO KSL statements see the DO KSL parameter in the Control-O User Guide. For server-related installation details see the INCONTROL for z/OS Installation Guide.

The sample rule below invokes KOA script CICSINQ to check whether or not a data set is open. If the data set is closed, the rule invokes script CICSOPEN to open the data set. Script CICST specified in the INITPROC subparameter handles the preset environment.

Note the following about the sample rule below:

• IMMEDIATE–If scripts are to be executed by an Immediate server, specify Y (Yes) in the IMMEDIATE subparameter.

• INITPROC–If scripts are to be executed by a Special server, a Special server named CICST must be defined to Control-O.

If scripts are to be executed by a General server, either INITPROC should be blank or there must not be a special server defined by the specified name (CICST).

Figure 4 Sample Control-O for Optimizing DO KSL Statements using KOA Scripts

 RL: CICSOPEN   LIB CTOW.WORKO.RULES                             TABLE: AA
 COMMAND ===>                                                    SCROLL===> CRSR
------------------------------------------------------------------------------
  ON COMMAND  = CICSOPEN *
     JNAME          JTYPE         SMFID        SYSTEM       USERID
     ROUTE          DESC          CONSOLEID    CONSOLE                      
     APPEARED     TIMES IN      MINUTES                          And/Or/Not
  OWNER IOAADMIN GROUP                         MODE PROD    RUNTSEC       
  DESCRIPTION   CHECK IF A FILE IS OPEN FOR CICS USAGE. IF NOT, OPEN IT
  DESCRIPTION
  ===========================================================================
  /* GET THEFILENAME FROM THE COMMAND LINE
  DO SET      = %%FILE = %%$V2                                      GLOBAL  N
  DO
  /* INVOKE KOA CICSINQ (CEMT INQUIRY FILE ( ))
  DO KSL      = CICSINQ %%FILE
    WAITMODE   Y                                      TIMEOUT 9999    STOP Y
     INITPROC   CICST         SHARELOC Y               IMMEDIATE N
  DO
  /* IF NEEDED INVOKE KOA CICSOPEN (CEMT SET FILE( ) OPEN)
  IF       %%DSTATUS NE O
  DO KSL      = CICSOPEN %%FILE
     WAITMODE   Y                                      TIMEOUT 9999    STOP Y
     INITPROC   CICST         SHARELOC Y               IMMEDIATE N
FILL IN RULE DEFINITION. CMDS: EDIT, SCHED, OPT, SHPF                  07.55.22

Figure 5 Sample KOA Script (CICST) invoked by Control-O Rule Subparameter INITPROC to handle the Preset Environment

IFVAR `%A1’ EQ INIT  GOTO INIT
IFVAR `%A1’ EQ TERM  GOTO TERM
IFVAR `%A1’ EQ RESET GOTO RESET
GOTO EXIT
LABEL INIT
LOGON APPLID CICSTEST SESSID CICS
CLEAR
GOTO EXIT
LABEL RESET
CLEAR
GOTO EXIT
LABEL TERM
SCREENMODE NORECEIVE
TYPE `CESF LOGOFF’
ENTER
LOGOFF
GOTO EXIT
LABEL EXIT
RETURN

Figure 6 Sample KOA Script (CICSINQ) invoked by Control-O Rule to Check whether a Data Set is Open

TYPE `CEMT INQUIRY FILE( %A1 )’ENTER
SETVAR %STATUS SCREEN 3 22 1
SETOLOC %%DSTATUS = %STATUS
PF03
RETURN

Figure 7 Sample KOA Script (CICOPEN) invoked by Control-O Rule to Open a Closed Data Set

TYPE  `CEMT SET FILE( %A1 ) OPEN’
ENTER
PF03
RETURN
TYPE  `CEMT SET FILE( %A1 ) OPEN’
ENTER
PF03
RETURN

Execution of the DO KSL statements mentioned in the above rule depends on which type of server is used. Below is a step-by-step description of how these statements are executed for each type of server.

Table 27 Step-by-Step Description of DO KSL Statements in Sample Control-O Rule

Preset Environments and Batch JobsLink copied to clipboard

Before a KOA script designed for a preset environment can be executed, the preset environment must be defined. To achieve this, Control-O normally invokes the necessary scripts to preset the environment. When a KOA script designed for a preset environment is to be executed in batch, a controlling KOA script must be included to simulate Control-O actions. The controlling script invokes the scripts which create and maintain the preset environment.

The following job contains a controlling KOA script. It invokes the same scripts shown in the previous example.

Figure 8 Sample Job Containing a Controlling KOA Script

//JOB1    JOB ....
//STEP0001 EXEC IOARKOA,OUTDUMP=X
//DAKSLPRM DD *
*
  SETVAR %FIL DATA `FILE1’
  CALLMEM CICST INIT
  CALLMEM CICSINQ %FIL
  CALLMEM CICST RESET
  IFVAR %%DSTATUS EQ `O’ GOTO SKIPOPEN
  CALLMEM CICSOPEN %FIL
  CALLMEM CICST RESET
LABEL SKIPOPEN
  CALLMEM CICST TERM
  END
*
//

Updating KOA Scripts Requiring a Preset EnvironmentLink copied to clipboard

Servers executing DO KSL requests sequentially (that is, General and Special servers) load the KOA script the first time it is executed. When the same KOA script is again requested, the server does not reload the script, but instead uses the previously loaded version from memory.

If a KOA script is updated, it is necessary to restart the server so that it is forced to reload the scripts. A server can be restarted by the Server Status screen or by specifying operator command:

F CONTROLO,SERVER=name,TERM

The server terminates, and restarts automatically upon the next DO KSL request.

Testing a ScriptLink copied to clipboard

When testing a KOA script, it may be necessary to make changes. To avoid restarting a General or Special server after each change in the script:

Temporarily define the DO KSL statement with the IMMEDIATE subparameter set to Y. This causes an Immediate server to be created for each request.

Test scripts by submitting them in batch jobs (described earlier in this chapter).

KOA RecordingLink copied to clipboard

The KOA Recorder facility, which is available under IOA TSO and IOA cross memory, makes it easy to create KOA scripts. The KOA Recorder generates a script by automatically recording your keystrokes and saving the keystrokes in a file. This eliminates the need to write scripts manually and reduces the chance of error. You can edit the file as necessary.

Scripts generated by the KOA Recorder can be submitted in the same way as manually created scripts, that is, by using batch procedure IOARKOA.

Note: The KOA Recorder facility simulates a hardware terminal (SNA LUTYPE2) and supports terminal models 2, 3, 4 and 5, with or without extended data stream capabilities. Therefore, corresponding VTAM LOGMODEs should be used with the KOA Recorder. Ensure that the LU for a VTAM logmode attribute used in the recording session corresponds to the logmode of the recorded session. For more information about defining VTAM LUs and logmodes, refer to the INCONTROL for z/OS Administrator Guide.

To start the KOA Recorder, select Option OK, KOA RECORDER, on the IOA Primary Option menu. The IOA KOA Recorder screen, which is illustrated in Figure 9, is displayed.

KOA Recorder ScreenLink copied to clipboard

Figure 9 KOA Recorder Screen

-----------------------------  IOA KOA RECORDER  --------------------------(KR)
COMMAND ===>                                                                  
   
             SPECIFY THE FOLLOWING PARAMETERS:                                     
                                                                                   
        APPLICATION ===>                                                           
        LU NAME     ===>                                                           
        LOGON DATA  ===>                                                           
        SCRIPT FILE ===>                                                           
   
   
   










                                                                                   
 USE THE COMMAND SHPF TO SEE PFK ASSIGNMENT

To record a script, specify a value for each of the fields in Table 28.

Table 28 Fields of the KOA Recorder Screen

To begin the actual recording, press Enter. Both the recording and the VTAM application that you specified begin simultaneously.

When you quit your VTAM application (for example, in a TSO session, by typing LOGOFF at the TSO READY prompt), the KOA Recorder stops recording, and the KOA Recorder Screen reappears.

To leave the KOA Recorder screen, press PF03/PF15 (END).

Sample Output ScriptLink copied to clipboard

The following is an example of steps performed by a user while the KOA Recorder is in session. The KOA Recorder will record these steps as a script.

1. Display the Rule Definition Entry Panel.

2. Locate the DAILY table and select the DAILY rule.

3. Modify the DAILY rule so that MODE LOG is Y.

4. Exit the DAILY rule, exit the DAILY table, and save the updated rule.

5. Force the DAILY Rule table.

6. Display the Automation Log panel

7. Check that the DAILY rule was loaded and triggered.

8. Quit IOA.

9. Log off TSO and stop recording.

From these steps, the KOA Recorder generates the script shown in Figure 10.

Figure 10 Sample KOA Output Script

LOGON APPLID TSO      SESSID RCRD TERMINAL KSLT0001         TYPE 'N18A'         
ENTER   
TYPE 'N18     '     
ENTER   
TYPE 'OR       '    
ENTER   
TYPE 'CTOP.PROD.RULES  '        
ENTER   
TYPE 'L DAILY      '
ENTER   
TYPE 'S'
ENTER   
CURSOR NEWLINE      
TYPE 'S'
ENTER   
CURSOR POS 2  15    
TYPE 'F PROD        '
ENTER   
TYPE 'LROD'         
ENTER   
PF03    
PF03    
TYPE 'Y'
ENTER   
TYPE 'F'
ENTER   
TYPE 'Y'
ENTER   
TYPE '=OL           '
ENTER   
TYPE 'F DAILY       '
ENTER   
PF08    
TYPE '=X'
ENTER   
TYPE 'LOGOFF'       
ENTER   
END