WHILE/ENDWHILE

WHILE...ENDWHILE (Short Name: WHI...ENDW)

Use the WHILE...ENDWHILE structure in a program to continuously run a set of commands based on a specified condition.

Options

condlist
Specifies a list of conditions that identify the requirements to be met.

while-block
Specifies commands to be executed if the WHILE condition is true.

About the WHILE...ENDWHILE Command

A WHILE ... ENDWHILE structure consists of conditions, commands, and an ENDWHILE statement. As long as WHILE conditions are true, R:BASE runs the commands repeatedly.

WHILE Conditions

The basic WHILE conditions are the same as those used in an IF...ENDIF structure and are as follows:

Condition            Description
varname IS NULL            The value of the variable is null.

varname IS NOT NULL         The value of the variable is not null.

varname CONTAINS 'string'         The variable has a TEXT data type and contains a 'string' as a
               substring in the variable value.

varname NOT CONTAINS 'string'      The variable has a TEXT data type and a 'string' is not contained as
               a substring in the variable value.

varname LIKE 'string'         The variable equals a 'string.' A 'string' can contain wildcards.

varname NOT LIKE 'string'         The variable does not equal the 'string'. A 'string' can contain
               wildcards.

varname BETWEEN value1 AND value2   The value of the variable is greater than or equal to value1 and less
               than or equal to value2. The variable and the values must be the
               same data type.

varname NOT BETWEEN value1 AND value2   The value of the variable is less than value1 or greater than value2.
               The variable and the values must be the same data type.

item1 op item2            Item1 has the specified relationship to item2. Item1 can be a column                name, value, or expression; item2 can be a column name, value, or                expression.

An expression can be substituted for the first variable in each of the condition formats shown above.

You can only use wildcard characters with the LIKE and NOT LIKE operators. For example, varname LIKE 'string%.'

You can combine conditions from the WHILE condition list by using the connecting operators AND, OR, AND NOT, and OR NOT. Be careful when using these conditions in a condition list. Conditions connected by AND are evaluated first, then conditions connected by OR are evaluated. However, you can use parentheses to set the evaluation order.

WHILE Loop Commands

All WHILE loop commands are retained in memory, so a WHILE loop runs more quickly than a GOTO or LABEL structure. A computer must have enough available memory to read all of the commands in a WHILE loop, or the program terminates abnormally.

R:BASE optimizes commands in a WHILE loop so that it runs more quickly. Use the following guidelines when constructing WHILE loops so they run more quickly.

Do not clear variables in the WHILE loop. Rather, set those variables to null.

Do not define variables within the WHILE loop. Only define variables outside of the loop because the values can change within the loop.

If you issue multiple SET VARIABLE commands on a single command line, then those variables will not be optimized. If you want to increase the speed for that loop, you should put the SET VARIABLE commands on separate lines.

To turn off WHILE loop optimization, set WHILEOPT off.

The ENDWHILE Statement

ENDWHILE indicates the end of the loop. Place an ENDWHILE statement at the end of each WHILE loop. Each time R:BASE reaches the ENDWHILE statement, R:BASE returns to the WHILE command at the top of the loop and checks to see whether the conditions are still true or false. If true, R:BASE again runs the commands between the WHILE and the ENDWHILE. If false, R:BASE runs the command line immediately following the ENDWHILE.

Exiting from a WHILE Loop

To exit from a WHILE loop before the WHILE condition becomes false, use an IF...ENDIF structure to check other conditions, then use BREAK to exit from the WHILE loop. The BREAK command causes the WHILE loop to terminate when the conditions specified in the IF statement become true.

Never use GOTO to exit from a WHILE loop; use BREAK instead. BREAK clears the WHILE loop. When you do not use BREAK or the naturally occurring exit (that is, when the WHILE loop conditions are no longer true) to exit from a WHILE loop, R:BASE continues to read commands into memory. If you have a large command or procedure file, you can run out of memory and your program terminates abnormally.

Example

In the following example, R:BASE runs the commands in the WHILE block and evaluates the v2 condition in the IF statement. If v2 is not equal to zero, R:BASE runs the BREAK command and terminates the WHILE loop. R:BASE then runs the commands immediately following the ENDWHILE statement. As long as the WHILE condition (v1) is true and the IF condition (v2) remains false, the WHILE loop continues processing.

SET VARIABLE v1 = 0
WHILE v1 = 0 THEN
   *(while-block commands)
   IF v2 <> 0 THEN
      BREAK
   ENDIF
   *(while-block commands)
ENDWHILE
*(next command outside the while-block