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. A 'string' can contain wildcards. |
varname NOT CONTAINS 'string' |
The variable has a TEXT data type and a 'string' is not contained as a substring in the variable value. A 'string' can contain wildcards. |
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 LIKE 'string ' ESCAPE 'chr ' |
The variable equals a 'string.' If you want to use a wildcard character as a text character in the string, specify the ESCAPE character chr. In the string, use chr in front of the wildcard character. |
varname NOT LIKE 'string ' ESCAPE 'chr ' |
The variable does not equal a 'string.' If you want to use a wildcard character as a text character in the string, specify the ESCAPE character chr. In the string, use chr in front of the wildcard character. |
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. |
The valid operators (op) for the conditions in a WHILE...ENDWHILE structure are listed in the table below. Do not use wildcard characters with these operators.
Operator |
Description |
= |
Equals |
<= |
Less than or equal to |
>= |
Greater than or equal to |
< |
Less than |
> |
Greater than |
<> |
Not equal |
A variable can be substituted for the first variable in each of the condition formats shown above, and for either item when using an operator comparison. The condition should not use dotted variables, unless the current value of that variable is to be evaluated. When comparing items with an operator, (e.g. item1 < item2, item1 >= item2, etc.) the condition may be enclosed in parentheses, where R:BASE will evaluate the expression each time through the loop.
You can only use wildcard characters with the LIKE, NOT LIKE, CONTAINS, or NOT CONTAINS 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.
Skip to the next WHILE Occurrence
Use the CONTINUE command to move to the next occurrence of the WHILE loop and run the code.
In the following example, when the code is run, processing returns to line 3 after it completes the CONTINUE command on line 6. The while-block commands in line 8 are not run.
SET VARIABLE v1=0
SET VARIABLE V2=1
WHILE v1 = 0 THEN
*(while-block commands)
IF v2 <> 0 THEN
CONTINUE
ENDIF
*(while-block commands)
ENDWHILE
Displaying Messages
It is helpful to show a progress message when performing long running tasks in WHILE loops. A method to let the user know the status of the process is using a PAUSE 3 dialog with the GAUGE options with the PROCESSMESSAGE command, which processes messages that are currently in the windows message queue. The PROCESSMESSAGE can help in the GUI part to avoid the "Not responding" behavior in Windows operating systems.
Examples
Example 01. 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
Example 02. The following example loops through a counter displaying a PAUSE message.
CLS
PAUSE 3 USING ' Calculating ... Please Stand By ...'
SET VAR vCounter INTEGER = 1
WHILE vCounter < 2500000 THEN
SET VAR vCounter = (.vCounter + 1)
PROCESSMESSAGE
ENDWHILE
CLEAR VARIABLE vCounter
CLS
RETURN
