bdfs1m0wStructured Programming Macros

#DO Macro Group

Use this macro group to process specific code based on one of the following:

The #DO macro group includes the following macros:

See #DO Macro Group Processing for diagrams that show the processing flow of the #DO macro group.

Format




Notes:

  1. A #DO statement can contain one of each of the WHILE, UNTIL, TIMES, and FROM conditions.




#DO
specifies the start of the #DO structure.

WHILE
specifies the start of a #DO WHILE loop based on a conditional expression. Any code that follows this parameter is processed only if and while the conditional expression is true. See Conditional Expression Format for information about the syntax of a conditional expression.

UNTIL
specifies the start of a #DO UNTIL loop based on a conditional expression. Any code that follows this parameter is processed at least once and is repeated until the conditional expression is true. See Conditional Expression Format for information about the syntax of a conditional expression.

TIMES
specifies the number of times to repeat the loop. Any code that follows this parameter is repeated based on a loop counter.

FROM
specifies the number of times to repeat the loop. Any code that follows this parameter is repeated based on a loop counter.

The form of #DO FROM using a BC or BCR loop is the basic form. The form of #DO FROM using a BXH or BXLE loop allows values to be saved during the processing of the loop. The type of loop generated depends on the following:

Note:
#DO FROM is only available for compatibility with older applications. Use the #DO TIMES form for new applications.

INF
specifies an unconditional loop. You must code a #DOEX or #EXIF macro to avoid creating an infinite loop.

ONCE
creates a non-loop where the processing is performed only once. This parameter allows you to use the conditional branching macros (#EXIF, #DOEX, and so on) to construct a procedure that is processed the same way as inline code.

reg1
is a register that contains the loop counter. When you specify the TIMES parameter, the value in reg1 must be positive.

initval
is an initial value for the loop counter that gets loaded into the register specified by reg1.

The value of initval can be:

You can enter an address in one of the following ways:

In both cases, the initial value is the address of label label.

You can enter labels in one of the following ways:

reg2
is the branch register. If you specify reg2 with the TIMES parameter, a BCTR loop is generated. If you do not specify reg2 with the TIMES parameter, a BCT loop is generated. If you specify reg2 with the FROM parameter, a BCR loop is generated. If you do not specify reg2 with the FROM parameter, a BC loop is generated.

save1
is a fullword area where reg1 is saved. This allows reg1 to be used during the execution of the loop. If you specify save1 with the TIMES parameter, a BCT loop is generated.

BY=byval
specifies the value with which to increment reg1, where byval is the value. This value is added to the value in reg1 at the end of each iteration.

The valid values for byval are the same as for initval, with the exception of single-byte fields or single-byte literals.

TO=toval
specifies when to end the loop, where toval is a field that contains the ending value for the loop. The value in toval is compared with the value in reg1 at the end of each iteration.

The valid values for toval are the same as for initval, with the exception of single-byte fields or single-byte literals.

INCLUSIVE
processes the loop including the ending value, toval.

EXCLUSIVE
processes the loop excluding the ending value, toval.

BXLE
specifies a BXLE loop.

BXH
specifies a BXH loop.

BY=byreg
specifies the increment value, where byreg is a register that contains the value with which to increment reg1.

byval2
is an initial increment value to load into the register specified by byreg.

save2
is a full or double word save area into which byreg and toreg are saved. They are stored at the beginning of each iteration and reloaded at the end of each iteration before the BXLE or BXH loop. Only 1 fullword is required during the loop processing if byreg and toreg are the same odd-numbered register.

TO=toreg
specifies when to end the loop, where toreg is a register that contains the ending value for the loop, where:

toval2
is an initial value to load in toreg.

PREFIX=label
specifies a prefix for all link labels generated by this macro group, where label is a 4-character alphabetic name.

code1
is the code to process.

#EXIF
specifies the start of the exit code to process when the conditional expression is true. See Conditional Expression Format for information about the syntax of a conditional expression. After the exit code is performed, processing exits from the whole #DO group. If the conditional expression is false, #EXIF branches to the next #OREL macro.

code2
is the exit code to process when the #EXIF condition is true. The exit code consists of any code between the #EXIF macro and the next sequential #OREL macro.

#OREL
specifies the start of the code to process when the previous #EXIF condition is not true. After the code is processed, control returns to the top of the loop and processing continues.

For clarity, it is recommended that you always code a matching #OREL macro for each #EXIF macro. However, if you do not specify the #OREL macro, it will be automatically generated between a #EXIF macro and any of the following:

code3
is the code to process when the previous #EXIF condition is false.

#DOEX
exits from the loop based on a conditional expression. See Conditional Expression Format for information about the syntax of a conditional expression. If the conditional expression is true, #DOEX branches to the #ELOP macro. If the #ELOP macro is not specified, processing branches to the #EDO macro.
Note:
The #DOEX macro provides a conditional exit from the iteration loop. This optional exit is a violation of structured programming rules. Restrict the use of this macro to special cases where you would otherwise have to:
  • Use a #GOTO macro. See #GOTO Macro Group for more information about the #GOTO macro.
  • Set and test an additional indicator.

code4
is the code to process when the #DOEX condition is false.

#ELOP
ends the iteration loop and specifies the start of any code to be processed at the end of the loop. The #ELOP macro must be the last structured programming macro (SPM) in the #DO group before the #EDO macro. If you do not specify the #ELOP macro, it is automatically generated by the #EDO macro.

code5
is the code to process at the end of the loop. This code is processed only once when the iteration loop ends. This code is bypassed only when the iteration is ended by a true #EXIF condition.

#EDO
specifies the end of the loop-end processing and the whole #DO group.

Entry Requirements

None.

Return Conditions

Control is returned to the next sequential instruction after the #EDO macro statement unless another assembler instruction or macro passes control outside the #DO structure.

Programming Considerations

Examples

Related Macros

#EXEC-Execute Macro.