## The Assembler Description

### ... General Assembler Directives

####

       An  ASxxxx  directive  is placed in the operator field of the
    source line.  Only one directive is  allowed  per  source  line.
    Each  directive  may  have  a blank operand field or one or more
    operands.  Legal operands differ with each directive.

`

- .module Directive
- .title Directive
- .sbttl Directive
- .list and .nlist Directives
- .page Directive
- .msg Directive
- .error Directive
- .byte, .db, and .fcb Directives
- .word, .dw, and .fdb Directives
- .3byte and .triple Directives
- .dl, .long, .4byte and .quad Directives
- .blkb, .ds, .rmb, and .rs Directives
- .blkw, .blkl, .blk3, and .blk4 Directives
- .ascii, .fcc, and .str Directives
- .ascis and .strs Directives
- .asciz and .strz Directives
- Non-Printing Characters In Strings
- .assume Directive
- .radix Directive
- .even Directive
- .odd Directive
- .bndry Directive
- .area Directive
- .psharea and .poparea Directives
- .bank Directive
- .org Directive
- .globl Directive
- .local Directive
- .equ, .gblequ, and .lclequ Directives
- .if, .else, and .endif Directives
- .iff, .ift, and .iftf Directives
- .ifxx Directive
- .ifdef Directive
- .ifndef Directive
- .ifb Directive
- .ifnb Directive
- .ifidn Directive
- .ifdif Directive
- Alternate .if Directive Forms
- Immediate Conditional Assembly Directives
- .include Directive
- .incbin Directive
- .define and .undefine Directives
- .enabl and .dsabl Directives
- .setdp Directive
- .16bit, .24bit, and .32bit Directives
- .msb Directive
- .lohi and .hilo Directives
- .trace and .ntrace Directives
- .end Directive
- Return to the Assembler Index

`

####

    .module Directive

    Format:

            .module name

       The  .module  directive causes the name to be included in the
    assemblers output file as an identifier for this particular  ob-
    ject module.  The name may be from 1 to 79 characters in length.
    The name may not have any embedded white space (spaces or tabs).
    Only  one  identifier is allowed per assembled module.  The main
    use of this directive  is  to  allow  the  linker  to  report  a
    modules'  use  of undefined symbols.  At link time all undefined
    symbols are  reported  and  the  modules  referencing  them  are
    listed.

##### => Section Index

####

    .title Directive

    Format:

            .title  string

       The .title directive provides a character string to be placed
    on the second line of each page during listing.  The string  be-
    gins  with  the first non white space character (after any space
    or tab) and ends with the end of the line.

##### => Section Index

####

    .sbttl Directive

    Format:

            .sbttl  string

       The .sbttl directive provides a character string to be placed
    on the third line of each page during listing.  The  string  be-
    gins  with  the first non white space character (after any space
    or tab) and ends with the end of the line.

##### => Section Index

####

    .list and .nlist Directives

    Format:

            .list                           ;Basic .list

            .list   expr                    ;with expression

            .list   (arg1,arg2,...,argn)    ;with sublist options

            .nlist                          ;Basic .nlist

            .nlist  expr                    ;with expression

            .nlist  (arg1,arg2,...,argn)    ;with sublist options

    The  .list  and  .nlist directives control the listing output to
    the .lst  file.   The  directives  have  the  following  sublist
    options:

            err     -       errors
            loc     -       program location
            bin     -       binary output
            eqt     -       symbol or .if evaluation
            cyc     -       opcode cycle count
            lin     -       source line number
            src     -       source line text
            pag     -       pagination
            lst     -       .list/.nlist line listing
            md      -       macro definition listing
            me      -       macro expansion listing
            meb     -       macro expansion binary only listing
            mel     -       macro expansion binary with source

            !       -       sets the listing mode to
                            !(.list) or !(.nlist) before
                            applying the sublist options

    The  'normal' listing mode .list is the combination of err, loc,
    bin, eqt, cyc, lin, src, pag, lst, and md enabled with me,  meb,
    and mel disabled.  The 'normal' listing mode .nlist has all sub-
    list items disabled.  When specifying sublist options the option
    list  must  be  enclosed within parenthesis and multiple options
    separated by commas.

       The NOT option, !, is used to set the listing mode to the op-
    posite of the .list or .nlist directive before applying the sub-
    list options.  For example:

            .nlist  (!)     is equivalent to .list  and
            .list   (!)     is equivalent to .nlist
                            any additional options will
                            be applied normally

       Normal  .list/.nlist processing is disabled within false con-
    ditional blocks.  However, the .list/.nlist with  an  expression
    can  override  this  behavior  if  the expression has a non zero
    value.

       Examples of listing options:

            .list   (me)    ; listing options are enabled
                            ; during macro processing

            .list   (meb)   ; macro processing forces listing
                            ; of generated binary and location

            .list   (mel)   ; macro processing forces listing
                            ; of generated binary and location
                            ; plus any other enabled listing

            .nlist  (src)   ; .nlist src lines not listed

            .nlist  (!,lst) ; list all except .nlist

            .nlist          ; combination lists only
            .list   (src)   ; the source line

            .list   (!,src) ; list only the source line

            .list   1       ; enable listing even within
                            ; a FALSE conditional block

##### => Section Index

####

    .page Directive

    Format:

            .page

       The .page directive causes a page ejection with a new heading
    to be printed.  The new page occurs after the next line  of  the
    source  program is processed, this allows an immediately follow-
    ing .sbttl directive to appear  on  the  new  page.   The  .page
    source  line will not appear in the file listing.  Paging may be
    disabled by invoking the -p directive or by using the directive:

            .nlist  (pag)

       If  the .page directive is followed by a non zero constant or
    an expression that evaluates to a non zero value then pagination
    will be enabled within a false condition range to allow extended
    textual information to be incorporated  in  the  source  program
    with out the need to use the comment delimiter (;):

            .if     0

            .page   1       ;Enable pagination within 'if' block.
            This text will be bypassed during assembly
            but appear in the listing file.
            .
            .
            .

            .endif

##### => Section Index

####

    .msg Directive

    Format:

            .msg     /string/               or

            .msg    ^/string/

    where:  string  represents a text string.  The string is printed
                    to the console during the final assembly pass.

            /  /    represent   the  delimiting  characters.   These
                    delimiters   may   be   any   paired    printing
                    characters,  as  long  as the characters are not
                    contained within  the  string  itself.   If  the
                    delimiting  characters  do  not  match, the .msg
                    directive will give the <q> error.

       The  .msg  directive  is  useful to report assembly status or
    other information during the assembly process.

##### => Section Index

####

    .error Directive

    Format:

            .error exp

    where:  exp     represents   an  absolute  expression.   If  the
                    evaluation of the expression results  in  a  non
                    zero value then an <e> error is reported and the
                    text line is listed in the generated error.

       The  .error  directive  is  useful to report configuration or
    value errors during the assembly process.  (The .error directive
    is  identical in function to the .assume directive, just perhaps
    more descriptive.)

##### => Section Index

####

    .byte, .db, and .fcb Directives

    Format:

            .byte   exp             ;Stores the binary value
            .db     exp             ;of the expression in the
            .fcb    exp             ;next byte.

            .byte   exp1,exp2,expn  ;Stores the binary values
            .db     exp1,exp2,expn  ;of the list of expressions
            .fcb    exp1,exp2,expn  ;in successive bytes.

    where:  exp,    represent expressions that will be
            exp1,   truncated to 8-bits of data.
            .       Each expression will be calculated,
            .       the high-order byte will be truncated.
            .       Multiple expressions must be
            expn    separated by commas.

       The  .byte, .db, or .fcb directives are used to generate suc-
    cessive bytes of binary data in the object module.

