!pr2
!lm12
!rm75
Assembler Directives.......................Bob Sander-Cederlof

Of all the Apple assemblers on the market, it seems that no two have exactly the same list of assembler directives.  Directives, also called "pseudo-ops", are used to control the assembly process and to define data in your programs.  When you see a listing of an assembly language program in a magazine, or in this newsletter, or in a book on 6502 programming, you may have to translate the directives to fit the assembler you own.

All directives in the S-C Macro Assembler begin with a period.  This helps to distinguish them visually from 6502 and SWEET-16 opcodes.  This same convention is used by Carl Moser's (Eastern House Software) MAE assembler, by the MOS Technology and Rockwell assemblers, and some others.  Most other assemblers use 3- or 4-character mnemonics beginning with a letter.  Which combination of letters cause the assembler to perform a particular function is not standardized at all, but there are enough similarities to make programs readable once you learn the general techniques.

What follows is an alphabetical listing of all the directives I have encountered in various manuals and magazine-published programs.  The assemblers represented are coded like this:

!lm+5
B = Big Mac            SC= S-C Macro Assembler
K = DOS Tool Kit       T = TED II
L = Lisa               W = Weller's Assembler
M = Merlin
!lm-5

In each case I have given a brief description of the directive, and tried to show how to do the same thing in the S-C Macro Assembler.  I suggest looking up the S-C directives in the reference manual if you are not sure exactly how to use them.


ADR    ADdRess                 L
Stores the expression as an address, low-order byte first.
SC:  Use .DA directive

ASC    ASCii string definition L K T B M
SC:  Use .AS or .AT directives.

AST    ASTerisks               T B M
Prints the number of asterisks specified on the listing.  Used to save space in the source file.
SC:  Not needed, because SC compresses repeated characters automatically.

BLK    BLinKing characters     L
Generates a string of characters in Apple's FLASH code.
SC:  Not available, but a combination of .AS and .HS directives will do the job.

BYT    BYTe data               L
Define data value, storing low-order byte only.
SC:  Use .DA with "#" before value.
!np
CHK    CHecKsum                B M
SC:  Not available

CHN    CHaiN to next source    K
SC:  Use .IN directive.

CHR    Set CHaR for REP directive  K
Used to create fancy comments with repeated strings; saves space in source file.
SC:  Not necessary, because SC compresses repeated characters automatically.

.DA    DAta definition         L SC
Apparently Randy borrowed this one from me.  (See the reviews he wrote in Call APPLE some time ago.)

DA     Define Address          T B M
Defines a 16-bit value with low-byte first.
SC:  Use .DA directive.

DATA   DATA definition         W
Defines numeric and ASCII data bytes
SC:  Use .DA directive, preceding each value with "#".

DB     Data Byte               T
Defines a data value, only using the low byte of the expression.
SC:  Use .DA directive with "#" before the expression.

DBL    DouBLe precision data   W
Defines 16-bit data values.
SC:  Use .DA directive.

DBY    Double BYte data        L
Generates a 16-bit value and stores it high-byte first.
SC:  Not directly available, but use .DA as follows:
       .DA /expression,#expression

DCI    Define Characters Immed L K T B M
Stores string with sign bit of last byte opposite that of the rest of the bytes.
SC:  Use .AT directive.

DCM    DOS CoMmand             L
Issue a DOS command during assembly.  Usually used to BSAVE a section of the generated object code.
SC:  Use .TF directive

DDB    Define Double Byte      K B M
Defines a 16-bit value which is stored with the high-byte first.
SC:  Not directly available, but use .DA as follows:
       .DA /expression,#expression

DEND   Dummy END               K
Marks end of a dummy section (see DSECT).
SC:  Not available

DFB    DeFine Byte             K B M
Defines one or more bytes.
SC:  Use .DA, preceding each expression with "#".

DFC    DeFine Character        L (old version)
Data definition, byte expression list
SC:  Use .DA directive, preceding each expression with "#".

DFS    DeFine Storage          L
Reserve a block of bytes.  An optional second operand will cause the reserved bytes to be set to the specified value.
SC:  Use .BS directive.  No option to set the reserved bytes to a specified value.

