Sometimes  it  is  convenient  to  give  alternate names to a
processor's registers to improve readability or make  your  code
more descriptive.  

   For  almost  all the assemblers the registers are defined in-
ternally and do not have a value.   This  means  that  using  an
equate statement will fail:  

        iptr .equ R3  /  iptr = R3

and will give a <u>, undefined, error.  

   Use the .define directive to specify the alternate name for a
register:  

        .define   keyword   ^/string'
e.g.
        .define   iptr   ^/R3/


   The  assembler, when it finds the key word 'iptr', will first
replace the string 'iptr' with 'R3' and then process  the  line.
(Note that the the keyword must start with a letter.) 

   The  .area  and .bank directives are just a means of organiz-
ing, ordering, combining, and placing code where you want it.  

   An  example  might  be the construction of an area which con-
tains addresses of messages and an area containing the messages.
In this case define an area which will only contain the base ad-
dress of the address table, the second will contain the list  of
addresses, and the third which will contain the messages.  


        .area   msgbas          ; Message address base
        .area   msgadr          ; Message addresses
        .area   msgs            ; Messages


   Then insert message addresses in area msgaddr and messages in
area msgs:  


        .area   msgbas          ; Base of msgadr table
msgadr:

        .area   msgadr
        .word   msg01           ; Address of message 1
        .word   msg02           ; Address of message 2
        ...

        .area   msgs
msg01:  .asciz  "Message Number 1"
msg02:  .asciz  "Message Number 2"
        ...

        .area   MyCode          ; Reselect Code Area


   (Note:   be  sure  to  reselect the code area you want before
continueing with your coding.) 

   At any further point in your source code you can insert addi-
tional messages in the table by simply repeating the process:  

        .area   msgadr
        .word   msg03           ; Address of message 3
        ...

        .area   msgs
msg03:  .asciz  "Message Number 3"
        ...

        .area   MyCode          ; Reselect Code Area


with the message addresses and messages appended to the previous
entries.  (Note that the label msgadr, which is the beginning of
the address table, is required to be presented to the linker be-
fore area msgadr.) 

   This  procedure can be replicated as needed and also in other
assembly files.  The ordering will be defined by  the  order  in
which  the  individually assembled modules are linked.  This may
be especially useful when  linking  optional  modules  and  want
their messages included in the same dispatch table.  

   It  will be easier to manage your areas by creating an assem-
bly file which contains the ordering of your code and  including
it  in  all your assembly files or assemble this definition file
and make it the first file when linking your project.  

   In  this  example the definition file should contain the fol-
lowing three areas:  


        ...
        .area   msgbas          ; Message Base
        .area   msgadr          ; Message Addresses
        .area   msgs            ; Messages
        ...


   The  bank  directive  allows  the programmer to position code
anywhere in the address space of the processor.  Suppose  it  is
desired  to  place  the message tables at location 0x6000 in the
processor address space.  The bank directives might be:  


        .bank   MsgTbl  (Base=0x6000)

and  the  area  definitions  should be changed to place the code
into the specific bank:  

        ...
        .area   msgbas  (Bank=MsgTbl)   ; Message Base
        .area   msgadr  (Bank=MsgTbl)   ; Message Addresses
        .area   msgs    (Bank=MsgTbl)   ; Messages
        ...


   One  should  note that by using a definition file, which con-
tains all the area/bank options, all other assembly  files  need
only .area directives with the area name.  

   The  default  actions  when the .include directive is invoked
are:  

        1)  Interrupt current assembly processing
        2)  Start a New Page
        3)  Assemble include file statements
        4)  Start a New Page
        5)  Continue assembling where interrupted


   To  inhibit  the  'Start  a  New Page' steps when including a
file, insert the appropriate listing directives as shown in this
example.  

        .nlist                          ; Inhibits Pagination
        .include    "area.def"          ; Include the File
        .list                           ; Restart Listing


   Because the .nlist directive also applies to the include file
you must place an appropriate .list  directive  in  the  include
file.   At completion of the include file processing listing au-
tomatically reverts to the .nlist mode and pagination  is  again
suppressed.  The .list directive then restores normal listing as
assembly processing continues.  

                              NOTE

     If  the assembled include file generates output object
     code and a .rst file is going to  be  created  by  the
     linker,  then  the assembler listing file must include
     the .list options (loc,bin) for regular code or  (meb)
     for  macro  generated  code.   Failure  to include all
     generated code in the  listing  file  will  result  in
     translation errors in the .rst file.  



   When inserting an included file using the above technique and
there is no listing directive within the file, then the  result-
ing  assembler listing file will show no indication the file was
actually included.  .list and .nlist are never shown in the out-
put  listing file.  To indicate the file was included, using the
example Area/Bank definition file, one might list a single  line
description of the inclusion by inserting these lines in the in-
cluded file.  

        .list   (!,src)
;       area.def        Areas/Banks             Defined
        .nlist

   Then the result of 

        .nlist                          ; Inhibits Pagination
        .include    "area.def"          ; Include the File
        .list                           ; Restart Listing

will be a single line in the assembly listing:  

;       area.def        Areas/Banks             Defined

   When  building  a project there is always the decision to as-
semble multiple files together on the command line, use the .in-
clude directive to insert assembly files into the project, or to
assemble files  seperately  and  then  combine  them  using  the
linker.  

   When coding reusable modules it may be more convenient to as-
semble these modules seperately.  However this also  requires  a
method  to  define  the  global  entry  points  and data for the
calling program.  The following  technique  allows  any  of  the
three methods described to be used.  

   The  module  is designed in such a way that it can be used as
an independent module, included module, and a globals definition
file.   The  first step is to open a file, perhaps 'fnctns.asm',
inhibit listing, and create a macro which holds all  the  global
definitions:  

.nlist

        .macro  fnctns.globals
          .globl   func1        ; function 1
          .globl   func2        ; function 2
          .globl   inpval       ; input variable
          .globl   outval       ; ouput variable
        .endm


   Next  add  code  that invokes just the globals or the globals
and the module's code.  Do this  by  using  a  conditional  that
checks  if a specific label has been defined.  As an example use
the string "_fnctns" as the label that must be defined.  

        .ifdef  "_fnctns"
          fnctns.globals
        .else
          .list
          fnctns.globals

          ...                   ; module code
          ...
          ...

          .nlist
        .endif


   This  file can be assembled as a seperate module or as an in-
cluded file in the project.  If the project is built by  linking
this  module with other modules then any module which references
the functions or variables in the module "fnctns.asm" will  need
these to be defined.  Add this code to any module using the mod-
ule "fnctns".  

        .define   "_fnctns"             ; key word
        .nlist                          ; Inhibits Pagination
        .include  "fnctns.asm"          ; Include the File
        .list                           ; Restart Listing

This  results  in  only the globals being defined for the module
"fnctns.asm".