KSL commands and variables

Equivalent to pressing the Clear key on the keyboard.

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.

Equivalent to pressing the Enter key on the keyboard.

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.

Equivalent to pressing program attention keys on the keyboard.

Equivalent to pressing program function keys on the keyboard.

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

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 on page 38.

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.

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.

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).

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

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

• 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

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).

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).

Defines a label to which script flow can branch.

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

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

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.

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.

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.

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.

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.

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

Skips to a new page.

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

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.

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.

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 DDname 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.

Closes sequential data set ddname.

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

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.

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

• ddname is any DDname consisting of a constant, KSL variable, or AutoEdit variable.

• varname is a KSL variable name where contents are stored.

Opens sequential data set ddname for access.

• ddname is any DDname 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.

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

• ddname is any DDname consisting of a constant, KSL variable, and/or AutoEdit variables.

• varname specifies a KSL variable whose contents are written.

  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. This command is used to create (set) a global AutoEdit variable. expression may contain a KSL variable.

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

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.

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.

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.

Passes the specified arguments to a called script. The number corresponds to the position of the argument in command CALLMEM. The argument is replaced throughout the called script member at invocation time.

Contains the return code specified in the RETURN command when returning from command CALLMEM. Also contains the return code from programs called by the CALL or EXEC commands.

Provides the return code of the result of the last FIND. If the last FIND was successful, has a value of 0. If the last FIND was unsuccessful, %FINDRC has a value of 4.

Specifies text assigned at script termination, which appears as a message in the job’s SYSLOG and the script execution listing. Only the value of variable %MSG at the script member issuing command END is displayed.

Supplies the return code of the script. The value at successful script termination is the condition code of the step. Valid values are: 0 through 4095.

Current column position of the cursor.