Principles of KOA Operation

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.

Example 1

The following KOA script logs on to CICS and prints all open data sets.

Figure 2 KOA Script – Example 1

LOGON APPLID CICSP SESSID CICP

LABEL 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

A detailed explanation of each step in the above sample script is shown below:

Table 7 KOA Script – Example 1 Explanation

Step	Description
LOGON APPLID CICSP SESSID CICP	Issue a command to log on to application CICSP, assigning session name CICP to this session.
LABEL CHECK	Specify label CHECK for script flow branching purposes. This reference point marks the portion of the script that checks if the logon to CICS is successful.
CURSOR POS 1 15	Position the screen cursor at row 1, column 15. If the logon was successful, CICS’s welcome message is displayed at this screen position.
IFSCREEN ‘WELCOME TO CICS/MVS’ GOTO CONTINUE	Determine if the CICS/MVS welcome message is currently displayed. If displayed, proceed to label CONTINUE. If not, proceed to the next script command.
GETSCREEN	Receive (accept) any available messages. This is a test to see if the CICS welcome message has been sent.
GOTO CHECK	Proceed to label CHECK to continue testing for the CICS welcome message.
LABEL CONTINUE	Specify label CONTINUE for script branching purposes. Script flow continues here when the logon to CICS is successful.
CLEAR	Clear the screen.
TYPE ‘CEMT INQUIRE DATASET(*) OPEN’	Type the specified command at the keyboard. This command displays all open data sets.
ENTER	Send the screen to CICS, and in response, receive the CEMT screen back from CICS.
PRINTSCREEN 1 24	Print the contents of the screen from line 1 through line 24.
PF03	Equivalent to pressing the PF03 key, which deactivates the CEMT command.
CLEAR	Clear the screen.
TYPE ‘CSSF LOGOFF’	Issue CICS’s logoff command.
ENTER	Equivalent to pressing Enter on the terminal keyboard. You have now logged off from CICS.
LOGOFF	Issue KOA’s logoff command.
END	Terminate the script.

As you can see, the KOA script is actually a representation of the keystrokes that are entered while working with a VTAM application. Everything that can be seen on the screen can be printed; and any keystroke that can be performed on a terminal can be performed by KOA.

Example 2

The following KOA script is activated by Control-O when a console message indicates that a production job that needs exclusive access is waiting for a reserved data set. The script looks for all users (TSO users and jobs) currently using the data set. If a TSO user is found, a message is sent to the user. Otherwise, a message is sent to the production manager.

Assume that the rule that activates this script passes two arguments to the script:

Table 8 KOA Script – Example 2 Explanation

