*CLIST/NOCLIST


These options allow you to control whether or not the conditional
assembly control instructions (IFcc and ENDC) are output to the
assembly listing. 

CLIST - control instructions are listed.

NOCLIST - control instructions are not listed.

Default - control instructions are listed.

The option becomes effective at the point specified and is reset to the
default setting at the end of pass 1



*LIST/NOLIST


These options allow the user to control whether or not the source
code statements are listed. 

LIST - the statements are listed.

NOLIST - the statements are not listed.

Default - the statements are listed.

The option becomes effective at the point specified and is reset to the
default setting at the end of pass 1



*LISTF


This option causes a listing to be generated on the first pass.  This is
not normally necessary but can be useful if you are trying to identify
errors that occur on the first pass.  A symbol table will also be
generated following the first pass if the SYM directive has been used. 

LISTF - the statements are listed on the first pass.

Default - the statements are not listed on the first pass.

Note that LISTF will not generate a listing if the LIST directive has not
been used.  To force a listing on the first pass even if the LIST
directive has not been included in the source code, include both LISTF
and LIST in the command line as follows:

XASM /LISTF /LIST



*MC/NOMC


These options allow you to control whether or not the macro calls are
output to the assembly listing. 

MC - Macro calls are listed.

NOMC - Macro calls are not listed.

Default - Macro calls are listed.

The option becomes effective at the point specified and is reset to the
default setting at the end of pass 1



*MD/NOMD


These options allow you to control whether or not the macro
definitions are output to the assembly listing. 

MD - Macro definitions are listed.

NOMD - Macro definitions are not listed.

Default - Macro definitions are listed.

The option becomes effective at the point specified and is reset to the
default setting at the end of pass 1



*MEX/NOMEX


These options allow you to control whether or not the macro
expansions are output to the assembly listing.

MEX - Macro expansions are listed.

NOMEX - Macro expansions are not listed.

Default - Macro expansions are not listed.

The option becomes effective at the point specified and is reset to the
default setting at the end of pass 1


*OBJ/NOOBJ


These options allow you to control whether or not any object code is
send to the object code file.

OBJ - Object code is filed.

NOOBJ - No object code is filed.

Default - Object code is filed.



*PAGE/NOPAGE


These options allow you to enable and disable 'paged mode' of the
assembly listing.  With paged mode enabled, page breaks are
automatically generated and page headers are produced. 

PAGE - enables paged mode of the assembly listing.

NOPAGE - disables paging of the assembly listing.

Note: The use of PAGE to enable paged mode can only be used in
the command line or in the operand following the OPT directive. 
When PAGE is used in the operation field it has a different meaning. 
See the next section.

*PAGE Paging Control

The PAGE directive allows you to control the page breaks of the
assembly listing. 

Note that PAGE can have different meanings defending on whether or
not it has an operand. 

PAGE <expression> - sets the number of lines per page to the value
of expression.  Note that this option can only be used with page in the
operation field and not in the command line or following the OPT
directive. 

The default lines per page is 66.  

PAGE - a page break is sent to the assembly listing.
*PAGE continued

Note that this latter form of PAGE cannot take any comments
otherwise they will be mistaken for an expression and note that also
the line containing the PAGE directive is not listed. 

Note that the assembly option PAGE included in the command line or
in the operand following the OPT directive is different to the PAGE
directive here.  The assembly option PAGE enables paged mode and
is described above






*SEQON/NOSEQ


These options allow the user to control whether line numbers or
sequence numbers are displayed in the first field of the assembly
listing.  The options are only effective if sequence numbers are
included in the source code. 

SEQON - sequence numbers are displayed.

NOSEQ - line numbers are displayed.

Default - line numbers are displayed

The option becomes effective at the point specified and is reset to the
default setting at the end of pass 1


*SYM


This option causes a symbol table listing to be generated showing the
symbol names and their values.  This is listed immediately following
the end of assembly. 

SYM - Generate a symbol table

Default - Do not generate a symbol table.



*UNA/NOUNA


These options allow the user to control whether or not the
unassembled statements, skipped as a result of the conditional
assembly conditions not being satisfied, are listed. 

UNA - unassembled statements are listed.  The statements are
displayed unformatted. 