##### => Section Index

####

    .word, .dw, and .fdb Directives

    Format:

            .word   exp             ;Stores the binary value
            .dw     exp             ;of the expression in
            .fdb    exp             ;the next word.

            .word   exp1,exp2,expn  ;Stores the binary values
            .dw     exp1,exp2,expn  ;of the list of expressions
            .fdb    exp1,exp2,expn  ;in successive words.

    where:  exp,    represent expressions that will occupy two
            exp1,   bytes of data. Each expression will be
            .       calculated as a 16-bit word expression.
            .       Multiple expressions must be
            expn    separated by commas.

       The  .word, .dw, or .fdb directives are used to generate suc-
    cessive words of binary data in the object module.

##### => Section Index

####

    .3byte and .triple Directive

    Format:

            .3byte  exp             ;Stores the binary value
            .triple exp             ;of the expression in
                                    ;the next triple (3 bytes).

            .3byte  exp1,exp2,expn  ;Stores the binary values
            .triple exp1,exp2,expn  ;of the list of expressions
                                    ;in successive triples
                                    ;(3 bytes).

    where:  exp,    represent expressions that will occupy three
            exp1,   bytes of data. Each expression will be
            .       calculated as a 24-bit word expression.
            .       Multiple expressions must be
            expn    separated by commas.

       The  .3byte  or .triple directive is used to generate succes-
    sive triples of binary data in the object module.  (These direc-
    tives   are  only  available  in  assemblers  supporting  24-bit
    addressing.)

##### => Section Index

####

    .dl, .long, .4byte, and .quad Directives

    Format:

            .dl     exp             ;Stores the binary value
            .long   exp             ;of the expression in
            .4byte  exp             ;the next quad (4 bytes).
            .quad   exp

            .dl     exp1,exp2,expn  ;Stores the binary values
            .long   exp1,exp2,expn  ;of the list of expressions
            .4byte  exp1,exp2,expn  ;in successive quads
            .quad   exp1,exp2,expn  ;(4 bytes).

    where:  exp,    represent expressions that will occupy three
            exp1,   bytes of data. Each expression will be
            .       calculated as a 32-bit word expression.
            .       Multiple expressions must be
            expn    separated by commas.

       The .dl, .long, .4byte or .quad directive is used to generate
    successive quads of binary data in the  object  module.   (These
    directives  are  only  available in assemblers supporting 32-bit
    addressing.)

##### => Section Index

####

    .blkb, .ds, .rmb, and .rs Directives

    Format:

            .blkb   N       ;reserve N bytes of space
            .ds     N       ;reserve N bytes of space
            .rmb    N       ;reserve N bytes of space
            .rs     N       ;reserve N bytes of space

       The  .blkb, .ds, .rmb, and .rs directives reserve byte blocks
    in the object module;

##### => Section Index

####

    .blkw, .blkl, .blk3, and .blk4 Directives

    Format:

            .blkw   N       ;reserve N words of space
            .blkl   N       ;reserve N quads of space
            .blk3   N       ;reserve N triples of space
            .blk4   N       ;reserve N quads of space

       The .blkw directive reserves word blocks;  the .blk3 reserves
    3  byte  blocks(available  in   assemblers   supporting   24-bit
    addressing);  the .blkl and .blk4 reserves 4 byte blocks (avail-
    able in assemblers supporting 32-bit addressing).

##### => Section Index

####

    .ascii, .fcc and .str Directives

    Format:

            .ascii   /string/               or

            .ascii  ^/string/

            .fcc     /string/               or

            .fcc    ^/string/

            .str     /string/               or

            .str    ^/string/

    where:  string  is a string of printable ascii characters.

            /  /    represent   the  delimiting  characters.   These
                    delimiters   may   be   any   paired    printing
                    characters,  as  long  as the characters are not
                    contained within  the  string  itself.   If  the
                    delimiting  characters  do not match, the .ascii
                    directive will give the <q> error.

    The  .ascii,  .fcc, and .str directives place one binary byte of
    data for each character in the string into the object module.

##### => Section Index

####

    .ascis and .strs Directives

    Format:

            .ascis   /string/               or

            .ascis  ^/string/

            .strs    /string/               or

            .strs   ^/string/

    where:  string  is a string of printable ascii characters.

            /  /    represent   the  delimiting  characters.   These
                    delimiters   may   be   any   paired    printing
                    characters,  as  long  as the characters are not
                    contained within  the  string  itself.   If  the
                    delimiting  characters  do not match, the .ascis
                    and .strs directives will give the <q> error.

       The .ascis and .strs directives place one binary byte of data
    for each character in the string into the  object  module.   The
    last character in the string will have the high order bit set.

##### => Section Index

####

    .asciz and .strz Directives

    Format:

            .asciz   /string/               or

            .asciz  ^/string/

            .strz    /string/               or

            .strz   ^/string/

    where:  string  is a string of printable ascii characters.

            /  /    represent   the  delimiting  characters.   These
                    delimiters   may   be   any   paired    printing
                    characters,  as  long  as the characters are not
                    contained within  the  string  itself.   If  the
                    delimiting  characters  do not match, the .asciz
                    and .strz directive will give the <q> error.

       The .asciz and .strz directives place one binary byte of data
    for each character in the string into the object  module.   Fol-
    lowing  all  the  character data a zero byte is inserted to ter-
    minate the character string.

##### => Section Index

####

    Non-Printing Characters In Strings

       Non-printing  characters  can  be inserted into any string by
    enclosing the non-printing characters' value in  parenthesis  as
    shown in the following example.

    .asciz  /Hello World!/(13)(10)

    A  carriage return and line feed character have been appended to
    the string "Hello World!".  The  non-printing  character  values
    are  always  evaluated  in  the current radix (or in a temporary
    radix when specified.) The character  values  may  be  evaluated
    from  any legal expression and are truncated to 8-bit values be-
    fore being inserted into the character string.

       It   should  be  noted  that  multiple  string  segments  and
    non-printing character segments can  be  included  in  a  single
    string statemment:

    .asciz  /I Said:/(13)(10)/Hello World!/(13)(10)

##### => Section Index

####

    .assume Directive

    Format:

            .assume exp

    where:  exp     represents   an  absolute  expression.   If  the
                    evaluation of the expression results  in  a  non
                    zero value then an <e> error is reported and the
                    text line is listed in the generated error.

       The  .assume  directive  is useful to check assumptions about
    assembler values.  (The .assume directive is identical in  func-
    tion to the .error directive, just perhaps more descriptive.)

##### => Section Index

####

    .radix Directive

    Format:

            .radix  character

    where:  character  represents  a single character specifying the
            default radix to be used for  succeeding  numbers.   The
            character may be any one of the following:

                    B,b     Binary

                    O,o     Octal
                    Q,q

                    D,d     Decimal
                    'blank'

                    H,h     Hexidecimal
                    X,x

##### => Section Index

####

    .even Directive

    Format:

            .even

       The .even directive ensures that the current location counter
    contains an even boundary value by adding 1 if the current loca-
    tion is odd.

##### => Section Index

####

    .odd Directive

    Format:

            .odd

       The  .odd directive ensures that the current location counter
    contains an odd boundary value by adding one if the current  lo-
    cation is even.

##### => Section Index

