AutoEdit Facility in KSL

The AutoEdit facility provides additional data manipulation capabilities. It is composed of the following types of AutoEdit symbols and instructions:

• AutoEdit Variables

  • System Variables

  • AutoEdit System Variables

  • User-Defined Variables

  • Rules of Variable Substitution

• AutoEdit Operators

• AutoEdit Functions

  • %%$CALCDATE Function

  • %%$SUBSTR Function

  • %%$TIMEINT Function

  • %%$PARSE Function

AutoEdit Variables

• System Variables

• AutoEdit System Variables

• User-Defined Variables

• Rules of Variable Substitution

System Variables

System variables are predefined, commonly used variables whose values are automatically updated and maintained by the AutoEdit facility.

The System variable format is:

%%$var

where var represents the name of the System variable.

Each AutoEdit variable begins with "%%". Each variable resolves to (is replaced by) the corresponding system value. AutoEdit System variables are described on the following pages.

TYPE '%%$DATE'

TYPE '011010'

AutoEdit System Variables

Table 30 AutoEdit System Variables

User-Defined Variables

The user-defined variables capability is designed to provide additional flexibility. You can define your own symbols using the KSL command SETOLOC and use them in other KSL commands. They are automatically resolved when the KSL is executed.

A user-defined variable can be any alphanumeric string starting with %%. The characters @ # $ _ are also valid. Lowercase characters are resolved, but upon resolution they remain lowercase and are not translated to uppercase characters.

When the AutoEdit facility identifies a string that starts with %%, the string is assumed to be an AutoEdit variable or instruction. If the string is a reserved AutoEdit symbol or a System variable, it is interpreted as such. Otherwise the string is assumed to be a user-defined variable.

Rules of Variable Substitution

A KSL command can contain expressions including both KSL and AutoEdit variables. Variable substitution is performed in the following order:

1. All KSL variables (variables preceded by a single % character) are substituted sequentially from left to right.

TYPE '%A %%$PLUS 1'

Assuming that the value of %A is 1, variable substitution begins with the KSL variable substituted as follows:

TYPE '1 %%$PLUS 1'

2. If the resulting expression contains AutoEdit symbols (in this example, %%$PLUS), variables are substituted sequentially from right to left until the symbol is assigned a value.

In the above example, TYPE ‘1 %%$PLUS 1’ resolves to TYPE ‘2’.

3. The largest number that can be handled by mathematical AutoEdit operations is 231 - 1, that is, 2147483647.

Examples

The following are additional examples of AutoEdit variable substitution.

AutoEdit Operators

AutoEdit operators can be used in conjunction with AutoEdit symbols. Valid AutoEdit operators are:

Table 31 AutoEdit Operators

The format for use of AutoEdit symbols and operators is:

operand operator operand

Only one operator can be used in an expression.

Operands must resolve into positive numeric constants. The final result is translated into a character string. For example:

SETOLOC %%x = %%x %%$PLUS 1

User-defined variable %%x is incremented by one.

AutoEdit Functions

• %%$CALCDATE Function

• %%$SUBSTR Function

• %%$TIMEINT Function

• %%$PARSE Function

%%$CALCDATE Function

The %%$CALCDATE function performs date calculations based on a specified date. Format:

%%$CALCDATE date ± quantity

where:

• date is the date in yymmdd format.

• quantity is the number (or numeric AutoEdit expression) of days to add to or subtract from the date (from 1 to 366).

Note: %%$CALCDATE operates on Gregorian dates only; Julian dates, such as %%JULDAY, cannot be specified.

%%$SUBSTR Function

The %%$SUBSTR function extracts a substring from the input string, and returns the attached substring. Format:

%%$SUBSTR strng startpos len

where:

• strng is the input string from which the substring is extracted.

• startpos is the first character of the input string to extract.

• len is the number of characters to extract.

startpos and len must be numbers (or numeric AutoEdit expressions) and greater than zero.

If (startpos + len – 1) is greater than the strng length, the function is not executed and the value returned is null.

%%$TIMEINT Function

The %%$TIMEINT function calculates the time interval between two given times, specified in any order.

Format:

%%$TIMEINT time1 time2

time1 and time2 are constants or variables in yydddhhmmss format

where:

• yy is a 2-digit year

• ddd is a Julian day

• hh is the number of hours

• mm is the number of minutes

• ss is the number of seconds

The resulting time interval is in format:

• ddddd is the number of days

• hh is the number of hours

• mm is the number of minutes

• ss is the number of seconds

%%$PARSE Function

