EVALUATE statement
The EVALUATE statement provides a shorthand notation for a series of nested IF
statements. It can evaluate multiple conditions. The subsequent action depends
on the results of these evaluations.
| Format |
 >>-EVALUATE--+-identifier-1-+----------------------------------->
+-literal-1----+
+-expression-1-+
+-TRUE---------+
'-FALSE--------'
>--+-----------------------------+------------------------------>
| .-------------------------. |
| V | |
'--- ALSO--+-identifier-2-+-+-'
+-literal-2----+
+-expression-2-+
+-TRUE---------+
'-FALSE--------'
.----------------------------------------------------------------------------.
| .------------------------------------------------. |
V V | |
>------WHEN--| phrase 1 |--+------------------------+-+--imperative-statement-1-+-->
| .--------------------. |
| V | |
'---ALSO--| phrase 2 |-+-'
>--+------------------------------------+--+--------------+----><
'-WHEN OTHER--imperative-statement-2-' '-END-EVALUATE-'
phrase 1:
|--+-ANY--------------------------------------------------------------------------------+--|
+-condition-1------------------------------------------------------------------------+
+-TRUE-------------------------------------------------------------------------------+
+-FALSE------------------------------------------------------------------------------+
'-+-----+--+-identifier-3------------+--+------------------------------------------+-'
'-NOT-' +-literal-3---------------+ '-+-THROUGH-+--+-identifier-4------------+-'
'-arithmetic-expression-1-' '-THRU----' +-literal-4---------------+
'-arithmetic-expression-2-'
phrase 2:
|--+-ANY--------------------------------------------------------------------------------+--|
+-condition-2------------------------------------------------------------------------+
+-TRUE-------------------------------------------------------------------------------+
+-FALSE------------------------------------------------------------------------------+
'-+-----+--+-identifier-5------------+--+------------------------------------------+-'
'-NOT-' +-literal-5---------------+ '-+-THROUGH-+--+-identifier-6------------+-'
'-arithmetic-expression-3-' '-THRU----' +-literal-6---------------+
'-arithmetic-expression-4-'
|
- Operands before the WHEN phrase
- Are interpreted in one of two ways, depending on how they are specified:
-
Individually,
they are called selection subjects.
- Collectively, they are called a set of selection subjects.
- Operands in the WHEN phrase
- Are interpreted in one of two ways, depending on how they are specified:
-
Individually,
they are called selection objects
- Collectively, they are called a set of selection objects.
- ALSO
- Separates selection subjects within a set of selection subjects; separates
selection objects within a set of selection objects.
- THROUGH and THRU
- Are equivalent.
Two operands connected by a THRU phrase must be of the same class. The two
operands thus connected constitute a single selection object.
The number of selection objects within each set of selection objects must be
equal to the number of selection subjects.
Each selection object within a set of selection objects must correspond to
the selection subject having the same ordinal position within the set of
selection subjects, according to the following rules:
- Identifiers, literals, or arithmetic expressions appearing within a
selection object must be valid operands for comparison to the corresponding
operand in the set of selection subjects. For comparisons involving
date fields, see Comparison of date fields.
- condition-1, condition-2, or the word TRUE or FALSE
appearing as a selection object must correspond to a conditional expression
or the word TRUE or FALSE in the set of selection subjects.
- The word ANY can correspond to a selection subject of any type.
END-EVALUATE phrase
This explicit scope terminator serves to delimit the scope of the EVALUATE
statement. END-EVALUATE permits a conditional EVALUATE statement to be nested in
another conditional statement.
For more information, see Delimited scope statements.
Determining values
The execution of the EVALUATE statement operates as if each selection
subject and selection object were evaluated and assigned a numeric,
alphanumeric, DBCS, or national character value; a range of numeric,
alphanumeric, DBCS, or national character values; or a truth value. These
values are determined as follows:
- Any selection subject specified by identifier-1, identifier-2,
... and any selection object specified by identifier-3 or identifier-5
without the NOT or THRU phrase are assigned the value and class of the data
item that they reference.
- Any selection subject specified by literal-1, literal-2,
... and any selection object specified by literal-3 or literal-5
without the NOT or THRU phrase are assigned the value and class of the
specified literal. If literal-3 or literal-5 is the
figurative constant ZERO, QUOTE, or SPACE, the figurative constant is
assigned the class of the corresponding selection subject.
- Any selection subject in which expression-1, expression-2,
... is specified as an arithmetic expression, and any selection
object without the NOT or THRU phrase in which arithmetic-expression-1
or arithmetic-expression-3 is specified, are assigned numeric
values according to the rules for evaluating an arithmetic expression. (See Arithmetic expressions.)
- Any selection subject in which expression-1, expression-2,
... is specified as a conditional expression, and any selection
object in which condition-1 or condition-2 is
specified, are assigned a truth value according to the rules for evaluating
conditional expressions. (See Conditional expressions.)
- Any selection subject or any selection object specified by the words TRUE
or FALSE is assigned a truth value. The truth value “true” is
assigned to those items specified with the word TRUE, and the truth value
“false” is assigned to those items specified with the word FALSE.
- Any selection object specified by the word ANY is not further evaluated.
- If the THRU phrase is specified for a selection object without the NOT
phrase, the range of values includes all values that, when compared to the
selection subject, are greater than or equal to the first operand and less
than or equal to the second operand according to the rules for comparison.
If the first operand is greater than the second operand, there are no values
in the range.
- If the NOT phrase is specified for a selection object, the values assigned
to that item are all values not equal to the value, or range of values, that
would have been assigned to the item had the NOT phrase been omitted.
Comparing selection subjects and objects
The execution of the EVALUATE statement then proceeds as if the values assigned
to the selection subjects and selection objects were compared to determine
whether any WHEN phrase satisfies the set of selection subjects. This comparison
proceeds as follows:
- Each selection object within the set of selection objects for the first
WHEN phrase is compared to the selection subject having the same ordinal
position within the set of selection subjects. One of the following
conditions must be satisfied if the comparison is to be satisfied:
- If the items being compared are assigned numeric, alphanumeric,
DBCS, or national character values, or a range of numeric, alphanumeric,
DBCS, or national character values, the comparison is satisfied if
the value, or one value in the range of values, assigned to the
selection object is equal to the value assigned to the selection subject
according to the rules for comparison.
- If the items being compared are assigned truth values, the comparison
is satisfied if the items are assigned identical truth values.
- If the selection object being compared is specified by the word ANY,
the comparison is always satisfied, regardless of the value of the
selection subject.
- If the above comparison is satisfied for every selection object within the
set of selection objects being compared, the WHEN phrase containing that set
of selection objects is selected as the one satisfying the set of selection
subjects.
- If the above comparison is not satisfied for every selection object within
the set of selection objects being compared, that set of selection objects
does not satisfy the set of selection subjects.
- This procedure is repeated for subsequent sets of selection objects in the
order of their appearance in the source text, until either a WHEN phrase
satisfying the set of selection subjects is selected or until all sets of
selection objects are exhausted.
Executing the EVALUATE statement
After the comparison operation is completed, execution of the EVALUATE
statement proceeds as follows:
- If a WHEN phrase is selected, execution continues with the first imperative-statement-1
following the selected WHEN phrase. Note that multiple WHEN statements are
allowed for a single imperative-statement-1.
- If no WHEN phrase is selected and a WHEN OTHER phrase is specified,
execution continues with imperative-statement-2.
- If no WHEN phrase is selected and no WHEN OTHER phrase is specified,
execution continues with the next executable statement following the scope
delimiter.
- The scope of execution of the EVALUATE statement is terminated when
execution reaches the end of the scope of the selected WHEN phrase or WHEN
OTHER phrase, or when no WHEN phrase is selected and no WHEN OTHER phrase is
specified.
|