####

    .bndry Directive

    Format:

            .bndry  n

       If  the current location is not an integer multiple of n then
    the location counter is increased to the next  integer  multiple
    of n.

       As an example:

            .bndry  4

    changes  the current location to be at a multiple of 4, a 4-byte
    boundary.

       The boundary specifications are propagated to the linker as a
    boundary modulus, ie the smallest common boundary for all  .odd,
    .even, and .bndry directives contained within the area.  A boun-
    dary value of 1 is equivalent to .odd and a boundary value of  2
    is equivalent to .even.  Because areas are always assembled with
    an initial address of 0, an even address, both  .odd  and  .even
    are modulus 2 boundaries.

       As  an  example, suppose there are two sections:  a CODE sec-
    tion and a DATA section.  The program code is  written  so  that
    the  data  associated with this section of the program code fol-
    lows immediately.

                    .area   CODE
                    ; Subroutine 1 Code
                    ; Uses data having a boundary of 6

                    .area   DATA
                    ; Subroutine 1 Data
                    .bndry  6
                    .word   1, 2, 3

                    ...

                    .area   CODE
                    ; Subroutine 2 Code
                    ; Uses data having a boundary of 8

                    .area   DATA
                    ; Subroutine 2 Data
                    .bndry  8
                    .word   1, 2, 3, 4,

       Since  the CODE and DATA sections are assembled during a sin-
    gle assembly (also applies to include files) the  the  assembler
    compiles all CODE segments as a single area segment.  The assem-
    bler also compiles all the DATA segments as a single  area  seg-
    ment  which  has  two .bndry directives and will have a boundary
    modulus of 24.  24 is the smallest boundary divisible by 6 and 8
    with  no remainder.  When the assembled file is linked the loca-
    tion of the data in the DATA area will be offset to  an  address
    which has a boundary modulus of 24.

       When  multiple files containing the same area names (projects
    with multiple independently compiled files or library files) are
    linked  together  each  area segment will be offset to match the
    segments boundary modulus.

       Boundary  specifications  will also be preserved when an area
    base address is specified with the -a linker option  and/or  the
    area is placed within a bank.

##### => Section Index

####

    .area Directive

    Format:

            .area   name    [(options)]

    where:  name    represents the symbolic name of the program sec-
                    tion.   This  name  may  be  the  same  as   any
                    user-defined  symbol  or  bank as the area names
                    are independent  of  all  symbols,  labels,  and
                    banks.

            options specify the type of program or data area:
                    ABS     absolute (automatically invokes OVR)
                    REL     relocatable
                    OVR     overlay
                    CON     concatenate
                    NOPAG   non-paged area
                    PAG     paged area

            options specify a code or data segment:
                    CSEG    Code segment
                    DSEG    Data segment

            option  specifies the data area bank:
                    BANK    Named collection of areas

       The .area directive provides a means of defining and separat-
    ing multiple programming and data sections.   The  name  is  the
    area  label used by the assembler and the linker to collect code
    from various separately assembled modules into one section.  The
    name may be from 1 to 79 characters in length.

       The options are specified within parenthesis and separated by
    commas as shown in the following example:

            .area  TEST  (REL,CON)  ;This section is relocatable
                                    ;and concatenated with other
                                    ;sections of this program area.

            .area  DATA  (REL,OVR)  ;This section is relocatable
                                    ;and overlays other sections
                                    ;of this program area.

            .area  SYS   (ABS,OVR)  ;(CON not allowed with ABS)
                                    ;This section is defined as
                                    ;absolute. Absolute sections
                                    ;are always overlayed with
                                    ;other sections of this program
                                    ;area.

            .area  PAGE  (PAG)      ;This is a paged section. The
                                    ;section must be on a 256 byte
                                    ;boundary and its length is
                                    ;checked by the linker to be
                                    ;no larger than 256 bytes.
                                    ;This is useful for direct page
                                    ;areas.

       The  default  area type is REL|CON;  i.e.  a relocatable sec-
    tion which is concatenated with other sections of code with  the
    same area name.  The ABS option indicates an absolute area.  The
    OVR and CON options indicate if program  sections  of  the  same
    name  will overlay each other (start at the same location) or be
    concatenated with each other (appended to each other).

       The  area can be specified as either a code segment, CSEG, or
    a data segment, DSEG.  The CSEG and DSEG descriptors are  useful
    when  the  microprocessor  code  and  data  unit allocations are
    unequal:  e.g.  the executable code  uses  an  allocation  of  2
    bytes for each instruction and is addressed at an increment of 1
    for every instruction, and the data uses an allocation of 1 byte
    for  each element and is addressed at an increment of 1 for each
    data byte.  The allocation units are defined by the architecture
    of the particular microprocessor.

       The  .area  directive also provides a means of specifying the
    bank this area is associated with.  All areas associated with  a
    particular  bank  are  combined  at  link  time  into a block of
    code/data.

       The  CSEG,  DSEG,  and  BANK options are specified within the
    parenthesis as shown in the following examples:

            .area   C_SEG   (CSEG,BANK=C1)
                                    ;This is a code section
                                    ;and is included in bank C1
            .area   D_SEG   (DSEG,BANK=D1)
                                    ;This is a data section
                                    ;and is included in bank D1.

       Multiple  invocations  of  the  .area directive with the same
    name must specify the same options or leave  the  options  field
    blank,  this  defaults  to  the previously specified options for
    this program area.

    The   ASxxxx   assemblers   automatically  provide  two  program
    sections:

            '_CODE'         This  is  the  default  code/data  area.
                            This   program   area   is    of    type
                            (REL,CON,CSEG).

            '_DATA'         This  is the default optional data area.
                            This   program   area   is    of    type
                            (REL,CON,DSEG).

    The .area names and options are never case sensitive.

##### => Section Index

####

    .psharea and .poparea Directives

    Format:

            .psharea

            .poparea

       The .psharea directive pushes the current area context onto a
    16 element stack.  Attempting a .psharea operation with  a  full
    stack results in a stack overflow error message.

       The  .poparea directive pops an area context from the 16 ele-
    ment stack.  Attempting a .poparea operation from an empty stack
    results in a stack underflow error message.

       These  directives  can  be  useful  when calling macros which
    place code and/or data into other areas.   As  an  example  this
    macro  saves the current area context, places descriptors into a
    specific area, and then restores the area context.

            .macro  .descriptor     name, device, block, flags
              .psharea
              .area Descriptors
              name: .rad50  device
                    .word   block
                    .word   flags
              .poparea
            .endm

       Code or data added to an area whose context is in the psh/pop
    stack is not affected by the restoration of the area's  context.
    The  code or data pointer is not part of the stacked area's con-
    text.

##### => Section Index

####

    .bank Directive

    Format:

            .bank   name    [(options)]

    where:  name    represents  the  symbolic  name of the bank sec-
                    tion.   This  name  may  be  the  same  as   any
                    user-defined  symbol  or  area as the bank names
                    are independent  of  all  symbols,  labels,  and
                    areas.   The name may be from 1 to 79 characters
                    in length.

            options specify the parameters of the bank:
                    BASE    base address of bank
                    SIZE    maximum size of bank
                    FSFX    file suffix for this bank
                    MAP     NOICE mapping

       The  .bank  directive allows an arbitrary grouping of program
    and/or data areas to be communicated to the  linker.   The  bank
    parameters are all optional and are described as follows:

         1.  BASE, the  starting  address of the bank (default is 0)
             may be defined.  This address can be overridden by  us-
             ing  the  linker -b option.  The bank address is always
             specified in 'byte' addressing.  A first area which  is
             not  'byte' addressed (e.g.  a processor addressed by a
             'word' of 2 or more bytes) has the area address  scaled
             to begin at the 'byte' address.

         2.  SIZE, the  maximum  length  of  the  bank  specified in
             bytes.  The size is always specified in terms of bytes.

         3.  FSFX, the file suffix to be used by the linker for this
             bank.  The suffix may not contain embedded white space.

         4.  MAP,  NOICE   mapping   parameter   for  this  bank  of
             code/data.

       The options are specified within parenthesis and separated by
    commas as shown in the following example:

            .BANK  C1  (BASE=0x0100,SIZE=0x1000,FSFX=_C1)
                                    ;This bank starts at 0x0100,
                                    ;has a maximum size of 0x1000,
                                    ;and is to be placed into
                                    ;a file with a suffix of _C1

       The parameters must be absolute (external symbols are not al-
    lowed.)