The %%$PARSE function is a powerful tool that offers extensive string manipulation capabilities in the AutoEdit environment. This function, which is similar to the REXX PARSE command in the TSO/E environment, can be used to analyze and extract information from various AutoEdit strings.

Overview of %%$PARSE

The %%$PARSE function parses a specified string (that is, it splits the specified string into substrings) according to a specified template. A template consists of variables and "patterns" that determine the parsing process.

The format of the %%$PARSE function is

DO SET=%%$PARSE string template

In this format

• string is the AutoEdit variable that contains the string to be parsed

• template is the AutoEdit variable or constant that contains the template

DO SET=%%S=THIS IS A SAMPLE STRING
DO SET=%%T=A1 A2 A3 A4 A5
DO SET=%%$PARSE %%S %%T

The %%$PARSE function assigns substrings of the specified string to the specified variables according to the specified template.

The DO SET statements in the above example provide the same result as the following DO SET statements:

DO SET=%%A1=THIS
DO SET=%%A2=IS
DO SET=%%A3=A
DO SET=%%A4=SAMPLE
DO SET=%%A5=STRING

The parsing process involves the following stages:

1. The string is broken into substrings, from left to right, using the patterns in the template.

2. Each substring is parsed into words, from left to right, using the variable names in the template.

   Template elements are

   • String Patterns

   • Position Patterns

   • Variables

   • Place holders (Dummy variables)

   The rules of parsing are detailed in the following paragraphs.

Parsing Words

Scanning is performed from left to right and words in the string (leading and trailing blanks excluded) are matched one by one with the variables named in the template. The last variable named in the template will contain the remaining part of the string, including leading and trailing blanks.

Up to 30 variable names can be specified in a parsing template.

The following situations can be encountered:

• The number of words in the string matches the number of variables in the template.
  Each of those variables contains one word of the string. The last variable contains the last word in the string including leading and trailing blanks.

• The number of words in the string is smaller than the number of variables named in the template
  The first variables each contain one word of the string and the extra variables receive a value of NULL (a string of 0 character length).

• The number of words in the string is greater than the number of variables in the template
  All variables but the last one contain one word of the string and the last variable named in the template contains the remaining part of the string, including leading and trailing blanks.

DO SET=%%S = THIS IS A SAMPLE STRING
DO SET=%%T = A1 A2 A3
DO SET=%%$PARSE %%S %%T

DO SET=%%A1 = THIS IS A SAMPLE STRING
DO SET=%%A2 = IS
DO SET=%%A3 = A SAMPLE STRING

Using Dummy Variables (Place Holders)

A single period can be used as a dummy variable in the template. This is useful when the corresponding word in the string does not need to be stored in a named variable.

DO SET=%%S = THIS IS A SAMPLE STRING
DO SET=%%T = . . . A4.
DO SET=%%$PARSE %%S %%T

DO SET=%%A4 = SAMPLE

Using Patterns in Parsing

Patterns can be included in the template. Their purpose is to break down the string into substrings prior to the actual parsing into words process. Parsing will then be performed, as previously described, on the substrings and not on the original string.

Two types of patterns are available:

• String Patterns - a character string delimited by quotes, to distinguish it from a variable name

• Numeric (Positional) Patterns - a number, signed or unsigned

Using String Patterns

The string is scanned from left to right for a substring that matches the string pattern.

The following situations may occur:

• A match is found, that is, a substring within the string is identical to the given string pattern.

  The original string is divided into two substrings. The first substring (up to, but not including, the string pattern) is parsed into words using the variables named before the string pattern on the template. Parsing continues from the character following the matched string.

  Example 1

  Copy

  DO SET=%%S= THIS IS A SAMPLE STRING
  DO SET=%%T= A1 A2 'SAMPLE' A3 A4 A5
  DO SET=%%$PARSE %%S %%T

  A match is found since the string SAMPLE is part of the original string.

  The %%$PARSRC System variThe original string is divided into two substrings while the matched part of the string is excluded. Parsing of the first substring will use the variables listed before the match on the template while parsing of the second substring will use the variables listed after the match:

  • First substring: THIS IS A

    As a result of parsing

    Copy

    A1=THIS
    A2=IS A

  • Second substring: STRING

    As a result of parsing:

    Copy

    A3=STRING
    A4=NULL
    A5=NULL

  • A match is not found. There is no substring identical to the given string pattern within the string.

    It is assumed that a match is found at the end of the string. The first substring consists of the entire string and it is parsed using only the variables named before the string pattern on the template. Parsing continues from the character following the matched string (the end of the string, in this case).