Step	Description
%A1	Data set needed by a production job (%A2), currently reserved by other users and jobs.
%A2	Job which needs exclusive access to a data set (%A1).
ON SCREENERROR GOTO END	If an exception occurs at any time during script execution, proceed to label END, which terminates the script.
LOGON APPLID OMEGAMON SESSID OM	Log on to application OMEGAMON, assigning session name OM to this session.
ENTER	Equivalent to pressing Enter on the keyboard. In this situation, Enter bypasses the OMEGAMON opening screen.
CURSOR POS 1 2	Position the cursor on the screen.
TYPE ‘ZOPTEA’	Type OMEGAMON command ZOPTEA, which lists display options on the screen.
ENTER	Send the screen to OMEGAMON, and in response, receive a screen from OMEGAMON.
CURSOR POS 14 24	Position the cursor.
TYPE ‘CSR’	Type OMEGAMON command CSR to change the scroll amount from page to cursor. Changing the scroll amount to CSR allows the script to scroll from a specific cursor position, instead of screen by screen.
ENTER	Equivalent to pressing Enter on the keyboard, thus sending the new scroll amount.
CURSOR POS 2 1	Position the cursor.
TYPE ‘LOC %A1’	Type OMEGAMON command LOC, which locates data set %A1 and lists the users and jobs which are currently accessing that data set (in either Shared or Exclusive mode).
ENTER	Send the previous command, to display the user list.
CURSOR POS 3 1	Position the cursor.
IFSCREEN ‘+’ GOTO END	If the value at the cursor position is +, this indicates that message: + DSNAME _____ NOT CURRENTLY ALLOCATED is displayed. In this situation, the data set is available, and the script should proceed to label END. If the data set is allocated (the message is not displayed), proceed to the next script command.
CURSOR POS 4 1	Position the cursor.
PF08	Equivalent to pressing PFKey PF08 on the keyboard. Pressing PF08 when scroll amount CSR is specified shifts the list of users up, so that the current cursor line is displayed at the top of the screen.
LABEL LOOP	Specify label LOOP to mark the portion of the script that determines if any more data set users exist.
CURSOR POS 2 1	Position the cursor.
SETVAR %START_OF_LINE CURSOR 1	Save the current screen contents (one character in length) to KOA variable %START_OF_LINE. Note that if a user exists, it is preceded by the symbol > on the screen.
IFVAR %START_OF_LINE NE ‘>’ GOTO END	If the value of variable %START_OF_LINE is not equal to >, indicating that no more users are accessing the data set, proceed to label END (because there are no more users to notify). If %START_OF_LINE is equal to >, messages must be sent to the appropriate users.
LABEL TSO-USER	Specify label TSO-USER. This chapter of the script determines if the user of the data set is a TSO user.
SETVAR %TYPE SCREEN 2 26 3	Store screen contents (of the specified position) in KOA variable %TYPE. If the user is a TSO user, the current screen contents contain TSO.
IFVAR %TYPE NE `TSO’ GOTO BAT-JOB	If the value of variable %TYPE indicates that the user is not a TSO user, proceed to label BAT-JOB. If this user is a TSO user, proceed to the next script command.
SETVAR %USERNAME SCREEN 2 39 8	Store the TSO user name in KOA variable %USERNAME.
SHOUT TO TSO-%USERNAME MESSAGE ‘PLEASE FREE FILE %A1 IMMEDIATELY’	Send a message (using the Shout facility) to the TSO user %USERNAME. This message asks the user to free data set %A1 immediately.
SHOUT TO TSO-%USERNAME MESSAGE ‘PRODUCTION JOB %A2 IS WAITING FOR IT.’	Inform TSO user %USERNAME that %A1 must be freed so job %A2 can access the data set.
GOTO CONTINUE	Proceed to label CONTINUE.
LABEL BAT-JOB	Specify label BAT-JOB to mark the portion of the script that sends messages to the production manager if the user currently accessing the data set is a batch job.
SETVAR %TYPE SCREEN 2 26 3	Save the user type in variable %TYPE.
IFVAR %TYPE NE ‘BAT’ GOTO CONTINUE	If the user is not a batch job, proceed to label CONTINUE. If the user is a batch job, process the following script commands.
SETVAR %JOBNAME SCREEN 2 39 8	Save the batch job name in variable %JOBNAME.
SHOUT TO U-PRODMNGR MESSAGE ‘CTO -PRODUCTION JOB %A2 WAITING FOR FILES’	Send (shout) a message to U-PRODMNGR, informing that job %A2 is waiting for data set access.
SHOUT TO U-PRODMNGR MESSAGE ‘CTO -FILE %A1 IS HELD BY JOB %JOBNAME’	Inform U-PRODMNGR (through the Shout facility) that data set %A1 is accessed by job %JOBNAME.
LABEL CONTINUE	Specify label CONTINUE to mark the portion of the script that repositions the cursor to the next user in the user list.
CURSOR POS 3 1	Position the cursor.
PF08	Redisplay the user list starting with the next line.
GOTO LOOP	Proceed to label LOOP to process other users holding the data set.
LABEL END	Specify label END as a reference, marking the end of the script.
LOGOFF	Disconnect from VTAM application OMEGAMON.
END	Terminate the script.

Because this script uses parameters (%A1 and %A2) instead of literal data set and job names, the script is easy to invoke—just specify the appropriate information each time the script is activated from within a rule.

Parent Topic

KOA Language Overview