##### => Section Index

####

    .org Directive

    Format:

            .org    exp

    where:  exp     is  an absolute expression that becomes the cur-
                    rent location counter.

    The  .org directive is valid only in an absolute program section
    and will give a <q> error if used in a relocatable program area.
    The  .org  directive specifies that the current location counter
    is to become the specified absolute value.

##### => Section Index

####

    .globl Directive

    Format:

            .globl  sym1,sym2,...,symn

    where:  sym1,           represent legal symbolic names. When
            sym2,...        When multiple symbols are specified,
            symn            they are separated by commas.

       A  .globl directive may also have a label field and/or a com-
    ment field.

       The  .globl directive is provided to define (and thus provide
    linkage to) symbols not  otherwise  defined  as  global  symbols
    within  a  module.   In  defining  global  symbols the directive
    .globl J is similar to:

          J == expression or J::

       Because  object  modules  are linked by global symbols, these
    symbols are vital to a program.  All internal symbols  appearing
    within  a  given program must be defined at the end of pass 1 or
    they will be considered undefined.  The assembly directive  (-g)
    can  be  be  invoked to make all undefined symbols global at the
    end of pass 1.

       The  .globl directive and == construct can be overridden by a
    following .local directive.

                                  NOTE

         The  ASxxxx  assemblers  use the last occurring symbol
         specification in the source file(s) as the type  shown
         in the symbol table and output to the .rel file.

##### => Section Index

####

    .local Directive

    Format:

            .local  sym1,sym2,...,symn

    where:  sym1,           represent legal symbolic names.
            sym2,...        When multiple symbols are specified,
            symn            they are separated by commas.

       A  .local directive may also have a label field and/or a com-
    ment field.

       The  .local  directive is provided to define symbols that are
    local to the current assembly process.  Local  symbols  are  not
    effected  by  the assembler option -a (make all symbols global).
    In defining local symbols the directive .local J is similar to:

          J =: expression

       The  .local directive and the =:  construct are useful in de-
    fining symbols and constants within a header or definition  file
    that contains many symbols specific to the current assembly pro-
    cess that should not be exported into the .rel output  file.   A
    typical  usage  is  in  the definition of SFRs (Special Function
    Registers) for a microprocessor.

       The .local directive and =:  construct can be overridden by a
    following .globl directive.

                                  NOTE

         The  ASxxxx  assemblers  use the last occurring symbol
         specification in the source file(s) as the type  shown
         in the symbol table and output to the .rel file.

##### => Section Index

####

    .equ, .gblequ, and .lclequ Directives

    Format:

            sym1    .equ    expr    ; equivalent to sym1  = expr
            sym2    .gblequ expr    ; equivalent to sym2 == expr
            sym3    .lclequ expr    ; equivalent to sym3 =: expr

       These  alternate  forms  of equivalence are provided for user
    convenience.

##### => Section Index

####

    .if, .else, and .endif Directives

    Format:

            .if     expr
            .                       ;}
            .                       ;} range of true condition
            .                       ;}
            .else
            .                       ;}
            .                       ;} range of false condition
            .                       ;}
            .endif

       The  conditional  assembly directives allow you to include or
    exclude blocks of source code during the assembly process, based
    on the evaluation of the condition test.

       The  range of true condition will be processed if the expres-
    sion 'expr' is not zero (i.e.  true) and the range of false con-
    dition  will  be processed if the expression 'expr' is zero (i.e
    false).  The range of true condition is optional as is the .else
    directive  and  the range of false condition.  The following are
    all valid .if/.else/.endif constructions:

            .if     A-4             ;evaluate A-4
            .byte   1,2             ;insert bytes if A-4 is
            .endif                  ;not zero

            .if     K+3             ;evaluate K+3
            .else
            .byte   3,4             ;insert bytes if K+3
            .endif                  ;is zero

            .if     J&3             ;evaluate J masked by 3
            .byte   12              ;insert this byte if J&3
            .else                   ;is not zero
            .byte   13              ;insert this byte if J&3
            .endif                  ;is zero

    All .if/.else/.endif directives are limited to a maximum nesting
    of 10 levels.

       The  use of a .else directive outside a .if/.endif block will
    generate an <i> error.  Assemblies having unequal .if and .endif
    counts will cause an <i> error.

##### => Section Index

####

    .iff, .ift, and .iftf Directives

    Format:

            .if     expr    ;'if' range Condition is
                            ;TRUE when expr is not zero
             .ift                                   ;}
             .      ;} range of true condition      ;}
             .iff                                   ;} if
             .      ;} range of false condition     ;} block
             .iftf                                  ;}
             .      ;} unconditional range          ;}
            .else           ;'else' range Condition is
                            ;TRUE when expr is zero
             .ift                                   ;}
             .      ;} range of true condition      ;}
             .iff                                   ;} else
             .      ;} range of false condition     ;} block
             .iftf                                  ;}
             .      ;} unconditional range          ;}
            .endif

       The  subconditional  assembly directives may be placed within
    conditional assembly blocks to indicate:

            1. The assembly of an alternate body of code when
               the condition of the block tests false.

            2. The assembly of non-contiguous body of code
               within the conditional assembly block,
               depending upon the result of the conditional
               test in entering the block.

            3. The unconditional assembly of a body of code
               within a conditional assembly block.

    The use of the .iff, .ift, and .iftf directives makes the use of
    the .else directive redundant.

       Note  that  the  implementation of the .else directive causes
    the .if tested condition to be complemented.  The TRUE and FALSE
    conditions are determined by the .if/.else conditional state.

       All  .if/.else/.endif  directives  are  limited  to a maximum
    nesting of 10 levels.

       The  use  of the .iff, .ift, or .iftf directives outside of a
    conditional block results in a <i> error code.

       The  use of a .else directive outside a .if/.endif block will
    generate an <i> error.  Assemblies having unequal .if and .endif
    counts will cause an <i> error.

##### => Section Index

####

    .ifxx Directives
       Additional  conditional  directives are available to test the
    value of an evaluated expression:

            .ifne   expr            ; true if expr != 0
            .ifeq   expr            ; true if expr == 0
            .ifgt   expr            ; true if expr >  0
            .iflt   expr            ; true if expr <  0
            .ifge   expr            ; true if expr >= 0
            .ifle   expr            ; true if expr <= 0

       Format:

            .ifxx   expr
            .                       ;}
            .                       ;} range of true condition
            .                       ;}
            .else
            .                       ;}
            .                       ;} range of false condition
            .                       ;}
            .endif

       The  conditional  assembly directives allow you to include or
    exclude blocks of source code during the assembly process, based
    on the evaluation of the test condition.

       The  range of true condition will be processed if the expres-
    sion 'expr' is not zero (i.e.  true) and the range of false con-
    dition  will  be processed if the expression 'expr' is zero (i.e
    false).  The range of true condition is optional as is the .else
    directive  and  the range of false condition.  The following are
    all valid .if/.else/.endif constructions:

            .ifne   A-4             ;evaluate A-4
            .byte   1,2             ;insert bytes if A-4 is
            .endif                  ;not zero

            .ifeq   K+3             ;evaluate K+3
            .byte   3,4             ;insert bytes if K+3
            .endif                  ;is zero

            .ifne   J&3             ;evaluate J masked by 3
            .byte   12              ;insert this byte if J&3
            .else                   ;is not zero
            .byte   13              ;insert this byte if J&3
            .endif                  ;is zero

    All .if/.else/.endif directives are limited to a maximum nesting
    of 10 levels.

       The  use of a .else directive outside a .if/.endif block will
    generate an <i> error.  Assemblies having unequal .if and .endif
    counts will cause an <i> error.

