CLEAR

Equivalent to pressing the Clear key on the keyboard.

CURSOR

Depending on the parameters listed below, CURSOR moves the cursor to the

• BTAB — Beginning of the previous unprotected input field on the screen.
• HOME — First unprotected input field on the screen.
• NEWLINE — First unprotected input field that appears on the line following the current cursor position line.
• POS line-no col-no — Specific position on the screen. line- no and col-no can contain constants, or any valid expression consisting of KSL variables and/or AutoEdit variables.
• TAB — Beginning of the next unprotected input field on the screen.

ENTER

Equivalent to pressing the Enter key on the keyboard.

FIND{‘textstring’|expression}

Searches for text on the screen from the current position of the cursor. If the text is found, the cursor is positioned at the beginning of the text. For more information, see special variable %FINDRC, described in Table 6 in Special KSL Variables.

• textstring — A character string constant. When specifying constants, quotes are not necessary unless spaces are embedded in textstring. To specify a quote inside the text, use two consecutive single quotes.
• expression — Any expression consisting of constants, KSL variables, and/or AutoEdit variables.

PA01-PA03

Equivalent to pressing program attention keys on the keyboard.

PF01-PF24

Equivalent to pressing program function keys on the keyboard.

SCREENSIZE line-no col-no

Defines the logical terminal size.

Valid terminal sizes are:

• 24 lines x 80 columns (Default)
• 32 lines x 80 columns
• 43 lines x 80 columns
• 27 lines x 132 columns

TYPE{‘textstring’ | expression}

Operates the keyboard by "typing" the text on the screen from the current position of the cursor. If the text is too long for the current data field, an error message is produced and the script stops executing.

• textstring — A character string constant. When specifying a constant, the text must be enclosed in single quotes (‘’). To specify a quote inside the text, use two consecutive single quotes.
• expression — Any valid expression consisting of KSL variables and/or AutoEdit variables. The expression must be enclosed in single quotes (‘’).

CALL progname [argument1 argument2 ... argumentn]

Calls an external program (progname). The arguments are optional. A maximum of nine arguments can be passed. Use command CALL when the called program expects to receive a list of parameters. The parameters are passed in a format compatible with ASSEMBLER, COBOL and FORTRAN.

• progname — Name of the called program. progname can consist of a constant, or may contain any valid KSL and/or AutoEdit expression.
• argumentx — Any text (not containing blanks), constant, KSL variable, or AutoEdit variable to be sent to the called program. (The variable data can contain blanks.)

Note: The return code of the called program is stored in special variable %CALLRC, which is described in Table 6.

CALLMEM memname [argument1 argument2 ... argumentn]

Calls a predefined KSL script that is located in the member memname in the library allocated to the DACALL DD statement. The arguments are optional. A maximum of nine arguments can be passed.

Note: The return code of the called program is stored in special variable %CALLRC, which is described in Table 6.

END

Indicates the end of the KSL script. This is a mandatory command in the main script commands list. When activated at any level, the script is terminated.

EXEC progname [argument1 argument2 ... argumentn]

Calls an external program (progname). The arguments are optional. A maximum of nine arguments can be passed. Use command EXEC when the called program expects to receive an argument in a format similar to JCL’s EXEC PGM argument format. (All arguments are merged into a single argument.)

• progname — Name of the called program. progname can consist of a constant, or can contain any valid KSL and/or AutoEdit expression.
• arguments — Text to be passed to the called program. An argument can consist of any text (not containing blanks), a constant, or a KSL and/or AutoEdit variable. (The variable data can contain blanks.)

(Described later in this chapter).

Note: The return code of the called program is stored in variable %CALLRC, which is described in Table 6 in Variables.

GOTO label_name

Branches to the specified label name, which must be in the same command member.

The IFSCREEN command allows elements of the screen display to be used for flow control. If all parts of the conditional expression evaluate to true, script flow branches to the specified label name, which must be in the same command member. A parameter cannot be specified more than once within the same conditional expression.

Each part of the conditional expression is true if the:

• ‘textstring’ — Text on the screen at the current cursor position is equal to the specified text. The text must be enclosed in single quotes (‘’). To specify a quote inside the text, use two consecutive single quotes.
• ‘expression’ — Text on the screen at the current cursor position is equal to the specified expression. expression can be any expression consisting of KSL variables and/or AutoEdit variables. expression must be enclosed in single quotes.
• COLOR col — Color of the screen at the current cursor position is equal to the specified color (col). Valid col values are:

  — WHITE

  — GREEN

  — RED

  — BLUE

  — PINK

  — YELLOW

  — TURQUOISE

  — NOCOLOR

IFSCREEN

(continued)

