Using KeyStroke Language (KSL)

The IOA standard KeyStroke Language (KSL) is a general purpose language that simulates, in batch, keystrokes that are entered in the IOA Online facility. KSL language statements (commands) are specified in programs called scripts.

• Activating KeyStroke Language Scripts

• Principles of KSL Operation

• Language Syntax

• Special considerations

The most common use of KSL scripts is to generate reports from the IOA Core and INCONTROL product repositories. Utilities are also frequently written in KSL scripts.

Once you are familiar with KSL, you can write your own scripts to create reports and utilities. Once a KSL script is defined it can be reused.

Note: Many of the functions performed using KSL can now be performed more easily and efficiently using CTMAPI and IOAAPI. For more information on CTMAPI refer to the Control-M for z/OS User Guide. For more information on IOAAPI refer to the INCONTROL for z/OS Administrator Guide. BMC recommends that you use CTMAPI and IOAAPI instead to KSL whenever possible.

Activating KeyStroke Language Scripts

The IOARKSL procedure activates KeyStroke Language scripts, either as a standard batch execution or as a started task.

KSL scripts can be activated at any time, even if the monitors are not active.

Standard batch execution example

//KSL      EXEC IOARKSL
//DAKSLPRM DD   *
 parameters
//

The following are the basic DD statements you can use with the IOARKSL procedure.

Started task example

S IOARKSL,PARM='scriptname script-parameters'

Return codes for the IOAKRKSL procedure

Principles of KSL Operation

KSL is composed of screen control commands and editing commands. Screen control commands correspond to operations of the terminal keys. Editing commands are required to edit the printed page.

At the beginning of a script, you are positioned in the on-line field of the IOA Primary Option menu. If the IOA entry panel is mandatory at your site, you are positioned at the entry panel and you should include commands that enter your user ID and password first.

The following is an example of a KSL script that prints the contents of a specific job scheduling definition is illustrated below:

TYPE '2'ENTER
TYPE 'DPTT.CTM.SCHEDULE'
CURSOR NEWLINE
TYPE 'APD'
CURSOR NEWLINE
TYPE 'APDP0020'
ENTER
PRINTSCREEN 3 23
END

This script produces a printout of the first screen of the job scheduling definition. The following explains each step of the above example.

Table 1 Step-by-Step Explanation of Script Example

A KSL script is a representation of your keystrokes while you are working with the Online facility. Everything that you can display on the screen, you can print. Every selection criterion that can be applied online can be applied in batch mode. The same language is used to work on the screen and on the output of the KSL script.

Modifying scripts

An important advantage of using KSL is that once a script is created, it can be stored in a member in a library. This enables requests to be submitted in batch mode as often as required (daily, weekly, monthly, and so on), and during off-peak hours not convenient for online requests.

The following example expands the previous script into a more general purpose script.

TYPE '2'ENTER
TYPE 'DPTT.CTM.SCHEDULE'
CURSOR NEWLINE
TYPE 'APD'
CURSOR NEWLINE
TYPE 'APDP0020'
ENTER
LABEL PRTSCR

*Define a label to which we can later branch from another command (GOTO).

PRINTSCREEN 3 23
CURSOR POS 23 2

*Position the cursor on the last line of the job’s data on the screen.

IFSCREEN ' ' GOTO ENDREPORT
IFSCREEN '======= >' GOTO ENDREPORT

*If the last line of data on the screen is either blank or the end-of-data message, do *not print any more job data.

CURSOR HOMECURSOR HOME

*Position the cursor on the Command field in the screen.

PF08

*Scroll down one more page.

GOTO PRTSCR

*Go to label PRTSCR and print the screen (loop again).

LABEL ENDREPORT
END

This script is easy to define, but filling in a different library, table name or job name each time you want to print a job scheduling definition is awkward.

It would be much easier if you could supply the library name, table name and job name at the time the script is executed.

Scripts can be defined with special variables (for example, %A1, %A2, described later in this chapter) instead of "hard-coded" values. When activating the script, the values for the special variables can be passed as parameters.

In the following example, special variable %A3 represents the job name, %A2 represents the table name, and %A1 represents the library name. Other features, such as a header for the report produced by this script, are also presented.