NOUNA - unassembled statements are not listed.

Default - unassembled statements are not listed.

The option becomes effective at the point specified and is reset to the
default setting at the end of pass 1



*IHEX/BIN


These options allow the user to control whether object code is
generated as Intel hex. records or as binary data.

IHEX - object code is generated as Intel hex. records.

BIN - object code is generated as binary data.

Default - object code is generated as Intel hex. records.


*DEFB  Define Constant Byte


This directive inserts a series of byte values into the object code. The
format is:

        DEFB [Exprn],[Exprn],[Exprn],....

The expressions are sequentially evaluated and the byte values
generated are stored sequentially in the program object code. If an
expression is null (nothing is written between the commas or before
the first comma) then zero is assigned.

Example:

    1                              nam     defbxampl   l
    2                              ttl     define byte
    3 0021               variable  equ     $21         
    4 0000 16 CF 00 21   label     defb    $16,%11001111,,variable 



*DEFL  Define Label Value (Variable)


The DEFL directive will define the symbol in the label field to have the
value of the expression in the operand field.  Unlike with the EQU
directive, the DEFL directive allows the symbol to subsequently be
redefined by another DEFL directive. 

Format:

<label>  DEFL   <expression>   <comment>



*DEFM  Define Memory


This directive stores a string as data. There are two formats for the
instruction:

DEFM n,<Ascii character string>

where n is a decimal number that indicates the number of characters
required in the string. A comma must follow the number and the
character string is placed immediately after the comma. (A comma can
still be used in the character string).

When n is greater than the number of characters in the character
string, then $20's (Ascii space character) are appended to the data
generated to make up the total number bytes.

When n is smaller than the number of characters in the character
string, then the string is truncated with only the first n characters being
used.
*DEFM continued

DEFM d<string>d

This form of fcc requires the character string to be enclosed in
delimiters (symbolised above by 'd'). The delimiter may be any valid
character including a digit (but if a digit is used, the first character of
the string should not be a comma since the cross-assembler will then
assume that the operand is the previous form of fcc). The same
delimiter must be used to end the string as is used at the beginning.


Examples:

    1                              nam     defmxampl   l
    2                              ttl     define memory
    3 0000 54 72 75 6E   label1    defm    4,Truncated 
    4 0004 46 69 6C 6C   label2    defm    12,Filled   
      0008 65 64 20 20
      000C 20 20 20 20
    5 0010 53 74 72 69   label3    defm    "String"    
      0014 6E 67
*DEFS  Define Space

The format for this directive is:

DEFS [Exprn]

This reserves an area of object code space [Exprn] bytes long and fills it 
with $FF's. The bytes generated are not displayed in the assembly listing.

    1                              nam     defsxamp    
    2                              ttl     define space
    3
    4 0000               label1    defs    21          
    5 0015               label2    
Assembly complete
Bytes filed: 21
0 errors 0 warnings

This produces the following data (in Intel hex. format):

:10000000FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF00
:05001000FFFFFFFFFFF0
:00000001FF
*DEFW  Define Word

This directive inserts a series of double byte values into the object
code. The format is:

        DEFW [Exprn],[Exprn],[Exprn],....

The expressions are sequentially evaluated and the two byte values
generated are stored sequentially in the program object code. The low
byte is stored first (ie at the lowest address) and the high byte is
stored second. As with DEFB, if an expression is null (nothing is
written between the commas or before the first comma) then zero is
assigned.

Example:

    1                              nam     defwxampl   l
    2                              ttl     define word
    3 79F1               variable  equ     $79F1       
    4 0000 00 00 32 91   label     defw    ,$9132,,variable,$16 
      0004 00 00 F1 79
      0008 16 00
*END   Specifies End of Source Code


The END directive indicates to the cross-assembler that the source
code has ended.  If source code is present after this directive, it will
not be assembled. 

The END directive is not compulsory.  Assembly will continue up to
the end of the file if it is not present. 

The END directive is ignored if it is present in a file that has been
specified by the INCLUDE directive although a warning message is
generated on the second pass to indicate that the directive has been
encountered under such circumstances. 

The END directive cannot be included in a macro definition. 

Format:

END             <comment>



*ENDC  Specifies the End of Conditional Assembly