##### => Section Index

####

    .ifdef Directive

    Format:

            .ifdef  sym
            .                       ;}
            .                       ;} range of true condition
            .                       ;}
            .else
            .                       ;}
            .                       ;} range of false condition
            .                       ;}
            .endif

       The  conditional  assembly directives allow you to include or
    exclude blocks of source code during the assembly process, based
    on the evaluation of the condition test.

       The  range  of true condition will be processed if the symbol
    'sym' has been defined with a .define directive or  'sym'  is  a
    variable  with  an  assigned  value else the false range will be
    processed.  The range of true condition is optional  as  is  the
    .else directive and the range of false condition.  The following
    are all valid .ifdef/.else/.endif constructions:

            .ifdef  sym$1           ;lookup symbol sym$1
            .byte   1,2             ;insert bytes if sym$1
            .endif                  ;is defined or
                                    ;assigned a value

            .ifdef  sym$2           ;lookup symbol sym$2
            .else
            .byte   3,4             ;insert bytes if sym$1
            .endif                  ;is not defined and
                                    ;not assigned a value

            .ifdef  sym$3           ;lookup symbol sym$3
            .byte   12              ;insert this byte if sym$3
            .else                   ;is defined/valued
            .byte   13              ;insert this byte if sym$3
            .endif                  ;is not defined/valued

    Note  that the default assembler configuration of case sensitive
    means the testing for a defined symbol is also case sensitive.

       All  .if/.else/.endif  directives  are  limited  to a maximum
    nesting of 10 levels.

       The  use of a .else directive outside a .if/.endif block will
    generate an <i> error.  Assemblies having unequal .if and .endif
    counts will cause an <i> error.

##### => Section Index

####

    .ifndef Directive

    Format:

            .ifndef sym
            .                       ;}
            .                       ;} range of true condition
            .                       ;}
            .else
            .                       ;}
            .                       ;} range of false condition
            .                       ;}
            .endif

       The  conditional  assembly directives allow you to include or
    exclude blocks of source code during the assembly process, based
    on the evaluation of the condition test.

       The  range  of true condition will be processed if the symbol
    'sym' is not defined by a .define directive and a variable 'sym'
    has  not been assigned a value else the range of false condition
    will be processed.  The range of true condition is  optional  as
    is  the  .else  directive and the range of false condition.  The
    following are all valid .ifndef/.else/.endif constructions:

            .ifndef sym$1           ;lookup symbol sym$1
            .byte   1,2             ;insert bytes if sym$1 is
            .endif                  ;not defined and
                                    ;not assigned a value

            .ifndef sym$2           ;lookup symbol sym$2
            .else
            .byte   3,4             ;insert bytes if sym$1
            .endif                  ;is defined or
                                    ;is assigned a value

            .ifndef sym$3           ;lookup symbol sym$3
            .byte   12              ;insert this byte if sym$3
            .else                   ;is not defined/valued
            .byte   13              ;insert this byte if sym$3
            .endif                  ;is defined/valued

    All .if/.else/.endif directives are limited to a maximum nesting
    of 10 levels.

       The  use of a .else directive outside a .if/.endif block will
    generate an <i> error.  Assemblies having unequal .if and .endif
    counts will cause an <i> error.

##### => Section Index

####

    .ifb Directive

    Format:

            .ifb    sym
            .                       ;}
            .                       ;} range of true condition
            .                       ;}
            .else
            .                       ;}
            .                       ;} range of false condition
            .                       ;}
            .endif

       The  conditional  assembly directives allow you to include or
    exclude blocks of source code during the assembly process, based
    on the evaluation of the test condition.

       The  conditional  .ifb  is most useful when used in macro de-
    finitions to determine if the argument is blank.  The  range  of
    true  condition  will be processed if the symbol 'sym' is blank.
    The range of true condition is optional as is the  .else  direc-
    tive  and  the  range of false condition.  The following are all
    valid .ifb/.else/.endif constructions:

            .ifb    sym$1           ;argument is not blank
            .byte   1,2             ;insert bytes if argument
            .endif                  ;is blank

            .ifb    sym$2           ;argument is not blank
            .else
            .byte   3,4             ;insert bytes if argument
            .endif                  ;is not blank

            .ifb                    ;argument is blank
            .byte   12              ;insert this byte if
            .else                   ;argument is blank
            .byte   13              ;insert this byte if
            .endif                  ;argument not blank

    All .if/.else/.endif directives are limited to a maximum nesting
    of 10 levels.

       The  use of a .else directive outside a .if/.endif block will
    generate an <i> error.  Assemblies having unequal .if and .endif
    counts will cause an <i> error.

##### => Section Index

####

    .ifnb Directive

    Format:

            .ifnb   sym
            .                       ;}
            .                       ;} range of true condition
            .                       ;}
            .else
            .                       ;}
            .                       ;} range of false condition
            .                       ;}
            .endif

       The  conditional  assembly directives allow you to include or
    exclude blocks of source code during the assembly process, based
    on the evaluation of the test condition.

       The  conditional  .ifnb is most useful when used in macro de-
    finitions to determine if the argument is not blank.  The  range
    of  true  condition will be processed if the symbol 'sym' is not
    blank.  The range of true condition is optional as is the  .else
    directive  and  the range of false condition.  The following are
    all valid .ifnb/.else/.endif constructions:

            .ifnb   sym$1           ;argument is not blank
            .byte   1,2             ;insert bytes if argument
            .endif                  ;is not blank

            .ifnb   sym$2           ;argument is not blank
            .else
            .byte   3,4             ;insert bytes if argument
            .endif                  ;is blank

            .ifnb                   ;argument is blank
            .byte   12              ;insert this byte if
            .else                   ;argument is not blank
            .byte   13              ;insert this byte if
            .endif                  ;argument is blank

    All .if/.else/.endif directives are limited to a maximum nesting
    of 10 levels.

       The  use of a .else directive outside a .if/.endif block will
    generate an <i> error.  Assemblies having unequal .if and .endif
    counts will cause an <i> error.

##### => Section Index

####

    .ifidn Directive

    Format:

            .ifidn  sym$1,sym$2
            .                       ;}
            .                       ;} range of true condition
            .                       ;}
            .else
            .                       ;}
            .                       ;} range of false condition
            .                       ;}
            .endif

       The  conditional  assembly directives allow you to include or
    exclude blocks of source code during the assembly process, based
    on the evaluation of the test condition.

       The  conditional .ifidn is most useful when used in macro de-
    finitions to determine if  the  arguments  are  identical.   The
    range  of true condition will be processed if the symbol 'sym$1'
    is idendical to 'sym$2' (i.e.  the character strings  for  sym$1
    and  sym$2  are  the  same  consistent with the case sensitivity
    flag).  When this if statement occurs inside a  macro  where  an
    argument  substitution  may  be blank then an argument should be
    delimited with the form /symbol/ for each symbol.  The range  of
    true  condition  is  optional  as is the .else directive and the
    range  of  false  condition.   The  following  are   all   valid
    .ifidn/.else/.endif constructions:

            .ifidn  sym$1,sym$1     ;arguments are the same
            .byte   1,2             ;insert bytes if arguments
            .endif                  ;are the sane

            .ifidn  sym$1,sym$2     ;arguments are not the same
            .else
            .byte   3,4             ;insert bytes if arguments
            .endif                  ;are not the same

            .ifidn  sym$3,sym$3     ;arguments are the same
            .byte   12              ;insert this byte if
            .else                   ;arguments are the same
            .byte   13              ;insert this byte if
            .endif                  ;arguments are not the same

    All .if/.else/.endif directives are limited to a maximum nesting
    of 10 levels.

       The  use of a .else directive outside a .if/.endif block will
    generate an <i> error.  Assemblies having unequal .if and .endif
    counts will cause an <i> error.

