2 @node Conditionals and Looping
3 @chapter Conditional and Looping Constructs
6 @cindex flow of control
9 This chapter documents @pspp{} commands used for conditional execution,
10 looping, and flow of control.
13 * BREAK:: Exit a loop.
14 * DO IF:: Conditionally execute a block of code.
15 * DO REPEAT:: Textually repeat a code block.
16 * LOOP:: Repeat a block of code.
27 @cmd{BREAK} terminates execution of the innermost currently executing
30 @cmd{BREAK} is allowed only inside @cmd{LOOP}@dots{}@cmd{END LOOP}.
31 @xref{LOOP}, for more details.
48 @cmd{DO IF} allows one of several sets of transformations to be
49 executed, depending on user-specified conditions.
51 If the specified boolean expression evaluates as true, then the block
52 of code following @cmd{DO IF} is executed. If it evaluates as
54 none of the code blocks is executed. If it is false, then
55 the boolean expression on the first @cmd{ELSE IF}, if present, is tested in
56 turn, with the same rules applied. If all expressions evaluate to
57 false, then the @cmd{ELSE} code block is executed, if it is present.
59 When @cmd{DO IF} or @cmd{ELSE IF} is specified following @cmd{TEMPORARY}
60 (@pxref{TEMPORARY}), the @cmd{LAG} function may not be used
68 DO REPEAT dummy_name=expansion@dots{}.
72 expansion takes one of the following forms:
78 num_or_range takes one of the following forms:
83 @cmd{DO REPEAT} repeats a block of code, textually substituting
84 different variables, numbers, or strings into the block with each
87 Specify a dummy variable name followed by an equals sign (@samp{=})
88 and the list of replacements. Replacements can be a list of existing
89 or new variables, numbers, strings, or @code{ALL} to specify all
90 existing variables. When numbers are specified, runs of increasing
91 integers may be indicated as @code{@var{num1} TO @var{num2}}, so that
92 @samp{1 TO 5} is short for @samp{1 2 3 4 5}.
94 Multiple dummy variables can be specified. Each
95 variable must have the same number of replacements.
97 The code within @cmd{DO REPEAT} is repeated as many times as there are
98 replacements for each variable. The first time, the first value for
99 each dummy variable is substituted; the second time, the second value
100 for each dummy variable is substituted; and so on.
102 Dummy variable substitutions work like macros. They take place
103 anywhere in a line that the dummy variable name occurs. This includes
104 command and subcommand names, so command and subcommand names that
105 appear in the code block should not be used as dummy variable
106 identifiers. Dummy variable substitutions do not occur inside quoted
107 strings, comments, unquoted strings (such as the text on the
108 @cmd{TITLE} or @cmd{DOCUMENT} command), or inside @cmd{BEGIN
109 DATA}@dots{}@cmd{END DATA}.
111 Substitution occurs only on whole words, so that, for example, a dummy
112 variable PRINT would not be substituted into the word PRINTOUT.
114 New variable names used as replacements are not automatically created
115 as variables, but only if used in the code block in a context that
116 would create them, e.g.@: on a @cmd{NUMERIC} or @cmd{STRING} command
117 or on the left side of a @cmd{COMPUTE} assignment.
119 Any command may appear within @subcmd{DO REPEAT}, including nested @subcmd{DO REPEAT}
120 commands. If @cmd{INCLUDE} or @cmd{INSERT} appears within @subcmd{DO REPEAT},
121 the substitutions do not apply to the included file.
123 If @subcmd{PRINT} is specified on @cmd{END REPEAT}, the commands after substitutions
124 are made are printed to the listing file, prefixed by a plus sign
132 LOOP [@var{index_var}=@var{start} TO @var{end} [BY @var{incr}]] [IF @var{condition}].
134 END LOOP [IF @var{condition}].
137 @cmd{LOOP} iterates a group of commands. A number of
138 termination options are offered.
140 Specify index_var to make that variable count from one value to
141 another by a particular increment. @var{index_var} must be a pre-existing
142 numeric variable. @var{start}, @var{end}, and @var{incr} are numeric expressions
143 (@pxref{Expressions}.)
145 During the first iteration, @var{index_var} is set to the value of @var{start}.
146 During each successive iteration, @var{index_var} is increased by the value of
147 @var{incr}. If @var{end} > @var{start}, then the loop terminates
148 when @var{index_var} > @var{end};
149 otherwise it terminates when @var{index_var} < @var{end}. If @var{incr} is not specified
150 then it defaults to +1 or -1 as appropriate.
152 If @var{end} > @var{start} and @var{incr} < 0, or if @var{end} < @var{start} and
153 @var{incr} > 0, then the
154 loop is never executed. @var{index_var} is nevertheless set to the value of
157 Modifying @var{index_var} within the loop is allowed, but it has no effect on
158 the value of @var{index_var} in the next iteration.
160 Specify a boolean expression for the condition on @cmd{LOOP} to
161 cause the loop to be executed only if the condition is true. If the
162 condition is false or missing before the loop contents are executed the
163 first time, the loop contents are not executed at all.
165 If index and condition clauses are both present on @cmd{LOOP}, the
166 index variable is always set before the condition is evaluated. Thus,
167 a condition that makes use of the index variable will always see the
168 index value to be used in the next execution of the body.
170 Specify a boolean expression for the condition on @cmd{END LOOP} to cause
171 the loop to terminate if the condition is true after the enclosed
172 code block is executed. The condition is evaluated at the end of the
173 loop, not at the beginning, so that the body of a loop with only a
174 condition on @cmd{END LOOP} will always execute at least once.
176 If neither the index clause nor either condition clause is
177 present, then the loop is executed @var{max_loops} (@pxref{SET}) times.
178 The default value of @var{max_loops} is 40.
180 @cmd{BREAK} also terminates @cmd{LOOP} execution (@pxref{BREAK}).
182 Loop index variables are by default reset to system-missing from one
183 case to another, not left, unless a scratch variable is used as index.
184 When loops are nested, this is usually undesired behavior, which can
185 be corrected with @cmd{LEAVE} (@pxref{LEAVE}) or by using a scratch
186 variable as the loop index.
188 When @cmd{LOOP} or @cmd{END LOOP} is specified following @cmd{TEMPORARY}
189 (@pxref{TEMPORARY}), the @cmd{LAG} function may not be used