Language constructs - syncsort_simulate_2000 - Latest

Quoted Strings

If a literal begins with a double quote (“) or single quote (‘), the literal is considered a quoted string. The initial quote defines the type of quote that will terminate the quoted string. Quoted strings must be completed on the same 80-byte control card. However, quoted strings can be chained to produce longer literal strings.

The following conditions list the uses for quoted strings:

• a literal that contains one or more blanks
• a literal that requires the use of wildcard characters (* or ?), but the pattern matching functions must be ignored
• a literal that requires the use of one of the quoted string characters
• a literal that must start with an ampersand character (&) —
  Note: IF expressions only.

The following example uses a quoted string to evaluate the programmer name field from the job card. Since the symbolic field must be checked for the character string RM5 HOUSTON, and the literal contains blanks, a quoted string is required.

IF &PGMRNAME = "RM5 HOUSTON"

If the literal requires more information than will fit on a single control card, the quoted strings can be chained. The following example can be used to produce a long message. To continue the message, add a plus (+) sign after the end of one quoted string, and start another quoted string on the next control card.

DEFMSG ACCMSG01
'THIS IS A VERY LONG MESSAGE ' +
'THAT CAN ONLY BE HANDLED BY ' + 'MULTIPLE TEXT ENTRIES'

Literals that do not use quoted strings can contain wildcard characters: the asterisk (*) and question mark (?). These characters enable rules processing to perform pattern matching.

The asterisk (*) stands for any sequence of characters. When evaluating the following expression, any job name that starts with the character string DON will match.

IF &JOBNAME = DON*

The question mark (?) stands for any single character in the position. When evaluating the following expression, any job name that starts with the character string DON, and has exactly two additional characters, will match.

IF &JOBNAME = DON??

Enclosing a literal between two asterisks (*) can be used to request a contains function. During installation and verification, the sample rule definition uses the following expression to intercept only data set names that contain the character string SCCIVP.

IF &DSNAME = *SCCIVP*

Symbolic Fields

Expressions, messages, operator commands and SMF records can use symbolic fields. Symbolic fields usually start with the ampersand (&) character, the only exception being an expression. Since the left side of an expression only allows a symbolic field, the ampersand (&) character is optional.

A symbolic field represents an associated data field. The tables found in the “SYMBOLIC FIELDS” chapter in each product manual can be used to obtain the information about the available symbolic field names.

When evaluating an expression, symbolic substitution will be performed before evaluating the expression. This facility allows symbolic fields to be placed on both sides of the relational operator. In the following example, the OWNERID for a VSAM file will be compared with the current job name.

IF &OWNER NE &JOBNAME

The DEFMSG, DEFCMD, and DEFSMF statements can use symbolic fields to customize messages, commands and SMF records. For example, the following message will perform symbolic substitution for the current job name.

DEFMSG WRNMSG01 "** WARNING ** &JOBNAME INVALID"

The SET parameter on the DEFRULE statement can also use symbolic substitution within quoted strings to build a value for the set. For example, the following SETs will set the first character user field to jobname.stepname.

SET USRFLDC1 = "&JOBNAME..STEPNAME"

Notes:

• When symbolic fields are used in the rules language, the entire symbolic name need not be entered—only enough of the name to ensure the field is unique. For example, &JOBN can specify &JOBNAME.
• During substitution, if there is no field currently associated with the symbolic name, symbolic substitution will use a single blank for character fields. Numeric fields will use a zero.

In the previous section, the prefixes used with a symbolic field determine where the field is found. The field format qualifiers control how a field is formatted. These qualifiers are primarily used with time, date and numeric-size symbolic fields. Examples of qualifiers include JULIAN, LONGDATE, DAY, FROMDAYS, TODAYS, DAYS and TODATE.

In earlier releases, JOBSDATE, JOBSDAY and JOBSLDATE fields all referred to the same date field for a job, and each symbolic field simply formatted the date differently. Since many date fields have been added across products, field format qualifiers were added to limit the number of symbolic names required for each new date field. Note: symbolic names available in earlier releases are now internally converted to the new format at rule compile time. Rules that use converted names will work correctly, but trace messages will display the converted name.

The following table shows how the field format qualifiers can be used to reformat a date field. Note: Most of the date fields are formatted based on the DATE parameter specified on the DIF execution parameters. DATE sets the default date format used by all products. However, the default date format can be overridden with the MMDDYY, MMDDYYYY, DDMMYY, DDMMYYYY, YYMMDD and YYYYMMDD field format qualifiers. For more information about the DIF DATE parameter, see “DIF - PARM Information” in the Product Installation Guide.

Table 3-1. Field Format Qualifiers for Date Symbolics

The FROMDAYS, TODAYS, DAYS and TODATE field format qualifiers can also be used to perform computations with date fields. The following list illustrates how each qualifier can be used to return a numeric value. Note: the following examples use the JOBSDATE symbolic field, but any date field can be used with the qualifiers.