DO     DO                      K B M
Start a conditional assembly block.
SC:  Use .DO directive.

DPH    DePHase                 L
Terminates a PHS directive.
SC:  Not available.

DS     Data Storage            T K B M
Reserve a block of bytes.
SC:  Use .BS directive.

DSC    Data SeCtion            L (old version)
Not sure what this was for.

DSECT  Dummy SECTion           K
Starts a block in which the object code bytes are not written on the output file.
SC:  Not available.

DW     Define Word             K T
Defines a 16-bit value, with the low-byte stored first.
SC:  Use .DA directive.

.EL    ELse                    L SC
For conditional assembly.

ELSE   ELSE                    K B M
For conditional assembly, toggles the truth value from the DO directive.
SC:  Use .ELSE directive.

END    END of program          L T B M W
Most assemblers REQUIRE an "END" directive at the end of the source code.  S-C allows it but does not require it.
SC:  Use .EN directive.

ENTRY  ENTRY                   K
Indicates a symbol is to be made reference-able from other separately-assembled modules.  To be used by a linking loader program, which Apple does not provide.
SC:  Not available.
!np
EOM    End Of Macro            B M
Marks end of a macro definition.
SC:  Use .EM directive.

EPZ    Equate Page Zero        L
label  EPZ expression
Defines the label to have the value of the expression, which must be from $00 to $FF.  When EPZ-defined labels are used in address fields, zero-page addressing mode will be used whenever possible.
SC:  Use .EQ directive.  SC automatically uses page-zero mode whenever possible.

EQU    EQUate                  L T K B M W
label  EQU expression
Defines the label to have the value of the expression during the assembly process.
SC:  Use .EQ directive.

ESP    End ScratchPad          W
Works with SPD to bracket a data section.
SC:  Not needed.

EXP    EXPansion of macros     B M
Controls whether macro expansion code is printed or not on the output listing.
SC:  Use .LIST directive.

EXTRN  EXTeRNal                K
Indicates that a label is externally defined.  To be used with a linking loader program, which Apple does not provide.
SC:  Not available.

.FI    end of conditional      L SC

FIN    end of conditional      K B M
SC:  Use .FIN directive.

FLS    FLaSH                   B M
Define a string in flashing mode.
SC:  Not available, but a combination of .AS and .HS directives will do the job.

GEN    GENerate code listing   L
Turns on listing of all object code bytes.
SC:  Not available, object code listing is always on.

HBY    High BYte               L
Define one-byte data value, storing only the high-byte of an expressions value.
SC:  Use .DA directive, writing "/" before the value.

HEX    HEXadecimal data        L T B M
label  HEX hexstring
SC:  Use .HS directive.
!np
ICL    InCLude                 L
Really is a CHAIN to next source file.
SC:  Use .IN directive.

.IF    conditional assembly    L
SC:  Use .DO directive.

INV    INVerted characters     L B M
Generates a string of characters in Apple's INVERSE screen code.
SC:  Not available, but you can convert to hexadecimal and use .HS directive.

LET    label reassignment      L
Same as EQU, except label can be redefined during assembly.
SC:  Not available.

LST    LiST option             L T K B M
Turn assembly listing on or off.
SC:  Use .LIST directive.

MAC    MACro definition        B M
Start a macro definition.
SC:  Use .MA directive.

MSB    Most Signficant Bit     K
Controls whether the ASC directive generates bytes with the first bit set or clear.
SC:  Use .AS or .AT directives with or without the "-" before the first delimiter to indicate the MSB value.

NLS    No List option          L
Turn assembly listing off.
SC:  Use .LIST OFF directive.

NOG    NO Generate             L
Turns off listing of all but first three bytes of any particular source line.
SC:  Not available.

OBJ    OBJect address          L T B M
Set actual memory address for assembled object code to be stored in.
SC:  Use .TA directive.

ORG    ORiGin                  L T K B M
Set memory address program will execute at.
SC:  Use .OR directive.

PAG    PAGe eject on listing   L T B M
Sends control-L to listing device.
SC:  Use .PG directive.

