.DO     DO if condition is true

Syntax:

        .DO  expression

See also:

.EL   .EM   .FI   .MA   .XM  

Function:

The .DO directive is one of the 3 directives used for conditional assembly. It can be used to include or exclude parts of the source code from the assembly processes depending on a test condition.

Boundary Sync:

In Version 3 of the SB-Assembler this directive will not perform a boundary sync.

Explanation:

If the expression evaluates to true (if its value is not 0) all following source lines will be assembled normally until the next .EL or .FI directive. If the expression evaluates to false (if its value is 0) the following source lines will not be assembled until the next .EL or .FI directive.

The .FI directive will end the conditional block that was started by the .DO directive, regardless of whether the expression evaluated to true or false.
The true/false condition can be reversed by the .EL directive as often as necessary.

The .DO, the .EL and .FI directives can be compared with IF, ELSE and ENDIF in other languages. Remember that the conditional directives control the assembler and not the target processor! They can not be used to let the target system compare values or make other decisions. The target system is unaware of the conditions used during assembly. In fact, only the lines which were surrounded by a true condition will end up in the target file. The target system will never see lines embedded in a false condition.

The expression must evaluate completely and may not contain any forward referenced labels. The .DO directive insists on knowing the condition and that is not possible if one of the labels in an expression is not defined yet.

Conditional assembly can be nested. This means that a .DO .FI block may contain other .DO .FI blocks. This nesting may go on, up to 255 levels deep. If that should not be enough for your application I suggest you get your head examined.
Version 3 of the SB-Assembler doesn't even have a (sensible) maximum nesting level.

The listing of conditionally excluded source lines can be controlled with the .LI directive. If the .LI CON mode is selected all source lines are listed, regardless of the condition. Lines that are not assembled are marked with the word SKIP in the line number column. With Version 3 of the SB-Assembler the letter 'S' is prefixed in front of the line numbers.
If the .LI COFF mode is selected the skipped lines are not listed at all.

The syntax of skipped lines due to a false condition is not checked. During a false condition the assembler will only look for .DO, .EL and .FI directives in the instruction field.
Labels are not allowed on lines containing any of the conditional directives .DO, .EL and .FI.

Examples:

          .CR  Z80            Load the Z80 Cross Overlay
          .DO  VALUE1>VALUE2
;                             These lines are assembled if
;                              VALUE1 is greater than VALUE 2
          NOP
          .EL                 Reverse condition
;                             These lines are not assembled
;                              if VALUE1 is greater than
;                              VALUE2
          NOP
          .FI                 End of conditional block

          .DO  VALUE1>VALUE2
          .DO  ?=0
;                             Condition nested 2 levels deep
;                             These lines are assembled if
;                              VALUE1 is greater than VALUE2
;                              and if we are in pass 1 of the
;                              assembly process (?)
          .FI                 End of 2nd condition (pass 1)
;                             These lines are assembled if
;                              VALUE1 is greater than VALUE2,
;                              regardless of the pass we're in.
          .FI                 First conditional is ended

          .DO  0              Condition is never true!
;                             This line will never be
;                              assembled
          .DO  1              This nested .DO is not evaluated
;                             because the previous .DO is always
;                             false.
;                             This line is never assembled
;                             The value of the expression
;                              doesn't matter for the .DO
;                              is not evaluated anyway.
          .FI                 Nested .DO block ended
;                             This line is still not assembled
          .FI                 Closing outer .DO block
;                             This line is assembled again

; You can invert the condition using .EL as often as you like.
          .DO   1             Condition is true!
          NOP                 This line is assembled
          .EL                 Reverse condition to false!
          NOP                 This line is not assembled
          .EL                 Reverse condition to true again!
          NOP                 This line is assembled again
          .FI                 End of conditional assembly