Table 3-2. Qualifiers for Date Calculations

The following table shows how the field format qualifiers can be used to reformat a time field. Note: this table uses the JOBSTIME symbolic field, but any time field can be used with the qualifiers.

Table 3-3. Field Format Qualifiers for Time Symbolics

The following table shows how the field format qualifiers can be used to perform a unit conversion on a numeric size value. Note: this table uses the USRFLDN1 symbolic field, but any numeric field can be used with the qualifiers.

Table 3-4. Field Format Qualifiers for Size Symbolics

The LENGTH qualifier returns the length of the returned field. For example, &LENGTH:DSNAME can be used to return the length of the current data set name.

The list below displays a few sample SET statements using the field format qualifiers. Note: These qualifiers can be used on any symbolic fields used in the rules language.

SET USRFLDN1 = &DAYS:JOBSDATE

SET USRFLDN1 = &USRFLDN1+1

SET USRFLDN2 = &TODATE:USRFLDN1

SET USRFLDC1 = "3/10/2001"

SET USRFLDN2 = &TODATE:USRFLDC1

SET USRFLDN3 = &FROMDAYS:USRFLDN2

SET USRFLDN3 = &TODAYS:USRFLDN2

SET USRFLDN1 = &DAYS:JOBSDATE+2

SET DAYS:EXPDT = &USRFLDN1

SET DAYS:EXPDT = &DAYS:EXPDT+1

Symbolic Fields with Substrings

When only part of a symbolic field is required, the displacement and length of the substring can be specified with the symbolic name. The displacement and length should be enclosed in parentheses, and be separated by a comma or blank. The parenthetical field must be concatenated with the symbolic field name. For example, the following symbolic name evaluates the first three characters of the job name.

IF &JOBNAME(1,3) = CCB

Substrings can be used on all character symbolic fields. For example, the following SET expressions could be used to build the OWNER field.

SET &OWNER(1,3) = &JOBNAME(1,3)

SET &OWNER(4,3) = "GRP"

Message definitions and SET expressions can use substrings on character symbolic fields used in quoted strings.

In previous releases, the rules language provided unique field names for variables such as ACCTn, CHARSn, COPIESn, JACCTn, QUALn, SACCTn, SMSACS_JACCTn, SMSACS_SACCTn, SMSACS_STORGRPn, and STORGRPn.

While the language still supports the original symbolic fields, an index value can now be specified within braces { } for the requested symbolic field. For example, the following IF statement uses an index request for the fourth qualifier in a data set name.

IF &QUAL{4} = SOURCE

Defining Symbolic Fields with DEFEQU

The DEFEQU statement can equate an installation-definable symbolic name with a literal value or another symbolic field. Substrings are supported on character symbolic fields, and numeric symbolic fields can be defined by specifying the NUMERIC parameter before the equate expression.

This facility can assign meaningful names to user fields delivered with the product: USRFLDCn and USRFLDNn. Also, since DEFEQU supports substrings, a single user field can be subdivided into many new symbolic fields. For example:

DEFEQU AMDTEST = &USRFLDC1(1,1)

DEFEQU CCLTEST = &USRFLDC1(2,1)

The DEFVAR statement defines a new variable in the rules language. A new variable is typically constructed using other variables and literal fields. The DEFVAR statement allows indirect references to other variables — even other variables created with DEFVAR.

Variables can have a scope of LOCAL or SYSTEM. The SYSTEM parameter allows the rules processor to write the new variable to a VSAM file during SET processing. LOCAL variables are available for all environments, but only during rule execution.