• ATTR attr — Screen attribute at the current cursor position is equal to the specified attribute (attr). Valid attr values are:

  — U — Unprotected

  — P — Protected

  — L — Low

  — H — High

  — D — Dark

  — N — Numeric

  — S — Skipped

  — UL — Unprotected and low

  — UH — Unprotected and high

  — UD — Unprotected and dark

  — NL — Numeric and low

  — NH — Numeric and high

  — ND — Numeric and dark

  — PL — Protected and low

  — PH — Protected and high

  — PD — Protected and dark

  — SPL — Skipped, protected and low

  — SPH — Skipped, protected and high

  — SPD — Skipped, protected and dark

• HILITE hilite — Highlight of the screen at the current cursor position is equal to the hilite value specified. Valid hilite values are:

  — REVERSE — Reverse video

  — USCORE — Underline

  — BLINK — Blink

  — NONE — No highlight

• BEEP— Terminal beep

IFVAR operand operator operand GOTO labname

Where:

• operand is a KSL variable or constant and/or AutoEdit variable. Constants must be enclosed in single quotes.
• operator is one of the following operators. Used to compare the specified operands.

  EQ — is equal to
  NE — is not equal to
  GT — is greater than
  GE — is greater than or equal to
  LT — is less than
  LE — is less than or equal to

• labname—Label name to which script branches. Specified using command LABEL (described below).

Note: Operands are compared as character strings from left to right. For example, 91 is greater than 1000, because 9 is greater than 1.

IFVAR is used together with command GOTO to permit branching based on different runtime conditions. If the condition is true, flow branches to the specified label name (must be in the same command member).

LABEL name

Defines a label to which script flow can branch.

MAXCOMMAND number

number is the maximum number of commands that can be executed in the script. Default: 400. This is designed to prevent an accidental loop.

PAUSE n

Where n= hundredths of seconds. Causes the script to "wait" the specified amount of time.

RETURN [return-code]

Returns to the calling script.

return-code must be a number from 0 through 4095. When command RETURN is activated, control is passed to the command after the CALLMEM command in the calling member. The variable %CALLRC in the calling member is set to the value of the return code. Default: 0.

BOTTOMLINE line-no pos-in-line {‘textstring’|varname}

Assigns contents to a line in the page footer. The footer contents are valid throughout the script until overridden by another BOTTOMLINE command for the same line in overlapping positions. Command BOTTOMSIZE overrides the current BOTTOMLINE specifications.

• line-no is the relative number of the line in the footer.
• pos-in-line is the relative position in the line in the footer.
• ‘textstring’ must be enclosed in single quotes (‘’). To specify a quote inside the text, use two consecutive single quotes.
• varname is a valid KSL variable.

BOTTOMSIZE line-no

Specifies the number of lines in the report bottom (footer) (1 minimum – 15 maximum). The bottom size is valid throughout the script until a new BOTTOMSIZE command is activated.

HEADERLINE line-no pos-in-line {‘textstring’|varname}

Assigns contents to a line in the page header. The header contents are valid throughout the script until overridden by another HEADERLINE command for the same line in overlapping positions. Command HEADERSIZE overrides the current HEADERLINE specifications.

• line-no is the relative number of the line in the header.
• pos-in-line is the relative position in the line in the header.
• ‘textstring’ must be enclosed in single quotes (‘’). To specify a quote inside text, use two consecutive single quotes.
• varname is a valid KSL variable.

HEADERSIZE line-no

Specifies the number of lines in the report header (1 minimum – 15 maximum). The header size is valid throughout the script until a new HEADERSIZE command is activated.

PAGESIZE line-no col-no

Defines the maximum size of a printed page.

• line-no is the number of lines in the page. Default: 60.
• col-no is the column number. In the current version, the column number must be 132.

PRINTLINE line-no

Prints the contents of the line identified by line-no (a number from 1 through 9999).

PRINTNEWPAGE

Skips to a new page.

Each occurrence of command PRINTNEWPAGE in a KSL script must be preceded by commands SCREENSIZE, PAGESIZE, HEADERSIZE and BOTTOMSIZE.

PRINTSCREEN from-line until-line

Prints the screen contents of the specified line range.

• from-line — The first line of screen contents to be printed.
• until-line — The last line of screen contents to be printed.

SETLINE identifier pos-in-line font {‘textstring’|varname}

Assigns contents to a line that is about to be printed.

• identifier is the number (from 1 through 9999) that identifies a line.
• pos-in-line is the number that identifies a position in the line.
• ‘textstring’ must be enclosed in single quotes (‘’). To specify a quote inside the text, use two consecutive single quotes.
• varname is a valid KSL variable.

TRACE {ON|OFF}

