EVALUATE
The EVALUATE directive provides a multi-branch method of choosing the source lines to include in a compilation group.
For descriptive purposes, in this topic:
- operand-1 refers to literal-1 or arith-expr-1 in format 1, and to the TRUE keyword in format 2.
- operand-2 refers to literal-2 or arith-expr-2 in format 1, and to constant-conditional-expression-1 in format 2.
- operand-3 refers to literal-3 or arith-expr-3 in format 1.
All formats:
- >>EVALUATE, >>WHEN, >>WHEN OTHER, >>END-EVALUATE
- Must begin on a new line in area A or B and must be specified entirely on that line.
- text-1, text-2
- Must begin on a new line and may consist of multiple lines.
May be any kind of source lines, including compiler directives. text-1 or text-2 may also include COPY statements.
The phrases of a given EVALUATE directive must be specified all in the same library text or all in source text. For purposes of this rule, text-1 and text-2 are not considered phrases of the EVALUATE directive. A nested EVALUATE directive specified in text-1 or text-2 is considered a new EVALUATE directive.
Format 1:
- >>EVALUATE
- All operands of one EVALUATE directive must be of the same category. For this rule, an arithmetic expression is of category numeric.
- literal-1, arith-expr-1
- Selection subjects.
- literal-2, literal-3, arith-expr-2, arith-expr-3
- Selection objects.
- THROUGH, THRU
- The words THROUGH and THRU are equivalent. If the THROUGH phrase is specified, all selection subjects and selection objects must be of category numeric.
- arith-expr-1, arith-expr-2, arith-expr-3
- Must be formed in accordance with the arithmetic expression rules as described in Compile-time arithmetic expressions.
Format 2:
- constant-conditional-expression-1
- Must be formed in accordance with the constant conditional expression rules as described in Constant conditional expressions.
General rules
All Formats:
- text-1 and text-2 are not part of the EVALUATE compiler directive line. text-1 and text-2 that are in the first true branch of the EVALUATE statement are subject to the matching and replacing rules of the COPY statement and REPLACE statement.
- If the END-EVALUATE phrase is reached without any WHEN phrase evaluating to TRUE, or without encountering a WHEN OTHER phrase, all lines of text-1 associated with all WHEN phrases are omitted from the resultant text.
Format 1:
- The selection subject is compared against the values specified
in each WHEN phrase in turn as follows:
- If the THROUGH phrase is not specified, a TRUE result is returned if the selection subject is equal to operand-2.
- If the THROUGH phrase is specified, a TRUE result is returned if the selection subject is greater than or equal to operand-2 and less than or equal to operand-3.
- If a WHEN phrase evaluates to TRUE, all the lines of text-1 associated with that WHEN phrase are included in the resultant text. All lines of text-1 associated with other WHEN phrases in that EVALUATE directive and all lines of text-2 associated with a WHEN OTHER phrase are omitted from the resultant text.
- If no WHEN phrase evaluates to TRUE, all lines of text-2 associated with the WHEN OTHER phrase, if specified, are included in the resultant text. All lines of text-1 associated with the other WHEN phrases are omitted from the resultant text.
- If literal-1 is an alphanumeric literal, a character-by-character comparison for equality based on the binary value of each character’s encoding is used. If the literals are of unequal length, they are not equal.
Format 2:
- For each WHEN phrase in turn, the constant-conditional-expression-1 is evaluated in accordance with the rules in Constant conditional expressions.
- If a WHEN phrase evaluates to TRUE, all lines of text-1 associated with that WHEN phrase are included in the resultant text. All lines of text-1 associated with other WHEN phrases of that EVALUATE directive and all lines of text-2 associated with a WHEN OTHER phrase are omitted from the resultant text.
- If no WHEN phrase evaluates to TRUE, all lines of text-2 associated with the WHEN OTHER phrase, if specified, are included in the resultant text. All lines of text-1 associated with other WHEN phrases are omitted from the resultant text.