##### => Section Index

####

    .ifdif Directive

    Format:

            .ifdif  sym$1,sym$2
            .                       ;}
            .                       ;} range of true condition
            .                       ;}
            .else
            .                       ;}
            .                       ;} range of false condition
            .                       ;}
            .endif

       The  conditional  assembly directives allow you to include or
    exclude blocks of source code during the assembly process, based
    on the evaluation of the test condition.

       The  conditional .ifdif is most useful when used in macro de-
    finitions to determine if  the  arguments  are  different.   The
    range  of true condition will be processed if the symbol 'sym$1'
    is different from 'sym$2' (i.e.  the character strings for sym$1
    and  sym$2  are the not the same consistent with the case sensi-
    tivity flag).  When this if  statement  occurs  inside  a  macro
    where  an  argument  substitution  may be blank then an argument
    should be delimited with the form /symbol/ for each symbol.  The
    range  of  true  condition is optional as is the .else directive
    and the range of false condition.  The following are  all  valid
    .ifdif/.else/.endif constructions:

            .ifdif  sym$1,sym$2     ;arguments are different
            .byte   1,2             ;insert bytes if arguments
            .endif                  ;are different

            .ifdif  sym$1,sym$1     ;arguments are identical
            .else
            .byte   3,4             ;insert bytes if arguments
            .endif                  ;are different

            .ifdif  sym$1,sym$3     ;arguments are different
            .byte   12              ;insert this byte if
            .else                   ;arguments are different
            .byte   13              ;insert this byte if
            .endif                  ;arguments are identical

    All .if/.else/.endif directives are limited to a maximum nesting
    of 10 levels.

       The  use of a .else directive outside a .if/.endif block will
    generate an <i> error.  Assemblies having unequal .if and .endif
    counts will cause an <i> error.

##### => Section Index