PAGE   PAGE eject on listing   K
Sends control-L to listing device.
SC:  Use .PG directive.
!np
PAU    PAUse and force error   L B M
SC:  Not available.

PHS    PHaSe                   L
Allows setting ORG without changing OBJ.  Terminated with DPH.
SC:  Not available.

PMC    Present MaCro           B M
Opcode to call a macro.
SC:  Not needed, macros are called by their own names.

PR#    Select printer slot     T
SC:  Select before assembly begins using DOS "PR#slot" command, or SC "PRT" command.

REL    RELocatable object      K
Causes assembler to generate a relocation dictionary at the end of the object file, for use by Apple's relocating loader.
SC:  Not available.

REM    REMark                  W
Used to indicate a comment line.
SC:  Use "*" in first column of label field.

REP    REPeated character      K
Generates a string of repetitions of the current CHR value on the output listing.  Used to save space in the source file.
SC:  Not needed, because SC automatically compresses repeated characters.

SAV    SAVe object code        B M
SC:  Use .TF directive.

SBTL   SuBTitLe                K
Provides a title line for the top of each page of the output listing.
SC:  Use .TI directive.

SKP    SKiP lines              K B M
Leaves a specified number of blank lines in the output listing.
SC:  Not available.

SPD    ScratchPaD              W
Works with ESP to bracket a data section.
SC:  Not needed.

STR    STRing                  L
Similar to Lisa's ASC except the first byte output is the length of the string.
SC:  labela .DA #labelb
            .AS /string/
     labelb .EQ *-labela-1

SYM    SYMbols                 T
Produces a symbol cross-reference table at end of assembly.
SC:  Not available, but can use Rak-Ware's XREF utility program.
!np
TITL   TITLe                   
TTL    TiTLe                   L
Generates title line at top of each page of listing.
SC:  Use .TI directive.

TR     TRuncate object listing B M
Limit listing of object code to 3 bytes per source line.
SC:  Not available.

USR    USeR directive          L
An extra entry in the directive table for the user to use as he sees fit.
SC:  Use .US directive.

;      comment indicator       L
SC:  If ";" was in first column, use "*" instead.  If in later column, no special character is needed.

=      equate                  B M others
If written with label on left, this is the same as EQU and .EQ directives.  If written with "*" on the left, it is the same as ORG and .OR directives.

<<<                            B M
Alternate syntax for EOM.
SC:  Use .EM directive.

>>>                            B M
Alternate syntax for PMC.
SC:  Not needed, because macros are called by their own names.


Directives in Roger Wagner's Book

If you have been trying to learn using the S-C Assembler with Roger's book "Assembly Lines:  The Book", you may have been frustrated by his use of several assembler directives.  He discusses directives on pages 16-18, and 55.

On page 16, the first example of the use of directives has two errors.  Lines 6 and 7 are written:

!lm+5
6  OBJ EQU $300
7  ORG EQU $300
!lm-5

But they should be:  6    OBJ $300
                     7    ORG $300

That is, OBJ and ORG are directives, not labels.  The top two lines on page 21 are also incorrect, in that the ORG and OBJ directives were typeset to look like labels; they should be moved over to the opcode column, and the "$300" values to the operand column.
!np
In all, Roger uses only five directives in his book:  OBJ, ORG, EQU, ASC, and HEX.  To use his programs in the S-C assembler, change:

!lm+5
 From                   To
----------------       ----------------
label EQU value        label .EQ value
label HEX hexdigits    label .HS hexdigits
      HEX hexdigits          .HS hexdigits
label ASC "characters" label .AS -"characters"
      ASC "characters"       .AS -"characters"
      OBJ $300 or $302     omit this line
      ORG $300 or $302       .OR $300 or $302
!lm-5

Note that the normal translation of "OBJ" is ".TA"; however, when the address is the same as the ORG/.OR address, it is not necessary to use OBJ/.TA.  Furthermore, in the S-C Assemblers you must put the ".OR" line BEFORE the ".TA" line.  In Roger's examples these two lines are reversed.