The ENDC directive indicates the end of a block of statements to be
conditional assembled.  Conditional assembly directives can be nested
and so the ENDC matches the previous IFcc directive.  An error is
generated if a matching IFcc directive has not been encountered. 

See the section on conditional assembly for more details. 

Format:

        ENDC                   <comment>



*ENDM  Specifies the End of a Macro Definition

The ENDM directive is used to define the end of a block of statements
constituting a macro definition.  Macro definitions cannot be nested. 

An error is generated if a matching MACR directive has not been
encountered. 

See the section on macros for more details.

Format:

        ENDM                   <comment>



*EQU   Define Symbol Value (Invariable)


The EQU directive will define the symbol in the label field to have the
value of the expression in the operand field.  The symbol cannot
subsequently be re-defined. 

Format:

<label>  EQU   <expression>   <comment>



*FAIL  Generate Assembly Warning


The FAIL directive generates a warning message:

"Warning at line xxxx  FAIL directive encountered"

and adds one to the warning count. After the warning has been
generated, assembly proceeds normally.

The FAIL directive is most useful when used in conjunction with
conditional assembly.  It can then be used to check such things as the
number of operands in a macro call, the value of a symbol, etc.  The
chapter on conditional assembly contains an example which uses the
FAIL directive. 

Format:

        FAIL           <comment>
*FIELDS    Set Object Listing Field Widths 

The FIELDS directive allows the user to adjust the widths of the label,
operation and operand fields of the assembly listing.

Format:

      FIELDS    <exprn1>,<exprn2>,<exprn3>      <comment>

where  <exprn1> is the required width in characters of the label field
       <exprn2> is the required width in characters of the operation field
       <exprn3> is the required width in characters of the operand field

A null expression (nothing between the commas) leaves the field width set
to the default value.

The default values are:

label field width:     10
operation field width: 10
operand field width:   18
*IFC/IFNC/IFIC/IFINC Conditional Assembly with String Comparison

These directives cause the assembly of the subsequent block of
statements to be dependant upon the comparison of two character
strings in the operand.  The ENDC directive marks the end of the
statement block. 

The format for the directives are:

IFC             <string 1>,<string 2>  <comment>
IFNC            <string 1>,<string 2>  <comment>
IFIC            <string 1>,<string 2>  <comment>
IFINC           <string 1>,<string 2>  <comment>

The statements following IFC and IFIC will be assembled if string 1
and string 2 are the same.  The statements following IFNC and IFINC
will be assembled if string 1 and string 2 are different.  IFC and IFNC
perform a case sensitive comparison on the two strings whereas IFIC
and IFINC perform a case insensitive comparison.

*IFC/IFNC/IFIC/IFINC continued

These directives are usually used in macro definitions where either one
or both of the strings is a macro argument.  The directives can then
be used to generate different object code depending on the string or
strings passed in the argument or arguments. 

These conditional assembly directives can be nested.

*IFcc Conditional Assembly with Numerical Comparison

The IFcc directives cause the assembly of the subsequent block of
statements to be dependant upon the value of the expression in the
operand.  The ENDC directive marks the end of the statement block. 

The format for the directive is:

IFcc            <expression>  <comment>

where cc indicates two characters such as EQ, NE etc.

The statements following IFcc will be assembled if the expression
values satisfy the conditions listed below:

IFEQ                   <Expression> =  0
IFNE                   <Expression> <> 0
IFGE                   <Expression> >= 0
IFGT                   <Expression> >  0
IFLE                   <Expression> <= 0
IFLT                   <Expression> <  0

Conditional assembly directives can be nested.
*INCLUDE Include Another Source Code File

The INCLUDE directive will cause the cross-assembler to read the
subsequent source code statements from the file which is specified in
the operand.  The file specification, which can be up to 120 characters
in length, should include the directory path unless the file is in the
current directory. If the file specification does not include an extension
then .ASM is assumed as with the main source file name.

When the end of the included file is reached, assembly continues at
the statement following the INCLUDE directive. 

The assembler generated line numbers start from 1 in the included file
and re-commence at their previous value when assembly of the
included file has been completed. The line numbers therefore directly
correspond with the line numbers of the files.

Included files can be nested but cannot be included recursively since
then the file would already be open and could not be opened again.

