SPFLite - V3.0.24069 2024-03-09

Expression is a numeric expression, in which non-zero values represent logical TRUE, and zero values represent logical FALSE.

If Expression contains string values, these must be part of a larger expression that results in a numeric value that can be treated as TRUE or FALSE. For example, the expression A = "X" produces a TRUE or FALSE value, but a simple string like "X" cannot be used as an expression in condition tests like WHILE or UNTIL. (That is, numbers can be converted to a "truth value", but strings cannot be.)

DO/LOOP statements are quite flexible. They allow you to create loops with the test for the terminating condition at the top of the loop, the bottom of the loop, both places, or none of the above. 

The WHILE and UNTIL keywords are used to add tests to a DO/LOOP. Use the WHILE if the loop should be repeated if expression is TRUE, and terminated if expression is FALSE. UNTIL has the opposite effect; that is, the loop will be terminated if expression is TRUE, and repeated if FALSE. 

When WHILE or UNTIL appears after the DO keyword, the test is performed before executing the body of the do-loop block. When WHILE or UNTIL appears after the LOOP keyword, the test is performed after executing the body of the do-loop block. It is possible to put a "before test" and an "after test" on the same do-loop block, though usually only one or the other is needed.

Note that DO is ended by LOOP and not by END DO.

An EXIT DO statement can be used to force an exit from a loop regardless of the WHILE / UNTIL condition. (EXIT DO is like a break or leave statement in some languages.)

An ITERATE DO statement transfers control to the bottom of the loop and triggers condition evaluation. (ITERATE DO is like a continue statement in some languages.)  Because ITERATE DO creates the equivalent of a "backward-reference GOTO" statement, great care is needed to ensure you do not create a logic error that would cause the program to be "stuck in a loop".

When a FOR statement is encountered, start is assigned to Counter, and Counter is tested to see if it is greater than (or, for negative increment, less than) stop. If the initial Start value makes the "stopping condition" immediately true, the body of the FOR/NEXT loop is not executed at all.

If the initial Start value does not make the "stopping condition" immediately true, the statements within the FOR/NEXT loop are executed, increment is added to Counter, and Counter is again tested against stop. The statements in the loop are executed repeatedly until  the stopping condition is true, at which time control passes to the statement immediately following the NEXT.

Counter is a numeric variable serving as the loop counter.

Start is a numeric expression specifying the value initially assigned to Counter.

Stop is a numeric expression giving the value that Counter must reach for the loop to be terminated.

Increment is an optional numeric expression defining the amount by which Counter is incremented with each loop execution. If not specified, Increment defaults to 1.

Note that FOR is ended by NEXT and not by END FOR.

An EXIT FOR statement can be used to force an exit from a loop regardless of stopping condition. (EXIT FOR is like a break or leave statement in some languages.)

An ITERATE FOR statement transfers control to the bottom of the loop and triggers evaluation of the stopping condition. (ITERATE FOR is like a continue statement in some languages.)  Because ITERATE FOR creates the equivalent of a "backward-reference GOTO" statement, great care is needed to ensure you do not create a logic error that would cause the program to be "stuck in a loop".

It is possible to modify the Counter variable inside the FOR/NEXT loop using assignment statements. However, experience has shown that such techniques often result in programming logic errors, and is thus not recommended. Instead of modifying the Counter you could do one of the following:

• Code an inner IF statement to selectively execute statements in a given loop iteration
• Use the EXIT FOR statement to leave the loop altogether
• Use the ITERATE FOR statement to begin the next iteration of the for-loop. Because of the potential risk of being "stuck in a loop" by using this statement, it is often safer to enclose a group of statements within your loop by an inner IF block, rather than trying to "skip" them using an ITERATE FOR statement.

NOTE  The NEXT statement does not require the name of the counter variable. Counter is optional and is treated as comments.

In executing IF blocks, the truth of the expression in the initial IF statement is checked first. If it evaluates to FALSE (zero), each of the following ELSEIF statements is examined in order. There can be as many ELSEIF statements as desired. As soon as one is found to be TRUE (non-zero), the statement(s) following the associated THEN and before the next ELSEIF or ELSE will be executed.

Execution then jumps to the statement just after the terminating END IF without making any further tests. If none of the test expressions evaluates to TRUE, the statement(s) in the ELSE clause (which is optional) are executed.

IF blocks must be terminated with a matching END IF statement. Note that the END IF statement requires a space and the ELSEIF statement does not.

testlist is one or more tests, separated by commas, to be performed on expression. expression can be of type STRING or NUMBER.

When a SELECT statement is encountered, expression is evaluated using the testlist in the first CASE clause. If the evaluation is FALSE, the evaluation is repeated using the next testlist. As soon as an evaluation is TRUE (non-zero), the statements following that CASE clause are executed, up to the next CASE clause.

Execution then passes to the statement following the END SELECT statement. If none of the evaluations is TRUE, the statements following the optional CASE ELSE clause are executed.

The tests that may be performed by a CASE clause include: equality, inequality, greater than, less than, and range ("from-to") testing. The SELECT CASE block can do string or numeric tests, but these cannot be interchanged.

Examples of numeric CASE clause tests:

SELECT CASE numeric_expression

CASE > b                         ' relational; is expression > b?

CASE 14                          ' equality (= assumed); is equal to 14?

CASE b TO 99                     ' range; is it between variable b and 99 

CASE 14, b                       ' two equality tests; equal to 14 or b

Examples of string CASE clause tests:

SELECT CASE string_expression

   CASE > b$                        ' relational; is expression > b$?

   CASE "X"                         ' equality (= is assumed); is equal to "X"?

   CASE "A" TO "C"                  ' range; is between "A" and "C"

   CASE "Y", b$                     ' two equality tests; is equal to "Y" or b$?

If numeric_expression is TRUE (it evaluates to a non-zero value), all of the statements between the WHILE and the terminating WEND are executed. Control then jumps back to the WHILE statement and repeats the test. If it is still TRUE, the enclosed statements are executed again. This process is repeated until the test expression evaluates to zero, or an EXIT WHILE statement is encountered. In either case, execution passes to the statement following WEND.

If numeric_expression evaluates to FALSE (zero) on the first pass, none of the statements in the loop are executed.

Loops built with WHILE/WEND statements can be nested (enclosed within each other). Each WEND matches the most recent unmatched WHILE.

Note that WHILE is ended by WEND and not by END WHILE.

Be aware that the WHILE/WEND statement is somewhat redundant as a language feature. You can do exactly the same thing (and more) using a DO WHILE/LOOP. As a coding style, you may wish to standardize on using DO statements rather than WHILE statements.

Stops execution of the script. In a stand-alone thinBasic program, STOP would halt the program execution. Because thinBasic is being used as a macro script engine, STOP returns control to SPFLite, which returns you to the edit session from which you originally launched the thinBasic macro.

The HALT command optionally allows you to set a macro Return code and message before terminating.

Created with the Personal Edition of HelpNDoc: Maximize Your Productivity with HelpNDoc's Efficient User Interface