The *DO command opens a loop. It instructs the Pre-processor to process the text following, down to the corresponding *END command, a variable number of times, depending on the settings of the loop parameters, and to output the text, making any necessary substitutions, each time through the loop.

The form of the *DO command is:

[*DO x = AE : AE ]


[*DO x = AE : AE : AE]

where x is any index not currently in use as a loop index (used as the index of a loop previously opened by a *DO or *FOR command which has not yet been closed).

The first AE is the setting that x is to take on the first execution of the loop.

The second AE is the last setting of x for which the loop is to be executed.

The last AE is the value for which x is to be increased each time through the loop. If the last AE and its preceding colon are omitted, then an incremental value of 1 is assumed. So the command

[*do Loop = 1:3]

tells the Pre-processor to execute a loop three times, for values Loop=1, Loop=2 and Loop=3, while the command

[*do lpThisOne = 1:16:5]

generates four iterations, with lpThisOne=1, lpThisOne=6, lpThisOne=11 and lpThisOne=16.

All DO loops must execute at least once; so the second AE may not have a value less than the first unless the increment is negative. If the first AE has the same value as the second, the loop will execute once.

A loop index may not be reset (by a *SET, *DO or *FOR command) inside the loop. However, indices used or referenced in the loop parameters (on the right side of the equals sign) may be reset, as it is their values when the loop begins that are used in computing the parameters. At the end of the loop the index is unset automatically and may not be referenced again until it has been set again.

A loop continues until the *END command with the loop index is found, so a loop beginning [*do Region= ... ] continues until the command [*end Region] is found. Note that these two commands may appear on the same line.

You can use *LAST to prevent a loop from continuing after this iteration.

Loops may be nested - a loop within a loop is allowed - up to a depth of 20.

Loops may not overlap; so where a loop using lpLoopA is opened, followed by one using lpLoopB, [*end lpLoopB] must occur before [*end lpLoopA]. This applies to both [*DO ... ] loops and [*FOR ... ] loops.

Examples of valid *DO commands:

[*do lpFirst=1:5]

[*do lpFirstCol=1:36:5]

[*do lpWhich = 2:Last]

[*do lpLoop = First:First+Count:Step]

[*do lpWhichNow = 10,1,-1]