####

    Alternate .if Directive Forms

    Format:

            .if     cnd(,)  arg1(, arg2)

       where  the  cnd (followed by an optional comma) may be any of
    the following:

            -------------------------------------------------------
             condition              Assemble
            (complement)    Args    Block if:
            -------------------------------------------------------
            eq   ( ne )     expr    equal to zero
                                    (not equal to zero)

            gt   ( le )     expr    greater than zero
                                    (less than or equal to zero)

            lt   ( ge )     expr    less than zero
                                    (greater than or equal to zero)

            def  ( ndef )   symbol  .define'd or user set
                                    (not .define'd or user set)

            b    ( nb )     macro   argument present
                            symbol  (argument not present)

            idn  ( dif )    macro   arguments identical
                            symbol  (arguments not identical)

            f    ( t )      -----   only within a .if/.else/.endif
                                    conditional block

            tf              -----   only within a .if/.else/.endif
                                    conditional block

    All .if/.else/.endif directives are limited to a maximum nesting
    of 10 levels.

       The  use of a .else directive outside a .if/.endif block will
    generate an <i> error.  Assemblies having unequal .if and .endif
    counts will cause an <i> error.

##### => Section Index

####

    Immediate Conditional Assembly Directives

       The  immediate conditional assembly directives allow a single
    line of code to be assembled without  using  a  .if/.else/.endif
    construct.   All  of  the previously described conditionals have
    immediate equivalents.

       Format:

            .iif            arg(,)          line_to_assemble
            .iifeq          arg(,)          line_to_assemble
            .iifne          arg(,)          line_to_assemble
            .iifgt          arg(,)          line_to_assemble
            .iifle          arg(,)          line_to_assemble
            .iifge          arg(,)          line_to_assemble
            .iiflt          arg(,)          line_to_assemble
            .iifdef         arg(,)          line_to_assemble
            .iifndef        arg(,)          line_to_assemble

            .iifb        (,)arg(,)          line_to_assemble
            .iifnb       (,)arg(,)          line_to_assemble
            .iifidn      (,)arg1,arg2(,)    line_to_assemble
            .iifdif      (,)arg1,arg2(,)    line_to_assemble

       Valid only within a conditional block.

            .iiff                           line_to_assemble
            .iift                           line_to_assemble
            .iiftf                          line_to_assemble

    Alternate Format:

            .iif            arg(,)          line_to_assemble
            .iif    eq      arg(,)          line_to_assemble
            .iif    ne      arg(,)          line_to_assemble
            .iif    gt      arg(,)          line_to_assemble
            .iif    le      arg(,)          line_to_assemble
            .iif    ge      arg(,)          line_to_assemble
            .iif    lt      arg(,)          line_to_assemble
            .iif    def     arg(,)          line_to_assemble
            .iif    ndef    arg(,)          line_to_assemble

            .iif    b    (,)arg(,)          line_to_assemble
            .iif    nb   (,)arg(,)          line_to_assemble
            .iif    idn  (,)arg1,arg2(,)    line_to_assemble
            .iif    dif  (,)arg1,arg2(,)    line_to_assemble

       Valid only within a conditional block.

            .iif    f                       line_to_assemble
            .iif    t                       line_to_assemble
            .iif    tf                      line_to_assemble

    The (,) indicates an optional comma.

       The  .iif  types b, n, idn, and dif require the commas if the
    argument(s) may be blank.  These commas may be  removed  if  the
    arguments are delimited with the form ^/symbol/ for each symbol.

       The   immediate   conditional  directives  donot  change  the
    .if/.else/.endif nesting level.

##### => Section Index

####

    .incbin Directive

    Format:

            .incbin          /string/ [,offset [,count]]    or

            .incbin         ^/string/ [,offset [,count]]

    where:  string  represents  a string that is the file specifica-
                    tion of any file type.

            /  /    represent   the  delimiting  characters.   These
                    delimiters   may   be   any   paired    printing
                    characters,  as  long  as the characters are not
                    contained within  the  string  itself.   If  the
                    delimiting  characters do not match, the .incbin
                    directive will give the <q> error.

       The  .incbin  directive  is  used to insert the contents of a
    file verbatim into the assembler as a byte stream.  This can  be
    handy  (for example) when including some arbitrary data directly
    into the executable output.  However, it is recommended  to  use
    this only for small pieces of data.

       The .incbin can be invoked with one or two optional arguments
    which specify the number of bytes to skip in the  file  and  the
    maximum number of bytes to insert into the output file.

    .incbin "file.dat"              ; include the whole file
    .incbin "file.dat",1024         ; skip the first 1024 bytes
    .incbin "file.dat",1024,512     ; skip first 1024, and
                                    ; include at most 512 bytes

    The ',' delimiters can be any regular delimiter - space, tab, or
    ','.  The offset and count arguments must be local, evaluate  to
    a  constant, and may be 0.  A blank offset is by default 0 and a
    blank count is the remainder of the file.

       An offset equal to or greater than the file length results in
    an <i> error.  A count that is larger than the  remaining  bytes
    in a file does not result in an error.

##### => Section Index

####

    .include Directive

    Format:

            .include         /string/               or

            .include        ^/string/

    where:  string  represents  a string that is the file specifica-
                    tion of an ASxxxx source file.

            /  /    represent   the  delimiting  characters.   These
                    delimiters   may   be   any   paired    printing
                    characters,  as  long  as the characters are not
                    contained within  the  string  itself.   If  the
                    delimiting characters do not match, the .include
                    directive will give the <q> error.

       The .include directive is used to insert a source file within
    the source file currently being assembled.  When this  directive
    is encountered, an implicit .page directive is issued.  When the
    end of the specified source file is reached, an  implicit  .page
    directive is issued and input continues from the previous source
    file.  The maximum nesting level of source files specified by  a
    .include directive is five.

       The  total  number  of separately specified .include files is
    unlimited as each .include file is opened and then closed during
    each pass made by the assembler.

       The  default  directory  path,  if none is specified, for any
    .include file is the directory path of the  current  file.   For
    example:   if  the  current  source file, D:\proj\file1.asm, in-
    cludes  a  file  specified   as   "include1"   then   the   file
    D:\proj\include1.asm is opened.

####

        Including Files In Windows/DOS  -
        Graphical Illustration of Include File Locations
        for the following command line entry:

        __> bin\ascheck -l -o -s  obj\prjct.rel   src\prjct\prjct.asm

#####

                             /-----------------------------------------------------------------------\
                             |                                           (rooted)                    |
                 _____       |           _____                                                       |
                |     |      |          |     |                                                      |
             ---| inc |  <---/       ---| bin |                                                      |
             |  |_____|              |  |_____|                                                      |
             |     |                 |     |                                                         |
             |     \___ inc4.asm     |     \___ ascheck.exe                                          |
             |                       |                                                               |
             |                       |                                                               |
     _____   |   _____       _____   |   _____       _____                                           |
    |     |  |  |     |     |     |  |  |     |     |     |      (in prjct.asm directory)            |
    | C:\ |-----| ..\ |-----| __> |--+--| src |-----|prjct|  <-------------------------------\       |
    |_____|     |_____|  |  |_____|  |  |_____|  |  |_____|                                  |       |
                         |           |           |     |                .include "inc1.asm" -/       |
                         |     ^     |           |     \___ prjct.asm   .include "C:\inc\inc4.asm" --/
                         |     |     |           |     \___ inc1.asm    .include "..\inc\inc3.asm" -------\
        Current          |     |     |           |   _____              .include "src\inc\inc2.asm" -\    |
        Working  ------> | >---/     |           |  |     |                                          |    |
       Directory         |           |           ---| inc |  <---------------------------------------/    |
                         |           |              |_____|   (relative to current working directory)     |
                         |           |                 |                                                  |
                         |           |                 \___ inc2.asm                                      |
                         |           |   _____                                                            |
                         |           |  |     |                                                           |
                         |           ---| obj |                                                           |
                         |              |_____|                                                           |
                         |                 |                                                              |
                         |                 \___ .REL, .SYM, .LST, .HLR                                    |
                         |                                                                                |
                         |   _____                                                                        |
                         |  |     |                          (relative to current working directory)      |
                         ---| inc |  <--------------------------------------------------------------------/
                            |_____|
                               |
                               \___ inc3.asm

####

        Including Files In Linux  -
        Graphical Illustration of Include File Locations
        for the following command line entry:

        __$ bin/ascheck -l -o -s  obj/prjct.rel   src/prjct/prjct.asm

#####

                             /-----------------------------------------------------------------------\
                             |                                           (rooted)                    |
                 _____       |           _____                                                       |
                |     |      |          |     |                                                      |
             ---| inc |  <---/       ---| bin |                                                      |
             |  |_____|              |  |_____|                                                      |
             |     |                 |     |                                                         |
             |     \___ inc4.asm     |     \___ ascheck                                              |
             |                       |                                                               |
             |                       |                                                               |
     _____   |   _____       _____   |   _____       _____                                           |
    |     |  |  |     |     |     |  |  |     |     |     |      (in prjct.asm directory)            |
    |  /  |-----| ../ |-----| __$ |--+--| src |-----|prjct|  <-------------------------------\       |
    |_____|     |_____|  |  |_____|  |  |_____|  |  |_____|                                  |       |
                         |           |           |     |                .include "inc1.asm" -/       |
                         |     ^     |           |     \___ prjct.asm   .include "/inc/inc4.asm" ----/
                         |     |     |           |     \___ inc1.asm    .include "../inc/inc3.asm" -------\
        Current          |     |     |           |   _____              .include "src/inc/inc2.asm" -\    |
        Working  ------> | >---/     |           |  |     |                                          |    |
       Directory         |           |           ---| inc |  <---------------------------------------/    |
                         |           |              |_____|   (relative to current working directory)     |
                         |           |                 |                                                  |
                         |           |                 \___ inc2.asm                                      |
                         |           |   _____                                                            |
                         |           |  |     |                                                           |
                         |           ---| obj |                                                           |
                         |              |_____|                                                           |
                         |                 |                                                              |
                         |                 \___ .REL, .SYM, .LST, .HLR                                    |
                         |                                                                                |
                         |   _____                                                                        |
                         |  |     |                          (relative to current working directory)      |
                         ---| inc |  <--------------------------------------------------------------------/
                            |_____|
                               |
                               \___ inc3.asm

##### => Section Index

####

    .define and .undefine Directives

    Format:

            .define        keyword  /string/        or

            .define        keyword ^/string/

            .undefine      keyword

    where:  keyword is  the  substitutable  string  which must start
                    with a letter and may contain any combination of
                    digits and letters.

    where:  string  represents  a string that is substituted for the
                    keyword.  The string may contain any sequence of
                    characters including white space.

            /  /    represent   the  delimiting  characters.   These
                    delimiters   may   be   any   paired    printing
                    characters,  as  long  as the characters are not
                    contained within  the  string  itself.   If  the
                    delimiting  characters do not match, the .define
                    directive will give the <q> error.

       The  .define  directive specifies a user defined string which
    is substituted for the keyword.  The substitution string may it-
    self  contain other keywords that are substitutable.  The assem-
    bler resumes the parse of the line at the point the keyword  was
    found.  Care must be excersized to avoid any circular references
    within .define directives, otherwise the assembler may  enter  a
    'recursion runaway' resulting in an <s> error.

       The  .undefine  directive removes the keyword as a substitut-
    able string.  No error is returned if the keyword  was  not  de-
    fined.

       When a .define directive specifies a keyword, with or without
    a substitution string, the keyword is defined but is not a  sym-
    bol.   Because  the  keyword is not a symbol the keyword becomes
    undefined at the beginning of the next assembler pass.

       The   keyword   substitution   is   never  applied  to  these
    directives:   .define,  .undefine,   .ifdef   .ifndef,   iifdef,
    iifndef, or any variation of def or ndef conditionals.

##### => Section Index

####

    .enabl and .dsabl Directives

    Format:

            .enabl  (optn1, optn2, ...)     ;enable options

            .dsabl  (optn1, optn2, ...)     ;disable options

       The  'csn'  option  , C Style Numbers', is currently the only
    option available to all ASxxxx assemblers.  Enabling  the  'csn'
    option disables all the temporary radix options beginning with a
    0 (zero) except the hex radix options  0x  and  0X.   All  other
    numbers  beginning  with 0 are evaluated as octal values and all
    numbers beginning with  digits  1-9  are  evaluated  as  decimal
    values.

       Individual assemblers may have additional options specific to
    that assembler and will be described in its documentation.

##### => Section Index

####

    .setdp Directive

    Format:

            .setdp [base [,area]]

    The  set  direct  page  directive has a common format in all the
    AS68xx assemblers.  The .setdp directive is used to  inform  the
    assembler  of  the current direct page region and the offset ad-
    dress within the selected area.  The normal  invocation  methods
    are:

            .area   DIRECT  (PAG)
            .setdp

            or

            .setdp  0,DIRECT

    for  all  the  68xx microprocessors (the 6804 has only the paged
    ram area).  The commands specify that the direct page is in area
    DIRECT and its offset address is 0 (the only valid value for all
    but the 6809 microprocessor).  Be sure to place the DIRECT  area
    at address 0 during linking.  When the base address and area are
    not specified, then zero and the current area are the  defaults.
    If  a  .setdp directive is not issued the assembler defaults the
    direct page to the area "_CODE" at offset 0.

       The  assembler  verifies  that  any  local variable used in a
    direct variable reference is located in this area.  Local  vari-
    able  and  constant value direct access addresses are checked to
    be within the address range from 0 to 255.

       External direct references are assumed by the assembler to be
    in the correct area and have valid  offsets.   The  linker  will
    check all direct page relocations to verify that they are within
    the correct area.

       The  6809  microprocessor  allows the selection of the direct
    page to be on any 256 byte boundary by loading  the  appropriate
    value  into the dp register.  Typically one would like to select
    the page boundary at link time, one method follows:

            .area   DIRECT  (PAG)   ; define the direct page
            .setdp
            .
            .
            .
            .area   PROGRAM
            .
            ldd     #DIRECT         ; load the direct page register
            tfr     a,dp            ; for access to the direct page

    At  link  time specify the base and global equates to locate the
    direct page:

            -a DIRECT = 0x1000
            -g DIRECT = 0x1000

    Both  the  area address and offset value must be specified (area
    and variable names are independent).   The  linker  will  verify
    that  the  relocated  direct page accesses are within the direct
    page.

    The  preceding  sequence  could  be  repeated for multiple paged
    areas, however an alternate method is to define a non-paged area
    and use the .setdp directive to specify the offset value:

            .area   DIRECT          ; define non-paged area
            .
            .
            .
            .area   PROGRAM
            .
            .setdp  0,DIRECT        ; direct page area
            ldd     #DIRECT         ; load the direct page register
            tfr     a,dp            ; for access to the direct page
            .
            .
            .setdp  0x100,DIRECT    ; direct page area
            ldd     #DIRECT+0x100   ; load the direct page register
            tfr     a,dp            ; for access to the direct page

    The  linker  will  verify that subsequent direct page references
    are in the specified area and offset address range.  It  is  the
    programmers responsibility to load the dp register with the cor-
    rect page segment  corresponding  to  the  .setdp  base  address
    specified.

       For  those  cases  where a single piece of code must access a
    defined data structure within a direct page and there  are  many
    pages,  define  a  dummy  direct page linked at address 0.  This
    dummy page is used only to define  the  variable  labels.   Then
    load  the dp register with the real base address but donot use a
    .setdp  directive.   This  method  is  equivalent   to   indexed
    addressing,  where the dp register is the index register and the
    direct addressing is the offset.

##### => Section Index

####

    .16bit, .24bit, and .32bit Directives

    Format:

            .16bit          ;specify 16-bit addressing
            .24bit          ;specify 24-bit addressing
            .32bit          ;specify 32-bit addressing

       The  .16bit, .24bit, and .32bit directives are special direc-
    tives for assembler configuration when default  values  are  not
    used.

##### => Section Index

####

    .msb Directive

    Format:

            .msb    n

       The  .msb  directive is only available in selected assemblers
    which support 24- or 32-bit addressing.

       The  assembler operator '>' selects the upper byte (MSB) when
    included in an assembler instruction.  The default assembler mode
    is  to select bits <15:8> as the MSB.  The .msb directive allows
    the programmer to specify a particular byte as  the  'MSB'  when
    the address space is larger than 16-bits.

       The  assembler  directive  .msb n  configures the assembler to
    select a particular byte as MSB.  Given a 32-bit address of MNmn
    (M(3)  is  <31:24>, N(2) is <23:16>, m(1) is <15:8>, and n(0) is
    <7:0>) the following examples show how to  select  a  particular
    address byte:

            .msb 1          ;select byte 1 of address
                            ;<M(3):N(2):m(1):n(0)>
            LD A,>MNmn      ;byte m <15:8> ==>> A
            ...

            .msb 2          ;select byte 2 of address
                            ;<M(3):N(2):m(1):n(0)>
            LD A,>MNmn      ;byte N <23:16> ==>> A
            ...

            .msb 3          ;select byte 3 of address
                            ;<M(3):N(2):m(1):n(0)>
            LD A,>MNmn      ;byte M <31:24> ==>> A
            ...

##### => Section Index

####

    .lohi and .hilo Directives

    Format:

            .lohi           ;specify LSB first output
            .hilo           ;specify MSB first output

       The .lohi and .hilo directives are special directives for as-
    sembler output configuration.  These  directives  are  currently
    only enabled in assembler 'ascheck'.

       An  <m> error will be generated if the .lohi and .hilo direc-
    tives are both used within the same assembly source file.

##### => Section Index

####

    .trace and .ntrace Directives

     Format:

             .trace                          ;Basic .trace

             .trace  (arg1,arg2,...,argn)    ;with trace options

             .ntrace                         ;Basic .ntrace

             .ntrace (arg1,arg2,...,argn)    ;with trace options

     The  .trace and .ntrace directives are used to trace the process
     of inserting assembler text lines, opening and closing of assem-
     bler  and  include  files,  and  the  processing of macros.  The
     directives have the following tracing options:

             ins     -       line insertion
             asm     -       assembler files
             inc     -       include files
             mcr     -       macro invocation
             rpt     -       macro repeat invocation
             !       -       sets the tracing mode to
                             !(.trace) or !(.ntrace) before
                             applying the tracing options

     The 'normal' tracing mode .trace is the combination of ins, asm,
     inc, mcr and rpt enabled.  The 'normal' non tracing mode .ntrace
     has all tracing items disabled.  When specifying tracing options
     the option list must be enclosed within parenthesis and multiple
     options separated by commas.

        The NOT option, !, is used to set the tracing mode to the op-
     posite of the .trace or .ntrace directive  before  applying  the
     tracing options.

        For example:

             .ntrace (!)     is equivalent to .trace  and
             .trace  (!)     is equivalent to .ntrace
                             any additional options will
                             be applied normally

        When  tracing  is invoked each trace option inserts a comment
     line into the  assembler  listing  denoting  when  a  particular
     traced  action  occurs.   The inserted lines contain information
     related to the type of traced action:

             ins     at insertion    ;N>>

             asm     at entry        ;A>> file.ext
                     at exit         ;A<< file.ext
                     The name of the assembler file

             inc     at entry        ;I>> (N) file.ext
                     at exit         ;I<< (N) file.ext
                     The inclusion depth (N) and
                     the name of the include file

             mcr     at entry        ;M>> (N) file.ext (L)
                     at exit         ;M<< (N) file.ext (L)
                     The macro recursion level,
                     the name of the file defining the macro,
                     and the line number in file.ext

             rpt     at invocation   ;R>> (N) file.ext (L)
                     The macro repeat count,
                     the name of the file defining the macro,
                     and the line number in file.ext

        The initial invocation of a macro or any repeat macro will be
     listed as ;M>> and subsequent repeats will be  listed  as  ;R>>.
     Thus  the first ;R>> will be the second invocation of the repeat
     macro.

        Examples of tracing options:

             .trace  (mcr)   ; macro processing lists
                             ; the entry and exit from
                             ; a non repeating macro.

             .trace  (rpt)   ; macro processing lists
                             ; the entry, exit, and
                             ; repeat of a macro.

##### => Section Index

####

    .end Directive

    Format:

            .end

            .end    exp

    where:  exp     represents  any expression, including constants,
                    symbols, or labels.

       The  .end  directive is used to specify a code entry point to
    be included in the linker output file.  Review  the  I86  and  S
    record formats described in the linker section for details.

       The .end directive without an expression is ignored.

##### => Section Index

... Exit the ASxxxx Documentation

... Home Page

###### Last Updated: May 2026