If the NAM and END directives are present in an included file, they will
be ignored although on the second pass a warning will be given. 
*INCLUDE continued

The cross-assembler resets its internal sequence number counter to
zero when it starts processing the included file and restores it to its
original value when assembly of the included file has been completed.
Consequently if sequence numbers are being used, it is not necessary
for the numbers in the included file to follow sequentially those of the
file that contained the include directive. However, if sequence numbers
are being used in the main file then they must be used in all included
files too. Similarly, if the main file does not contain sequence numbers,
then neither must the included files.



*MACR Macro Definition

The MACR directive specifies that the following statement block is a
macro definition.  The directive ENDM marks the end of the statement
block. 

The MACR directive requires a label which is subsequently used to
reference that definition during a macro call statement.  More details
are given in the chapter on macro functions. 

A 'C' can be optionally included in the operand field.  If present, all
comment statements beginning which an asterisk will be stored as
part of the macro definition so that they can be listed when the macro
is expanded.  When a 'C' is not present, these comment lines will not
be stored, thus saving memory (since the macro definition is stored
in ram). 

Macro definitions cannot be nested.

Formats:

<label>                MACR   <comment>
<label>                MACR   C   <comment>
*NAM  Program Name


The NAM directive allows a program name to be specified.  This may
be up to 8 characters in length.  The program name is displayed in the
header line of each page of the assembly listing.

The NAM directive is usually the first statement in the source code but
this is not essential, it can be placed anywhere within the source code.
It may only be used once.  If the cross-assembler encounters the
directive a second time, an error will be generated, unless it is within
an included file in which case it will be ignored and a warning
message given on the second pass. 

Format:

NAM             <character string>             <comment>



*OPT  Assembly Options


Assembly options may be included in the operand following the OPT
directive.  This allows multiple options to be included on a single line.
See the separate section on assembly options for more information on
this directive. 

Format:

OPT             <option list>                  <comment>

Options should be included in the option list separated by commas
and without any intervening spaces.



*ORG  Specifies Program Origin


The ORG directive sets the program counter to the value of the
operand. If the ORG directive is not used, the program counter is
assumed to be zero.

The use of the ORG directive to change the program counter value
after some object code has already been generated has a different
effect depending on whether Intel hex. record or binary object code
format is being generated.  The different actions are described below:

Intel Hex. Record Format

When the object code is being generated in Intel hex. record format,
the ORG directive causes the current data record to be closed. 
Subsequent code will cause a new data record to be opened which
will include the new program counter value.
*ORG continued

Binary Format

When the object code is being generated in binary format, the
program counter value is not stored in the object code. Consequently
the program counter can only be increased.  Blank space will be
generated to fill the file so that it remains a correct ram/rom image of
the machine code.  See the chapter on 'object code format' for more
information, noting that it is preferable with binary format to use ORG
before any code is generated. 

*PAGEWIDTH        Adjust Page Width of Assembly Listing

The PAGEWIDTH directive is used to set the page width of the assembly
listing.

Format:

      PAGEWIDTH       <exprn>         <comment>

where <exprn> evaluates to the maximum length of a line in characters.

Text in the assembly listing that extends beyond the page width is wrapped
into the appropriate field of the following line.

By default there is no maximum line length and no line wrapping occurs.
*SPC  Output Blank Lines


The SPC directive will instruct the cross-assembler to output blank
lines to the assembly listing.  The number of blank lines output is
determined by the value of the expression in the operand field.  If the
paged mode is disabled, the total number of blank lines specified in
the expression will be output.  If the paged mode is enabled, then the
number of blank lines output may be less if a page break is reached
beforehand.  (I.e. blank lines will not be carried forward onto the next
page.)

The line containing the SPC directive is not listed.

Format:

SPC             <expression>                   <comment>



*TTL  Specify Title


The TTL directive instructs the cross-assembler to use the following
text string as a title.  The text string extends from the first non-space
character following the TTL directive to the end of the line.  The title
can therefore contain spaces.  Up to 45 characters are allowed in the
title string. 

The title is displayed on the header line of each page if paged mode
is enabled. 

The title can be changed at any time by the further use of the TTL
directive. 

Format:

        TTL            <string>
*