Building the Text field — The DEFVAR statement builds the new variable using literal strings and symbolic substitution. The text field must start with a single (') or double (") quote, and terminate with the same type of quote. Both character and numeric symbolic fields can be placed in the definition.

Continuation — The text cannot be continued onto the next card. Add a plus (+) after the end of the text field, and start another quoted text field on the next control card.

Message length after substitution is limited to 125 bytes.

Defining a VSAM file for variables with a scope of SYSTEM — The following JCL allocates and initializes a VSAM file for the DEFVAR variables with SYSTEM scope. The file should be allocated to the DEFVAR DD statement in any job that accesses the variables.

//JOBNAME JOB ...
(RC=0 Expected)
// EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//IN DD *
$DUMMY
//SYSIN DD *
DELETE DTS.R71.DIFVAR
DEFINE CLUSTER(NAME(DTS.R71.DIFVAR) + VOLUME(??????) SHAREOPTIONS(2) + RECORDSIZE(56 254) CYL(2 2) + INDEXED KEYS(52 0) )
REPRO INFILE(IN) OUTDATASET(DTS.R71.DIFVAR) LISTCAT ENTRY(DTS.R71.DIFVAR) ALL

Token Lists Tokens can be formed into lists in the rules language. Lists are formed by enclosing tokens in parentheses. Token lists are used by the DEFRULE and DEFPROC statements.

The DEFRULE statements often use token lists in expressions for IF-THEN-ELSE processing. These expressions examine a list of conditions. In most situations, if any entry within the list evaluates as true, the expression evaluates as true. NOT EQUAL processing is the one exception — all entries in the list must fail comparison for the expression to evaluate as true.

Example: the following expressions would be successful for any job starting with TOM — unless the name ends with BAK or RST.

IF JOBNAME EQ (DON*,TOM*)

JOBNAME NE (*BAK,*RST)

During expression processing, symbolic names can also be used in token lists. In the following example, the first two characters of the account number will be examined for SY or AB. If these checks fail, the first two characters of the account number will be compared with the first two characters of the jobname.

IF ACCT(1,2) = (SY,AB,&JOBNAME(1,2))

Tables The rules language can use external tables to specify token lists. Literals and symbolic fields can be listed in a table. The tables are partitioned data set members that are read from the DIF PARMLIB DD statement during rule conversion.

The following example demonstrates the use of tables. The ALTDDS table contains a list of job names that can use the $ALTDATE DD statement.

DEFRULE ALTDDS

IF &JOBNAME = TABLE(ALTDDS) THEN SET ALLOW_DD = YES

Table requests may also be specified within a token list. For example, the high level qualifier expression in the last example might be changed as follows:

IF &JOBNAME = (DON*,TOM*,TABLE(ALTDDS))

The partitioned data set member that defines the table may contain comments, blank lines, literal strings, symbolic fields and filter lists. Literals with wildcard characters and symbolic fields with substrings are also allowed. Entries in the table may be separated by commas or blanks. Note: the table member cannot use additional table requests. The following table might be used to define the ALTDDS table.

/* TABLE(ALTDDS) */
PROD1,PROD2,PROD3,PROD4,PROD5,PROD6,PROD7,PROD8,
PRD1,PRD2,PRD3,PRD4,PRD5,PRD6,PRD7,PRD8,PRD9,PP*

Filter Lists The rules language supports installation-definable symbolic fields — filter lists. A filter list is similar to external tables with a few exceptions:

• a filter list must be defined in the rules language before the filter name can be used in a rule definition
• filter lists are more efficient than tables. Each time a table is referenced, the rules compiler builds data structures for each token found in the table. Filter lists produce a single data structure that all references share
• a filter list can provide both INCLUDE and EXCLUDE token lists on the same filter definition
• during language tracing, compare processing displays the trace message comparing a symbolic field to the entire filter list — not a message for each token in the filter list
• the DEFFILT statement defines a filter list within the rules language, unlike tables which use PDS members. However, the INCLUDE statement can be used to place a filter list in a PDS member

Example: The following defines and uses two new symbolic fields: &PRODHLQ and &PRODVOLS. The DEFFILT statement defines a list of the high level qualifiers that define production data sets. The INCLUDE parameter on the DEFFILT statement defines a list that has exceptions. The EXCLUDE parameter defines the exceptions.

DEFFILT &PRODHLQ

INCLUDE(PROD1,PROD2,PROD3,PROD4,PROD5,PROD6,PROD7,PROD8,PRD1,PRD2,PRD3,PRD4,PRD5,PRD6,PRD7,PRD8,PRD9,PP*)

EXCLUDE(PPV*,PPR*)

DEFFILT &PRODVOLS

INCLUDE(PRD*)

DEFRULE PRDPERM

IF &HLQ = &PRODHLQ

THEN SET DISKPOOL=PRDPOOL

DEFPOOL PRDPOOL VOLSER = &PRODVOLS

The INCLUDE and EXCLUDE parameters that define a filter list may contain comments, blank lines, literal strings, other symbolic fields and tables. Literals with wildcard characters and symbolic fields with substrings are allowed. Entries may be separated by commas or blanks.

Note: the DEFFILT statement has an alias of FILTLIST.

Filter Rules for Rule Statements

In early releases, customers sometimes requested additional filter-type keywords to be added to statements in the rules language. That information was often available to the product rules environment, but adding a new keyword with a patch was difficult. The FILTERRULE(rulename) keyword parameter can now be specified on selected statements: DEFCMD, DEFCONN, DEFDMYU, DEFDMYV, DEFENV, DEFGROUP, DEFMSG, DEFREC and DEFSMF.

The FILTERRULE keyword can determine whether the current statement is honored by the rule processor. If the rule member requested by FILTERRULE sets the symbolic field RULE_SKIP = YES, then the current rule statement will be skipped.

For example, the following DEFDMYV statement used by ACC would call the SYSACCT rule to determine whether the DEFDMYV should be used. Note: the SYSACCT member should be placed in the DIF rule library: DTS.R71.RULELIB.

DEFDMYV (VSAM*) FILTERRULE(SYSACCT)

In the following sample rule, the DEFDMYV would be bypassed for any job with a systems account number — first accounting field starts with SY.

IF &ACCT{1} = SY* THEN RULE_SKIP = YES

Expressions Expressions form a conditional relationship between two tokens and are used by four statements: IF, SET, DEFPOOL and DEFEQU.

• DEFRULE, DEFPROC and DO-END statements can use IF and SET statements. During IF processing, a rule definition uses one or more expressions to evaluate the conditions required by the rule. If the rule passes the evaluation, the SET parameters use an expression to set the requested fields.
• A DEFPOOL statement uses one or more expressions to define the list of devices associated with the pool definition.
• A DEFEQU statement uses an expression to define a new symbolic name.

Short Form

In the simplest form, an expression does not look like an expression. If a symbolic field can evaluate to a YES or NO character field, only the symbolic name is required in an expression to test for the YES condition. For example, the following expressions are equivalent.

IF &ALLOW_DD

IF &ALLOW_DD = YES

All remaining forms of expression are formed by two tokens separated by a relational operator. The valid relational operators include:

Ampersand Optional

In the rules language, the token on the left side of the relational operator always corresponds to a symbolic field. Therefore, the ampersand need not precede the symbolic name. For example, either of the following expressions can be used to evaluate the jobname field.

IF &JOBNAME = DON*

IF JOBNAME = DON*

To evaluate a substring of a symbolic field, concatenate the offset and length of the string enclosed in parentheses to the symbolic name. For example, the following expression checks the first two characters of the jobname for DO.

IF &JOBNAME(1,2) = DO

Expressions using Token Lists

The tokens on the right side of the relational operator can be literals, symbolic fields, tables or filter lists. If the tokens are enclosed in parentheses, the expression evaluates the list of tokens. If any entry in the list evaluates as true, the expression evaluates as true. For example, if the current jobname is TOMA, the following expression would be successful.

IF &JOBNAME = (DON*,TOM*)

If the token on the right side of the relational operator is a symbolic field, the expression is a field-to-field compare. In the following example, the first three characters of the jobname are compared with the first three characters of the programmer name field (comment) on the job card.

IF &JOBNAME(1,3) = &PGMRNAME(1,3)

Set Expressions

Expressions used on a SET parameter within a DEFRULE statement have the following limitations.

• The relational operator must be = (equal).
• The tokens used on both sides of the expression must be of the same type: numeric or character.
• Numeric ranges are not allowed on the token to the right of the relational operator.

When working with numeric symbolic fields, an expression can use numeric range checks. Any value that evaluates within the numeric range results in a true condition. In this type of expression, the relational operator must be equal. In the following example, the current unit address is compared to the hexadecimal range of 280 through 287.

UNITADDR = 280H-287H

The SET expression can perform numeric calculations. The rules language provides two forms for numeric calculations. A simple form evaluates one symbolic field, a numeric operator and a literal integer value.

• Only addition (+), subtraction (-), multiplication (*), and division (/) by a literal integer value are supported. Note: any calculation that produces a value less than one is set to zero.
• Multiplication modifications can use a percentage value (%). For example, the following SET expression sets the secondary space value to 25% of the primary space value. Note: on percentage modifications, any calculation that produces a value less than one is set to one.

SET &SSPACE = &PSPACE*25%

• The numeric expression to the right of the relational operator must not contain blanks.
• Divide by zero is not allowed.

The following SET expressions increment and decrement numeric user fields. This allows numeric user fields to be used as counters. Note: when using numeric user fields as counters, the USRFLDNn fields are reset to zero after processing a DD statement. The STPFLDNn symbolic fields remain available only for the current step, while the GBLFLDNn symbolic fields remain available for the entire job.

SET &USRFLDN1 = &USRFLDN1+1

SET &STPFLDN1 = &STPFLDN1+1

SET &GBLFLDN1 = &GBLFLDN1-1

Complex Numeric Expressions

For more complex numeric calculations, use the EVAL() function in a quoted string. The rules language performs symbolic substitution on the quoted string, and the EVAL() function performs numeric processing on the remaining integer numeric values. Nested parenthetical expressions are allowed.

• Only addition (+), subtraction (-), multiplication (*), and division (/) by an integer value are supported. Note: any calculation that produces a value less than one is set to zero.
• The numeric operators have no precedence. If no parenthetical expressions are used, operators are processed left to right.
• Divide by zero is not allowed.

The following SET expression sets the USRFLDN1 field to 15 times the USRFLDN2 field plus USRFLDN1.

SET &USRFLDN1 = "EVAL(&USRFLDN1+(15*&USRFLDN2))"