DO SET=%%S = THIS IS A SAMPLE STRING
DO SET=%%T = A1 A2 A3 'EASY' A4 A5
DO SET=%%$PARSE %%S %%T

Using Numeric Patterns within the Template

Numeric patterns are numbers that mark positions in the string. They are used to break the original string into substrings at the position indicated by the number.

The position specified can be absolute or relative:

• An absolute position is specified by an unsigned number.

• A relative position is specified by a signed number (positive or negative) and its purpose it to determine a new position within the string, relative to the last position.

• The last position is one of the following:

  • the start of the string (position1), if the last position was not specified previously

  • the starting position of a string pattern if a match was found

  • the position of the end of the string, if the string pattern was not matched

  • the last position specified by a numeric pattern

• If the specified position exceeds the length of the string, the numeric pattern is adjusted to the end of the string. Similarly, if the specified position precedes the beginning of the string (negative or zero numeric pattern), then the beginning of the string is used as last position.

DO SET=%%S =THIS IS A SAMPLE STRING
DO SET=%%T = A1 A2 11 A3 A4 A5
DO SET=%%$PARSE %%S %%T

DO SET=%%S =THIS IS A SAMPLE STRING
DO SET=%%T = A1 A2 +10 A3 A4 A5
DO SET=%%$PARSE %%S %%T

Using More Than One Pattern and Combining Pattern Types in the Template

Both types of patterns (string and numeric) can be combined in the same template. Up to 30 patterns and up to 30 variable names can be specified.

Scanning of the string proceeds from beginning of the string until the first pattern (if any).

1. String pattern - A match was found

   The substring that precedes the match to the pattern is parsed using the variables named in the template before the pattern, with the last variable receiving the end of the substring, including leading and trailing blanks.

2. String pattern - A match was not found

   Since no match was found in the string, it is assumed that a match is found at the end of the string. The whole string is parsed using only the variables named in the template before the pattern.

   Numeric pattern (absolute)

   • The absolute numeric pattern points to a position within the string when the beginning of the string is position1.

   • The string is divided into two substrings.

     • The first substring extends from the beginning of the string and up to, but not including, the position that corresponds to the numeric pattern and it is parsed using the variables named in the template before the pattern.

     • If the absolute numeric pattern specifies a position beyond the length of the string, it is readjusted to the first position beyond the length of the string and the entire string is parsed using the variables named in the template before the pattern.

4. Relative numeric pattern

   The relative numeric pattern (a signed number) specifies a position within the string, relative to the last position.

4. Last position

   It is the beginning of the string when the relative numeric pattern is the first pattern in the template.

   • If the relative numeric pattern is not the first pattern in the template and the previous pattern was numeric, the last position is that specified by the previous numeric pattern.

   • If the relative numeric pattern is not the first pattern in the template and the previous pattern was a string, the last position is that of the starting character of the match (if there was a match) or the position following the end of the string (if there was no match).

     As a result of what was just explained:

     • If a pattern was not matched until the end of the string and the following pattern is a string pattern, this new string pattern is ignored since the starting point for the new scan is the end of the string.

     • If a pattern was not matched until the end of the string and the following pattern is a numeric pattern, then the scan and subsequent parsing will resume from the new position indicated by that numeric pattern.

DO SET=%%S = THIS IS A SAMPLE STRING
DO SET=%%T = A1 A2 11 A3 6 A4
DO SET=%%$PARSE %%S %%T

DO SET=%%A1 = THIS
DO SET=%%A2 = IS A
DO SET=%%A3 = SAMPLE STRING
DO SET=%%A4 = IS A SAMPLE STRING

DO SET=%%S = THIS IS A SAMPLE STRING
DO SET=%%T = A1 6 A2 +3 A3
DO SET=%%$PARSE %%S %%T

DO SET=%%T = A1 A2 +40 A3 -13 A4 A5
DO SET=%%S = THIS IS A SAMPLE STRING
DO SET=%%$PARSE %%S %%T

DO SET=%%A1 = THIS
DO SET=%%A2 = IS A SAMPLE STRING
DO SET=%%A3 = %%NULL
DO SET=%%A4 = SAMPLE
DO SET=%%A5 = STRING

DO SET=%%S = THIS IS A SAMPLE STRING
DO SET=%%T = A1 'A' A2 +3 A3
DO SET=%%$PARSE %%S %%T

DO SET=%%A1 = THIS IS
DO SET=%%A2 = A S
DO SET=%%A3 = AMPLE STRING