.XM     eXit Macro

Syntax:

        .XM  [expression]

See also: Macros .DO .EL .EM .FI .MA

Function:

The .XM directive prematurely exits an expanding Macro. This premature exit can be caused conditionally or unconditionally.

Boundary Sync:

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

Explanation:

If the optional expression is omitted the .XM directive will prematurely exit the expanding Macro. If the expression is given the expanding Macro will be terminated when the expression evaluates to be true, i.e. unequal to 0.

The expression may not contain any forward referenced labels. The expression must follow the .XM directive within 9 or 10 spaces, otherwise it is treated as comment.

The unconditional exit is normally only used in co-operation with conditional assembly directives .DO, .EL and .FI. Without any of these conditional directives the use of an unconditional .XM does not make much sense.
This presents us with a little problem. If the condition is started inside the Macro, which it usually is, then the .XM directive will immediately terminate the Macro. Therefore the .FI directive, which is also part of the Macro, will never be executed. This results in a corrupted conditional stack which holds all pending true and false conditions. That is why the .XM directive will pop one condition from the condition stack, like the .FI directive would have done.
Please note that the .FI directive itself is still required to terminate the conditional part correctly in case the condition was not true! The .FI directive normally must directly follow the unconditional .XM directive in your source file. Any instructions between those two directives would never be interpreted anyway, the condition behind the .XM directive is false, remember.

A detailed description of the Macro capabilities of the SB-Assembler can be found in a separate chapter.

Examples:

The following example shows us a Macro that can push up to 3 registers on the processors stack. You can expand the Macro to handle even more than 3 registers yourself.

1   PUSH      .MA    reg1,reg2,reg3
2             PUSH   ]1        ; Push register 1 on the stack
3             .XM    ]#=1      ; Done if only 1 parameter
4             PUSH   ]2        ; Push register 2 on the stack
5             .XM    ]#=2      ; Done if only 2 parameters
6             PUSH   ]3        ; Push register 3 on the stack
7             .EM
8
9   TEST      >PUSH ACC,PCL,PCH
M1            PUSH  ACC
M2            .XM   3=1
M3            PUSH  PCL
M4            .XM   3=2
M5            PUSH  PCH
10
11            >PUSH ACC
M1            PUSH  ACC
M2            .XM   1=1
12
13            >PUSH B,ACC
M1            PUSH  B
M2            .XM   2=1
M3            PUSH  ACC
M4            .XM   2=2
14            NOP           Rest of the program