HEADERSIZE 5 BOTTOMSIZE 1
HEADERLINE 3 1 'SCHEDULE DEFINITION OF JOB'
HEADERLINE 3 28 '%A3'
HEADERLINE 3 38 'TABLE'
HEADERLINE 3 48 '%A2'
HEADERLINE 3 58 'LIBRARY'
HEADERLINE 3 68 '%A1'
HEADERLINE 4 1 '-------------------------'
HEADERLINE 5
TYPE '2'
ENTER
TYPE '%A1'
CURSOR BTAB
CURSOR NEWLINE
TYPE '%A2'
CURSOR BTAB
CURSOR NEWLINE
TYPE '%A3'
ENTER
LABEL PRTSCR
PRINTSCREEN 3 23
CURSOR POS 23 2
IFSCREEN ' ' GOTO ENDREPORT
IFSCREEN '======= >' GOTO ENDREPORT
CURSOR HOME
PF08
GOTO PRTSCR
LABEL ENDREPORT
PF03
PF03
PF03
RETURN

Assume that the above script is kept in the REPJOB member. You can produce a printout of two jobs from a scheduling library by the following request:

//KSL EXEC IOARKSL
 CALLMEM REPJOB DPTT.CTM.SCHEDULE APD APDP0020
 CALLMEM REPJOB DPTT.CTM.SCHEDULE APD APDP0035
 END

Language Syntax

• A command line is processed from column 1 to 72. A command cannot exceed column 72. Columns 73 to 80 are ignored.

• A command line can contain all blanks.

• A command line with * in column 1 is considered a remark.

• Each line in a script can optionally have one continuation line. To add a continuation line, place an asterisk (*) in column 72 of the initial line.

• A KSL variable must start with the character % and can be 2 through 40 characters long. A blank designates the end of the variable name.

• KSL variables are only accessible by the KSL script in which they are defined. Any reference to the same variable in another command member (or in another invocation of the same command member) is totally independent and has no effect on the current member environment.

• The value of an AutoEdit variable applies in all command members invoked by a KSL script.

• To share information between a KSL script and other command members invoked in the same KSL run, either store the information in local AutoEdit variables, or specify the relevant information using the CALL, CALLMEM, or EXEC command.

• Values for the variables %A1 through %A9 (arguments) cannot be set by the SETVAR command. They can only be specified as parameters of a CALLMEM command.

• Special variables %RC and %MSG are also valid during the same invocation of a command member. Therefore, if you use the SETVAR command to assign a value to the variable %RC and then execute RETURN, the value of the variable is lost.

• Special AutoEdit variables and functions must start with characters %%$. They are set using command SETOLOC and are resolved according to the same rules that apply to the IOA AutoEdit facility.

• When an expression contains both KSL and special AutoEdit variables and functions, the KSL variables are resolved first.

A label is valid through the same invocation of a command member. Any reference to the same label in another command member (or in another invocation of the same command member) is totally independent and has no effect on the current member environment.

• The IOA KSL and SAMPLE libraries contain general purpose command members that can be used to solve typical report functions (for example, scroll and print).

• BMC recommends that you active the TRACE ON command when performing an update function with the KeyStroke Language. It is also more convenient to write new reports with the TRACE ON.

• KSL scripts may not work in a customized environment. For this reason, it is highly recommended that you run KSL using backup libraries that specify the default values for the IOA environment.

Special considerations

Mixed case characters - The Control-M Active Environment screen (screen 3) supports mixed case (uppercase and lowercase) characters. KSL also supports mixed case characters for this screen, and product-supplied scripts have been updated accordingly.

If you are using a modified script, or a script that does not support mixed-case characters, BMC recommends that you change your KSL scripts to be mixed case compatible. As an alternative, you may change the format of the screen to uppercase only in the $$ACT member in the IOA MSG library, but changing the screen might affect the performance of other KSLs.

KSL and customized screens - The performance or the accuracy of the output produced by a KSL script may be affected if you have customized the IOA screens in certain ways.

For example, if you change the OWNER field in the Job Scheduling Definition screen (Screen 2), to a protected field (from its default status as an unprotected field), KSL REPCTRDF will no longer operate correctly.

KSL script authorization - If the script is to execute successfully, the user submitting a KSL script must be authorized to perform the Online functions performed by the script.