Simplifies problem resolution using the TRACE (debug) facility while defining a script.

• ON — Produces a complete printed output of every command execution, screen I/O, and command member invocation. It is highly recommended that KSL utilities that are performing updates of any database operate with TRACE ON to simplify problem resolution. Command TRACE can be activated any number of times within a script to turn on/off the TRACE facility.
• OFF — Does not produce a printed output. Default.

ALLOC DD ddname DS dsname[MEM memname][{SHR|OLD|MOD}]

Dynamically allocates the data set dsname to the specified DD name.

• memname – Member name for PDS members. Mandatory for PDS members. Must be left blank for non-PDS members. memname can be any valid member name consisting of a constant, KSL variable, or AutoEdit variable.
• ddname – Any DD name consisting of a constant, KSL variable, or AutoEdit variable.
• dsname – Any data set name consisting of a constant or KSL variable.
• SHR, OLD, MOD – Specify the data set disposition. Optional. Default is SHR.

Before a data set can be accessed (for example, with OPENFILE, GETFILE), it must be allocated and assigned a DD name. Similarly, when the data set no longer needs to be accessed, the data set and DD name must be released (for more information, see command FREE in this table). This DD name is local to the script that creates it.

CLOSEFILE ddname

Closes sequential data set ddname.

ddname is any DD name consisting of a constant, KSL variable, or AutoEdit variable.

FREE DD ddname

Dynamically frees the data set allocated to the specified DD name. (The DD name is assigned by command ALLOC.) Activate this command when a data set no longer needs to be accessed by the script.

GETFILE ddname INTO varname

Stores in the specified variable the contents of the next record in the sequential file referenced by ddname, where

• ddname is any DD name consisting of a constant, KSL variable, or AutoEdit variable.
• varname is a KSL variable name where contents are stored.

The OPENFILE command opens sequential data set ddname for access.

• ddname is any DD name consisting of a constant, KSL variable, or AutoEdit variable.
• INPUT opens the sequential data set as a read-only file. No changes can be made to the file.
• OUTPUT allows data to be written to the file (write access).
• UPDATE allows the file to be read and modified (read and write access). Default.
• ENDFILE label specifies a label name to which script processing flow branches when the end of sequential data set ddname is reached. ENDFILE is mandatory when ddname is opened for INPUT or UPDATE access.

PUTFILE ddname FROM varname

Writes the contents of variable varname in the next record of the sequential file referenced by ddname.

• ddname is any DD name consisting of a constant, KSL variable, and/or AutoEdit variables.
• varname specifies a KSL variable whose contents are written.

Note: AutoEdit variables (that is, variables beginning %%) cannot be used with a PUTFILE command. Instead, such a variable must be passed to a KSL variable (that is, a variable beginning with a single %). The KSL variable must be specified in the PUTFILE command.

Assigns the appropriate value to the variable name. The SETOGLB command is used to create (set) a global AutoEdit variable. expression can contain a KSL variable.

Note: This command is only available if Control-O is installed at your site. Global AutoEdit variables can only be used when the Control-O monitor is online. For further information, see the DO SET statement in the Control-O User Guide.

Assigns the value of the expression to the variable name. The SETOLOC command is used to create (set) a Local AutoEdit variable. expression can contain a KSL variable.

SETVAR varname CURSOR length

Assigns extracted text to variable varname. This command is used to create (set) variables.

• varname is the name of the KSL variable in which the text is stored.
• length is the length (in characters) of the extracted text. The text at the current cursor position of the specified length is extracted and assigned to the variable name.

SETVAR varname DATA{‘textstring’|expression}

Assigns a text string to variable varname. This command is used to create (set) variables.

• varname is the name of the KSL variable in which the text is stored.
• ‘textstring’ is the textstring assigned to the variable name. textstring is a character string constant. When specifying a constant, the text must be enclosed in single quotes (‘’). To specify a quote in the text, type two consecutive single quotes.
• expression is any valid expression containing KSL variables and/or AutoEdit symbols. expression must be enclosed in single quotes if it contains embedded blanks.

SETVAR varname SCREEN from-line from-col length

Assigns extracted text to variable varname. This command is used to create (set) variables.

• varname is the name of KSL variable in which the text is stored.

Variable value is determined by the screen contents at a specific screen position. The screen position is specified by:

• from-line – Starting from this line position, screen contents are extracted.
• from-col – Starting from this column position, screen contents are extracted.
• length – The number of characters) in the extracted text.

SHOUT TO destination [URG urgency] TEXT {textstring|expression}

Sends ("shouts") textstring to the specified destination.

• destination – a 1 through 16 character destination. For valid destination values, refer to the description of the SHOUT parameter in the Control-M for z/OS User Guide.