|
<< Click to Display Table of Contents >> Navigation: Command Language > Preprocessor > Preprocessor loops |
Loops are used to repeat sections of code, usually with some changes each repeat.
The command used are *DO, *FOR, *END, *SLE, and *LAST.
See also database loops.
Loops can be nested to any depth. Loops inside other loops must be ended before the outer loop ends.
Loops must not overlap, only the last opened loop can be ended.
Loops should begin and end within the same CL script file, but other scripts can be inserted within loops.
All loops opened must be ended before the end of the CL script.
A loop index may not be reset by any command inside the loop.
At the end of the loop the index is unset automatically and may not be referenced again until it has been set again.
The *DO command opens a loop. It instructs the preprocessor 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 one of the following:
[*DO index = arithmetic : arithmetic ]
[*DO index = arithmetic: arithmetic: arithmetic]
The index is any index not currently in use for any special purpose.
The arithmetic settings are usually a constant, but can be an index, or a substitution, or a calculation, or an embedded command.
The first arithmetic is the setting that index is to take on the first execution of the loop.
The second arithmetic is the last setting of index for which the loop is to be executed.
The third arithmetic (if present) is the value for which index is to be increased each time through the loop. If the third arithmetic is not used, then an incremental value of 1 is assumed. So the command:
[*do Loop = 1:3]
tells the preprocessor 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.
A loop index may not be reset by any command inside the loop. If loop parameters (on the right side of the equals sign) are reset, it is their values when the loop begins that are used.
All *DO loops must execute at least once; so the second arithmetic may not have a value less than the first unless the increment is negative. If the first arithmetic has the same value as the second, the loop will execute once.
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]
The *FOR command opens a loop. It instructs the preprocessor to process the text following, down to the corresponding *END command, a variable number of times, depending on the number of loop parameters, and to output the text, making any necessary substitutions, each time through the loop.
The form of the *FOR command is:
[*FOR index = arithmetic : arithmetic ... : arithmetic ]
The index is any index not currently in use for any special purpose.
The arithmetic settings are usually a constant, but can be an index, or a substitution, or a calculation, or an embedded command.
The arithmetic settings specify the value index is to take each time through the loop. The number of times the loop is executed is the number of arithmetic settings specified.
There must be at least one arithmetic but you can use as many as you like and they do not have to be in numerical order.
The command:
[*for lpLoop = 1:17:24]
tells the preprocessor to process the lines following three times, with lpLoop=1, lpLoop=17 and lpLoop=24.
Examples of valid *FOR commands:
[*for lpProduct=1:17:76:41]
[*for lpWhich = Prime : Prime+3 : Prime+5 : Prime+21]
All loops begun with *DO or *FOR must end with a *END which contains the same index as was used to open the loop.
The *END command denotes the closing point of a loop opened by a *DO or a *FOR command. The form of the command is:
[*END index ]
where index is the index of the loop to be closed. This must always be the last loop opened.
At the end of the loop the index is unset automatically and may not be referenced again until it has been set again.
Examples of valid *END commands:
[*end lpLoop]
[*end lpThisYear]
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 in the CL script.
Used inside a loop this causes a skip to the end of the current loop on the last time through.
This command cannot be used with *DBLOOP and *DBEND but *LAST can be used.
Example of valid *SLE usage:
[*do lpNumber = 1:5] [Number] [*sle] , [*end lpNumber]
This generates "1,2,3,4,5". Not there is no comma after the 5.
You can use *LAST to prevent a loop from continuing after this iteration is complete.
This PP command forces this to be the last time round a named loop. This command has no effect until the *END command is reached.
The *LAST command will normally be skipped past using a *SKIP or *BLOCK command until it is needed.
Example:
[*do lpRound=33:99]
[*block 22 on lpRound.eq.34]
[*last lpRound]
[*22]
Line out [lpRound]
[*end lpRound]
will output two lines:
Line out 33
Line out 34
The *LAST command must refer to a valid loop index. It does not have to be the last opened loop where loops are nested.
[*do lpOuter=33:99]
[*do lpInner=1:3]
[*last lpOuter]
Line inside [lpOuter] [lpInner]
[*end lpInner]
Line outside [lpOuter]
[*end lpOuter]
will output four lines:
Line inside 33 1
Line inside 33 2
Line inside 33 3
Line outside 33
If *SLE is encountered for a loop after *LAST it will be used.
*LAST can also be used on a DBLOOP index. Command *SLE does not work with DBLOOP except when *LAST has been used.