The FOR command provides a looping mechanism in GT.M. FOR does not generate an additional level in the M standard stack model.
The format of the FOR command is:
F[OR][lvn=expr[:numexpr1[:numexpr2]][,...]]]
Because FOR is a conditional command, it does not support a command postconditional.
The scope of the FOR is the remainder of the line. The scope of a FOR can be extended with DO (or XECUTE) commands.
When the FOR has no argument, at least two (2) spaces must follow the command to separate it from the next command on the line. This specifies a loop that must be terminated by a QUIT, HALT, GOTO, or ZGOTO.
The optional local variable name specifies a loop control variable delimited by an equal sign (=). A FOR command has only one control variable, even when it has multiple arguments.
When initiating the FOR, GT.M assigns the loop control variable the value of the expression. When only an initial value appears, GT.M executes the remainder of the line once for that argument without forcing the control variable to be numeric.
If the argument includes an increment and, optionally, a terminator, GT.M treats the initial expression as a number.
The optional numeric expression after the first colon (:) delimiter specifies the increment for each iteration. The FOR command does not increment the control variable on the first iteration.
The optional numeric expression after the second colon (:) delimiter specifies the limiting value for the control variable. This terminating expression is evaluated only when the control variable is initialized to the corresponding initial value, then used for all subsequent iterations.
GT.M does not execute the commands on the same line following the FOR if:
The increment is non-negative and the initial value of the control variable is greater than the limiting value.
The increment is negative and the initial value of the control variable is less than the limiting value.
After the first iteration, GT.M does not alter the control variable and ceases execution under the control of the FOR if:
The increment is non-negative, and altering the control variable by the increment would cause the control variable to be greater than the limiting value.
The increment is negative, and altering the control variable by the increment would cause the control variable to be less than the limiting value.
When the FOR has multiple arguments, each one affects the loop control variable in sequence. For an argument to gain control, no prior argument to the FOR can have an increment without a limit.
Increments and limits may be positive, negative, an integer, or a fraction. GT.M never increments a FOR control variable "beyond" a limit. Other commands may alter a control variable within the extended scope of a FOR that it controls. When the argument includes a limit, such modification can cause the FOR argument to yield control at the start of the next iteration, or, less desirably loop indefinitely.
NOUNDEF applies even in the case of an undefined FOR control variable, such as when a KILL or NEW command is used on the control variable, which may cause an unintended indefinite loop. For example, FOR A=1:1:10 KILL A results in an indefinite loop with VIEW "NOUNDEF".
GT.M terminates the execution of a FOR when it executes an explicit QUIT or a GOTO (or ZGOTO in GT.M) that appears on the line after the FOR. FOR commands with arguments that have increments without limits and argumentless FORs can be indefinite loops. Such FORs must terminate with a (possibly postconditional) QUIT or a GOTO within the immediate scope of the FOR. FORs terminated by such commands act as "while" or "until" control mechanisms. Also, such FORs can, but seldom, terminate by a HALT within the scope of the FOR as extended by DOs, XECUTEs, and extrinsics.
Example:
GTM>Kill i For i=1:1:5 Write !,i 1 2 3 4 5 GTM>Write i 5 GTM>
This FOR loop has a control variable, i, which has the value one (1) on the first iteration, then the value two (2), and so on, until in the last iteration i has the value five (5). The FOR terminates because incrementing i would cause it to exceed the limit. Notice that i is not incremented beyond the limit.
Example:
GTM>FOR x="hello",2,"goodbye" WRITE !,x hello 2 goodbye GTM>
This FOR loop uses the control variable x and a series of arguments that have no increments or limits. Notice that the control variable may have a string value.
Example:
GTM>For x="hello":1:-1 Write !,x GTM>ZWRite x x=0 GTM>
Because the argument has an increment, the FOR initializes the control variable x to the numeric evaluation of "hello" (0). Then, GT.M never executes the remainder of the line because the increment is positive, and the value of the control variable (0) initializes to greater than the limiting value (-1).
Example:
GTM>For y=-1:-3:-6,y:4:y+10,"end" Write !,y -1 -4 -4 0 4 end GTM>
This FOR uses two limited loop arguments and one value argument. The first argument initializes y to negative one (-1), then increments y to negative four (-4). Because another increment would cause y to be less than the limit (-6), the first argument terminates with y equal to negative four (-4). The second argument initializes the loop control variable to its current value and establishes a limit of six (6=-4+10). After two iterations, incrementing y again would cause it to be greater than the limit (6), so the second argument terminates with y equal to four (4). Because the final argument has no increment, the FOR sets y to the value of the third argument, and GT.M executes the commands following the FOR one more time.
Example:
GTM>Set x="" For Set x=$Order(ar(x)) Quit:x="" Write !,x
This example shows an argumentless FOR used to examine all first level subscripts of the local array ar. When $ORDER() indicates that this level contains no more subscripts, the QUIT with the postconditional terminates the loop.