Directives 

Formats

Where:

Description

The FOR directive is used to define the start of a repetitive loop of instructions in a program. The end of the loop is defined by a subsequent NEXT directive following in the program code. (If you specify a variable with a NEXT directive, it must match the variable in the FOR directive.)

The NEXT directive can appear anywhere in the program except where it would be executed inside another FOR/NEXT loop, a GOSUB/RETURN routine, a WHILE/WEND loop, or a REPEAT/UNTIL loop. The control variable can be omitted from the NEXT directive because the increment/decrement of the FOR var is assumed automatically. However, the NEXT var is useful for readability purposes, especially if it appears within a nested loop structure.

Use the EXITTO directive to halt a FOR/NEXT loop without performing all iterations. When the system executes an EXITTO directive, it removes the top entry from the FOR/NEXT stack and ends that FOR/NEXT loop.

Note:
The test to determine if the loop will be terminated occurs when the NEXT directive is encountered; therefore, if the initial value of the loop control variable exceeds the ending value, the loop will execute once.

Format 1

For Loop, Conventional Syntax 

FOR [LOCAL] numvar=first TO last [STEP step]
...
NEXT [numvar]

When using conventional syntax, the keyword TO is required in order to define first and last values in the loop.

The STEP value, if you use one, is evaluated and saved as the increment (or decrement if negative). If you do not include an increment/decrement, the default is 1. An increment of 0 is invalid and results in Error #44: Invalid step value.

The current program statement position is saved and execution continues. When a NEXT directive is encountered with the same variable as in the FOR directive (or no variable name), it increments/decrements the value. If the new value does not exceed the end value (or fall below it, if decremented), control transfers back to the FOR directive to continue the loop; otherwise, the FOR/NEXT loop ends.

Examples:

0010 for I = 1 to 10
0020 print I,
0030 next I

Yields: 1 2 3 4 5 6 7 8 9 10

The following example strips trailing spaces from the A$:

0030 A$=......
0040 gosub 1000
......
1000 if A$="" then I=0; return
1010 for I=len(A$) to 1 step -1
1020 if A$(I,1)<>" " then exitto 1040
1030 next
1040 return

This example uses nested FOR/NEXT loops to generate the string B$ from A$ reversed:

0010 input "Enter character string:",A$
0020 if A$="" then stop
0030 B$=A$
0040 for I=1 to len(A$)
0050 for J=len(A$) to 1 step -1
0060 B$(I,1)=A$(J,1)
0070 next J; next I
0080 print "The answer is: ", B$
0090 goto 0010

Format 2

For Loop, Simplified Syntax

FOR numvar 
...
NEXT [numvar] 

This format executes the logic immediately following the FOR by the number of times specified in the numeric value numvar; therefore, FOR 1 will execute the loop once, and FOR 5 will execute the loop 5 times. A value of 0 causes the loop to be skipped. An error is generated if the numeric value is not an integer or it is less than 0.

If numvar is a simple numeric variable, the system will first set numvar to 1, then increment up to its initial value. When numvar = 5, the loop will execute 5 times with numvar starting at 1 and incrementing by 1 through each iteration to 5. At the completion of the loop, numvar will equal its initial value. Regardless of whether a simple numeric variable is used, TCB(19) will contain the current iteration count during the loop.

Example 1:

N=len(X$)
for N
     if X$(N,1)="X" \
          then X$(N,1)="Y"
next

Example 2:

TOT=0
for dim(read max(Balance))
     TOT+=Balance[tcb(19)]
next

Should a loop using a defined variable be prematurely exited (via BREAK, POP or EXITTO), the variable will remain at its last value:

N=10
for N
     if X$[N]="" \
          then break
…
next

When the IF condition is satisfied and the FOR loop is exited via the BREAK, the value in N will be the index into the array.

Format 3

For Loop, Array Indexing 

FOR [LOCAL] variable INDEX vararray {ALL} 
...
NEXT [variable] 

This format executes the logic immediately following the FOR by the number of times determined by the primary index of the array specified by vararray.

During each iteration of the FOR loop, the variable will be set to either the array index for each element if variable is numeric or the associated key for each array element if variable is a string. If you specify a string variable and no associated keys exist, the loop will not be executed.

(FOR array indexing was added in PxPlus v8.01, build 9181.)

Format 4

For Loop, Substring Parsing

FOR [LOCAL] strvar FROM string
...
NEXT [strvar]

This format executes the logic immediately following the FOR based on the number of substrings found within the value of string. The substrings are defined using the last character of string as a substring delimiter. As each substring is extracted from string, it will be placed into strvar. If string is a null string, the FOR loop is skipped.

Should the loop be prematurely exited (via BREAK, POP or EXITTO), the variable will remain at its last value; however, if the loop terminates due to all substrings being processed, the variable will be set to null.

Example 1:

input "Enter your country: ",C$
for X$ from "Canada,USA,France,UK,Germany,Australia,"
     if C$=X$ \
          then break
next
if not(nul(X$)) \
     then print "Country "+C$+" was found in the string." \
     else print "Unknown country"

Example 2 - To print all the fields in a record:

read record (file)R$
for FLD$ from R$
     print FLD$
next FLD$

Example 3 - To process all rows in a Grid:

grid find Grid_ctl,0,0,GridData$
for GridRow$ from GridData$
…
next

(FOR array substring parsing was added in PxPlus v8.01, build 9181.)

See Also

BREAK Immediate Exit of Loop
CONTINUE Initiates Next Iteration of Loop
EXITTO End Loop, Transfer Control
Structured Error Handling Using ON ERR