Verbs and Built-in Functions › &BOOLEXPR

&BOOLEXPR

The &BOOLEXPR built-in function validates and/or tests a Boolean expression.

This built-in function has the following format:

&BOOLEXPR [ SUBCHAR={ & | c } ]
          [ EVAL={ YES | NO } ]
          [ FOLD={ * | YES | NO } ]
          { DATA=expression | VARS=prefix* RANGE=(start,end) }

The &BOOLEXPR built-in function allows you to write a complex Boolean expression, and supply it, either directly or indirectly, through a set of variables. The expression is analyzed for syntactical correctness, or evaluated, and the logical result made available.

The expression syntax is flexible and supports the full use of AND, OR, and NOT, and unlimited complexity and use of parentheses.

The function returns one of the following values:

VALID

Indicates that the Boolean expression is valid, but the EVAL=NO operand suppressed evaluation.

INVALID

Indicates that the Boolean expression has an error. &SYSMSG contains a description of the error.

BAD

Indicates that the Boolean expression is valid, but a data error has been encountered during evaluation. &SYSMSG contains a description of the error.

0

Indicates that the Boolean expression has been evaluated and is false.

1

Indicates that the Boolean expression has been evaluated and is true.

The &BOOLEXPR function does not change the content of &SYSMSG when the return values are VALID, 0, or 1.

Operands:

SUBCHAR={ & | c }

(Optional) Allows you to alter the variable substitution character from its default value of an ampersand (&). This ability prevents the substitution of variable names with their values before the parsing of the Boolean expression, which can lead to syntax and other errors.

The only characters permitted for the substitution character are & (the default), %, !, ?, ~, and '.

None of these characters are valid outside quoted data in the expression in any other context.

When supplying an expression using the DATA= operand, without the expression itself being contained in variables, this operand is probably required. For example, the following statement would result in the &A, &B, &C, and &D variables being replaced with their current contents before the evaluation of the expression. This processing sequence could possibly result in syntax errors:

&RESULT = &BOOLEXPR DATA=&A = &B AND &C = &D

Alternatively, if you specify the following statement, &BOOLEXPR itself processes the variables:

&RESULT = &BOOLEXPR SUBCHAR=% DATA=%A = %B AND %C = %D

When supplying the expression itself in variables, any embedded ampersand-prefixed variable names are correctly processed, unless &CONTROL RESCAN is in effect, for example:

&BOOLEXPR DATA=&EXPRESSION

EVAL={ YES | NO }

Indicates whether the Boolean expression is to be evaluated if syntactically correct or validated for syntactical correctness.

EVAL=YES

Evaluates the expression if no syntax errors are encountered. If the expression is valid, evaluation is attempted, which leads to either the 0, 1, or BAD return values.

EVAL=NO

Suppresses evaluation. If the expression is valid, the function return value is VALID.

If the expression is not valid (that is, a syntax error), the return value is INVALID in any case.

Default: YES

FOLD={ * | YES | NO }

Controls the default action to take, regarding the uppercasing of variable and quoted operands, when evaluating the expression.

FOLD=*

Specifies that the setting of &CONTROL IFCASE is honored for the standard relational operators, and the CONTAINS and LIKE operators. The strict operators do not uppercase data in this case.

FOLD=YES

Specifies that everything is uppercased.

FOLD=NO

Specifies that nothing is uppercased.

The setting of the FOLD operand is overridden on individual tests in the expression, using the FOLD and NOFOLD modifiers.

If variable uppercase translation is performed automatically on assignment, the effect of the &CONTROL UCASE option can override the intended effect of IFCASE.

Default: *

DATA=expression | VARS=prefix* RANGE=(start,end)

These operands supply the source data of the Boolean expression. Either the DATA=expression, or the VARS=prefix* RANGE=(start,end) operands must be supplied.

If DATA=expression is used, it must be the last operand, as all data following it to the end of the NCL statement is regarded as the Boolean expression.

If VARS=prefix* RANGE=(start,end) is used, the Boolean expression is contained in a set of nominated NCL variables. The data in these variables is extracted, and concatenated together with a single blank inserted between them, and is used as the Boolean expression. The VARS= and RANGE= operands is in any order, and need not be the last operands. The start and end values must be numbers in the range 0 through 32767, and end must be greater than or equal to start.