4/18/92
                         Pure C English Overview
        (or, "What Your 'Mutter' Never Told You About Pure C")
                              by Dan Wilga

            Document Copyright (c) 1992 by Gribnif Software


The Pure C package comes, as you have probably noticed by this time, with
German documentation.  As this is not likely to change in the near future, we
have decided to present people who purchase the package from us with a
description of the important features of the programs in English.

Certainly, the information in this document is far from the content of the full
manuals. However, careful attention has been paid to covering those details
which would not normally be obvious without understanding the manuals.

We strongly suggest that you read as much of this document as possible. While
you may never use some of the information covered, many important features of
the package may be revealed to you by reading it fully.


Installation
------------

  Probably the easiest way to install Pure C is in the format in which it is
  provided.  Simply create a PURE_C folder somewhere on one of your hard drives
  (with about 2 Mb free) and copy the contents of all three disks into it.

  This is a description of the major files in the distribution:

    PC.PRG            Programming environment
    PC.CFG            Default configuration file
    CPP.TTP           Pure C compiler pre-processor
    PCC.TTP           Pure C compiler
    PCC.CFG           Pure C compiler default configuration
    PD.PRG            Pure Debugger
    PD.CFG            Default configuration file
    BGIOBJ.TTP        Converts BGI fonts to .O files
    DISPOBJ.TTP       Display object files
    HC.TTP            Help compiler
    PASM.TTP          Pure Assembler
    PLINK.TTP         Object file linker
    C.HLP             C language help
    LIB.HLP           C libraries help
    PASM.HLP          Pure Assembler help
    PD.HLP            Pure Debugger help
    FONTS\            Fonts used by BGI routines
    PC_FSEL\          Replacement file selector
    PC_HELP\          Help desk accessory
    INCLUDE\          Header files
    LIB\
      PC881LIB.LIB    68881/2 floating point library
      PCBGILIB.LIB    Borland Graphics Interface library
      PCEXTLIB.LIB    Pure C extensions library (see: ext.h)
      PCFLTLIB.LIB    Floating point library
      PCGEMLIB.LIB    AES/VDI library
      PCLNALIB.LIB    Line A library
      PCSTDLIB.LIB    Standard library (stdio, etc.)
      PCTOSLIB.LIB    BIOS/XBIOS/GEMDOS library
      PCSTART.S       Source for default runtime module
      PCSTART.O       Object file for same
      PCVSTART.S      Source for runtime module with extended argument (ARGV)
                      passing
      PCVSTART.O      Object file for same
      PCXSTART.S      Source for runtime module with i/o redirection as part of
                      commandline
      PCXSTART.O      Object file for same


The Pure C Environment (PC.PRG)
-------------------------------

  While the separate parts of the Pure C compiler/assembler/debugger can all be
  used independently, the easiest way to manage a large project is by using the
  integrated environment, PC.PRG.

Editing Keys
------------

  Shift up arrow        Scroll up one page
  Shift down arrow      Scroll down one page
  Shift left arrow      Move to start of line
  Shift right arrow     Move to end of line
  Control left arrow    Move to start of word
  Control right arrow   Move to start of next word
  Backspace             Delete character to left of cursor
  Delete                Delete character to right of cursor
  Home                  Start of file
  Shift Home            End of file
  Control Y             Yank (cut) current line
  Click                 Move cursor
  Shift click           Add to selection
  Double-click          Select word
  Shift double-click    Select an entire line
  Undo                  Undo last keystroke
  Insert                Same as Paste

  Note that using the scroll bar does not affect the cursor location. This
  means that if you use the scroll bar to reposition the file being edited and
  then type a character, that character will appear where the cursor was (and
  still is) before the window was scrolled.

  If a block is selected when a normal key is pressed on the keyboard, that
  entire block will be replaced with the one character, so caution should be
  used.

Error Message Windows
---------------------

  A second type of window, which cannot be edited, appears when the compiler
  generates error messages. The contents of this window can be viewed like
  other text windows, but they cannot be changed. To quickly jump to a
  particular error in the appropriate source file, simply double-click anywhere
  on an error message. This action is similar to the "Find Error" menu entry.

Pure C's Help System
--------------------

  Yet another type of window which can be opened is for help messages. There
  are two ways to access the help, either directly from the menu or by pressing
  the Help key. In the case of the Help key, the help libraries will be
  searched for an entry which matches the word currently under the cursor. This
  can be especially helpful for situations where you cannot remember what
  parameters to pass to a library function.

    Help Window Controls
    --------------------

    Double-click on an underlined word or phrase   Jump to that help reference
    Help key while cursor is at underlined word    Jump to that help reference
    Undo key                                       Back up to previous help
                                                     screen
    
  Another use of the help system is to point out the declaration of a
  variable, constant, or function *within your own source code*. For instance,
  if you are working on a program which uses a number of header files to define
  variables and you want to find out how the variable "MaxValue" is defined,
  you simply have to place the edit cursor on the word "MaxValue" somewhere in
  the source code and press the Help key. If you have just recently compiled
  your program (and Pure C's internal caches have not been flushed) then the
  header file in which "MaxValue" is declared will be opened and the
  appropriate line will be shown. Note that this feature cannot work if you
  quit Pure C and then re-run it, because the caches are flushed; you must
  re-compile the program.


The Item Selector
-----------------

  Pure C employs (yet another!) enhanced item selector which offers many
  advantages to the standard Atari item selector. All of its operations can be
  controlled from the keyboard:

    Alt <drive letter>          Select disk drive
    Up/Down arrows              Change selected file/folder
    Return                      Open selected folder/file
    Insert                      New filename
    Delete                      Delete selected file
    Esc                         Swap disks (update file list)
    Undo                        Back up one directory level
    Control-U                   Exit item selector (like Cancel button)
    Extensions (*.C, *.H, etc.) See page 15 of your Pure C Compiler manual
    
  One other nice feature of the item selector is the ability to select a file
  or folder from a long list by simply typing the first few characters of its
  name. For instance, suppose you have the following items:

    *BIN
    *LIB
     BAR.C
     FOO.C
     FOX.C
     ZZZ.C

  To open the LIB folder, you merely have to press 'L' (select the folder) and
  then hit the Return key (Open it). To open the file FOX.C, in this case, you
  can either press 'F' and then move the selection down one line with the down
  arrow key, or you can type 'OX' to narrow the search. In either case,
  pressing Return will cause the file FOX.C to be opened.


Modifications of Menu Commands
------------------------------

  Two menu commands have alternate forms which are not otherwise obvious:

    Control Shift Q       Quit without autosaving configuration
    Shift Alt D           Debug, removing PC.PRG from memory first


Compiler Options
----------------

  Some of the compiler options are explained in more detail here. The remainder
  can be found in the "Compiler..." dropdown menu entry.
  -2        Generate 68020 code. Resulting program will not run on a 68000 CPU!
  -8        Generate 68881 code.
  -A        Non-ANSI keywords "cdecl" and "pascal" will generate errors.
  -B        Write objects (.O) in DRI format, instead of Pure C format. If this
            switch is on, then the Pure Debugger will not be able to use a
            source file window because the DRI format does not permit extended
            debugging information.
  -E#       Maximum number of error messages before break.
  -F#       Maximum number of warning messages before break.
  -H        Force "cdecl"-style function calling. Passes parameters on stack
            instead of in CPU registers.
  -L#       Maximum identifier length.
  -M        No string merging. Normally, Pure C checks to see if part of one
            string can actually be defined as being the tail end of another. An
            example would be the two strings "nobody" and "body", which could
            be merged into one string. This option can be disabled if your code
            needs to modify static string contents without affecting other
            strings.
  -Nname    Output file directory.
  -Oname    Output file name.
  -P        Use absolute calls (JSR's) instead of PC-relative ones. If you get
            a linker error which says there is a "16-bit PC-relative overflow",
            this option must be used.
  -S        Standard stackframes, using LINK and UNLINK instructions.
  -T        Stack checking. An error message will be produced if insufficient
            stack space has been reserved.
  -Wxxx     Disable (-W-xxx) or enable (-Wxxx) a compiler warning message.
            Similar to the #pragma warn preprocessor directive. Options:
            Adherance to ANSI standards:
                -Wdup   Redefinition of XXX is not identical. (default: ON)
                -Wret   Both return and return of a value used. (ON)
                -Wstr   XXX not part of a structure. (ON)
                -Wstu   Structure XXX is not defined. (ON)
                -Wsus   Suspicious pointer conversion. (ON)
                -Wvoi   Void functions may not return a value. (ON)
                -Wzst   Zero length structure. (ON)
            Common Warning Messages:
                -Waus   XXX is assigned a value which is never used. (ON)
                -Wdef   Possible use of XXX before definition. (ON)
                -Weff   Code has no effect. (ON)
                -Wpar   Parameter XXX is never used. (ON)
                -Wpia   Possibly incorrect assignment. (ON)
                -Wrch   Unreachable code. (ON)
                -Wrvl   Function should return a value. (ON)
            Less Common Warnings:
                -Wamb   Ambiguous operators need parentheses. (OFF)
                -Wamp   Superfluous & with function or array. (OFF)
                -Wnod   No declaration for function XXX. (OFF)
                -Wpro   Call to function with no prototype. (ON)
                -Wstv   Structure passed by value. (OFF)
                -Wuse   XXX declared but never used. (OFF)
            Portability Warnings:
                -Wapt   Non-portable pointer assignment. (ON)
                -Wcln   Constant is long. (OFF)
                -Wcpt   Non-portable pointer comparison. (ON)
                -Wrng   Constant out of range in comparison. (ON)
                -Wsig   Conversion may lose significant digits. (OFF)
                -Wucp   Mixing poiners to signed and unsigned char. (OFF)
                -Wrpt   Non-portable pointer conversion. (ON)
  -X    Generate underbars. All identifier names are preceded with a "_"
        character. This is mostly for compatibility with Mark Williams C
        modules.
  -Y    Add debug information for use with the Pure Debugger. This option must
        be set in order to get a C-source window within the debugger.


Preprocessor
------------

  The only unusual preprocessor directive supported by Pure C is #pragma. In
  this implementation, the only option is "warn", for enabling or disabling
  certain compiler warnings. The syntax is always one of these:
  
    #pragma warn -w        (enable all warnings)
    #pragma warn -xxx      (where "xxx" is a warning type to disable)
    #pragma warn +xxx      (where "xxx" is a warning type to enable)

  For a list of the warning types, refer to the -W compiler option.

  Pure C defines several preprocessor constants:
  
    __LINE__    Line number.
    __FILE__    Name of file being compiled.
    __DATE__    File compilation date.
    __TIME__    File compilation time.
    __STDC__    True (1) if the "ANSI keywords only" (-A) option is used.
    __PUREC__   Contains the version number of the compiler. Useful
                as a check to see if the Pure C compiler is being used.
    __TURBOC__  Same as __PUREC__.
    __TOS__     Always 1.


Assembler Options
-----------------

  The -1, -2, -3, -4, -5, and -8 options can be used to prevent an error
  message when the assembler encounters an instruction which is not part of the
  standard 68000 instruction set. Similarly, the -S option prevents errors from
  being generated when a supervisor mode instruction is encountered.

  The -U option forces all undefined symbols to be considered external. This
  avoids having to use the IMPORT and EXPORT assembler directives.


Linker Options
--------------

  The stack size for a program depends on many factors, such as the number and
  size of local variables, the level to which function calls are nested, and
  the number of parameters passed in function calls. The -T (stack checking)
  compiler switch can be helpful for determining the correct stack size for a
  particular program. Note that because Pure C normally passes function
  arguments in CPU registers, the amount of stack space required by a Pure C
  program can be significantly less than that required by other compilers.

  Options G, L, and Y should always be set if you intend to use the resulting
  program with the Pure Debugger. The program should be re-linked without these
  options to produce the final version, as this consumes much less disk space.
  
  The -F option prevents the FastLoad bit from being set in the program's
  header.  This attribute only affects programs which are run by TOS versions
  1.4 or newer.  This attribute must NOT be set (that is, you should use the -F
  option) for any program which can be run as a desk accessory, since the
  operating system can crash when a desk accessory has this attribute set.
  
  The -J option generates a new object file. This can also be used to create a
  linkable library from several .O files.
  
  The -R and -M options affect operation on the Atari TT computer, which has
  both fast RAM and normal ST RAM. If your program will be performing raw disk
  i/o or setting the screen display base to a block of memory it receives by
  way of the Malloc call, then the -M flag should be set so that the Malloc
  will return a block of memory in ST RAM rather than Fast RAM.

  The segment addresses should normally be left blank. They are intended for
  linking position-dependent code, such as something that will be burned into
  ROM.
  

Project (.PRJ) Files
--------------------

  The syntax for Project files follows. Items in braces {} are optional. A bar
  | denotes a choice between two options.

      { output_file | * }
      { .L [ <linker_options> ] }
      { .C [ <compiler_options> ] }
      { .S [ <assembler_options> ] }
      =
      <module_name1> { ( <dependent_files> ) }
      <module_name2> { ( <dependent_files> ) }
      ...
      
  Each module_name can either be an asterisk "*", to represent the topmost
  source file window, or one of the following:

      <assembler_file> { [ <assembler_options> ] }
      <C_source_file> { [ <compiler_options> ] }
      <object_file>
      <library_file>
      <project_file>

  The order in which modules appear in the list dictates the order in which
  they are linked. For this reason, the startup module should always come first
  and the libraries should usually come last.

  This sample project file will compile the files MYACC1.C (which is the
  topmost window), MYACC2.C, MYACC3.S, and will link the standard and GEM
  libraries. The compiler switch for 68020 code is enabled for MYACC2.C, and
  the assembler switch for priviledged instructions (-S) is set globally. The
  file MYACC1.C depends on the file HEADER.H not having changed since the last
  compilation. The output file is MYACC1.ACC.

      *.ACC           ; topmost window name with ACC extension
      .S[-S]          ; assembler options
      =
      PCSTART.O       ; startup module comes first
      * (HEADER.H)    ; compile topmost window MYACC1 if it or
                      ; HEADER.H has changed
      MYACC2.C [-2]   ; compile MYACC2.C with 68020 code generation
      MYACC3.S        ; assemble with options above
      PCSTDLIB.LIB    ; link standard library
      PCGEMLIB.LIB    ; link AES/VDI library


The Runtime Startup Modules
---------------------------

  Pure C includes several different compiler startup modules, for different
  purposes. Most likely, you will probably want to use the default, PCSTART.S.
  Essentially, these startups all perform the same actions:

    Find out how much memory the program requires and return (Mshrink) unused
      memory.
    Parse the commandline and prepare a list of pointers to the individual
      parameters.
    Prepare a list of pointers to the environmental variables.
    Determine if the computer has a floating point math coprocessor.
    Call the main portion of the program.
    Clean-up any malloc'd blocks and open files.
    Terminate.

  A program's "main" function receives three parameters: argc, argv, and envp.
  The first two are common to most C compilers. The envp parameter is a pointer
  to a null-termianted array of pointers to environmental variables. For
  example, to display a program's environment, you could use:

    int main( int argc, char *argv[], char *envp[] )
    {
      while( *envp )
      {
        printf( *envp );
        envp++;
      }
    }

  Please note that since the runtime startups all look at the return value from
  "main" and return this to the process which executed the program, it is a
  good practice to always return something, most likely zero. In the case of
  the sample program above, a line with "return 0;" should be added.


Writing Desk Accessories
------------------------

  Pure C's startup modules all contain a test to see if a particular program is
  running as a desk accessory or as a regular program. The int "_app", which is
  defined in AES.H, is zero if the program is running as a desk accessory.


Helpful Hints
-------------

  Using CFG and PRJ files:

  Whenever you begin a new project, it is a good idea to start by establishing
  a new configuration (CFG) file. This can be done by selecting the "Load..."
  option in the "Options" drop-down menu. If you press the New button in the
  item selector, you will be asked for the name of a new CFG file.

  From this point, you should set the compiler and assembler options to the
  way you will want them for the particular program you are compiling. You
  should also create a new project (PRJ) file or select an exisiting one. Be
  sure to Save Configuration if you do not have the Autosave option turned on.

  Now, whenever you want to work on the program further, you can simply call up
  the "Load..." menu entry and give it the name of the CFG file. Another method
  is to use the desktop's Install Application feature to install PC.PRG for the
  extension CFG. This way, you simply have to double-click on the CFG file to
  get PC.PRG to come up with the correct files loaded.

  Using warning level 1:

  In the Compiler Options dialog, there are three warning levels which can be
  used:
  
    0   Ignore all warning messages
    1   Produce some warning messages
    2   Produce all warning messages

  Experience has shown that, for most applications, number 1 is probably the
  best choice. This level corresponds to the ON/OFF defaults listed in the
  section of this document which describes the -W compiler switch. Level 0
  ignores so many warnings that the code which is generated may not be runable
  if the -H compiler switch is not used.


Pre-defined Data Types
----------------------

      Type        sizeof      Bits            Range
      ----        ------      ----            -----
  unsigned char      1          8             0 to 255
  char               1          8          -128 to 127
  enum               2         16        -32768 to 32767
  unsigned short     2         16             0 to 65535
  short              2         16        -32768 to 32767
  unsigned int       2         16             0 to 65535
  int                2         16        -32768 to 32767
  unsigned long      4         32             0 to 4294967295
  long               4         32   -2147483648 to 2147483647
  <pointer>          4         32
  float              4         32   (+-)3.4E-38 to (+-)3.4E+38
  double            10         80 (+-)3.3E-4932 to (+-)1.2E+4932
  long double       10         80 (+-)3.3E-4932 to (+-)1.2E+4932
  Zeiger             4         32             0 to 4294967295

  The format for floating point numbers is IEEE-standard.


The Help Compiler
-----------------

  Pure C includes a help compiler program (HC.TTP) which can be used to create
  your own help files.

  HC accepts the name of a file as its only parameter. This file must be in the
  following format:

    <options>
    <HLP_file_name>
    <source_file1>
    <source_file2>
    ...

  The options available are:

    L   Produce a log file
    N   Parse source file, but do not generate help file
    T=n Expand tabs to "n" characters, where 0 < n <= 9. The default is 4.
    V   Verbose message output
    W   Break on warnings

  Here is a sample command file:

    -LVT=8        ; log file on, verbose output, tab size=8
    USR.HLP       ; Help file name
    USR.TXT       ; Source file

  The source files for the help compiler contain blocks of separated text. The
  basic format is:

    screen( "<first screen name>" )
    Help text here
    more help text
    \end
    screen( "<second screen name>" )
    Help text
    \end

  The screen names are the index entries which trigger the help text which
  follows.  More than one screen name can also be specified for the same text:

    screen( "Cat", "Dog", "Fish" )
    Household pets
    \end

  Context-sensitive help (which can be accessed with the Help key) can also be
  generated by using the directives "sensitive" and "capsensitive":

    screen( "Index entry #1", sensitive( "keyword" ) )
    This text will display for "Keyword", "KEYWORD", or even "kEYwoRd"
    \end
    screen( "Index entry #2", capsensitive( "Key" ) )
    This text will only display for the word "Key"
    \end

  Help screens can also be linked by using the sequence \#. The following two
  help messages are linked together:

    screen( "First" )
    This is some text.
    \end
    screen( "Second" )
    Double-click on the underlined part to go to the \#First\# text.
    \end

  The use of \# depends on the contents of the text between the markers.
  Another directive, \link, can also be used so that the name of the actual
  help screen need not appear:

    screen( "Second" )
    \link( "First" ) Double-click here\# to go to the first screen.
    \end

  Both the PC_HELP desk accessory and the on-line help in the Pure C
  environment look for a file called USR.HLP. This file can contain your own
  help messages which will be scanned whenever the help system is accessed by
  either of these two methods.


The Pure Debugger
-----------------

  The majority of the options in the Pure Debugger should be self-evident.
  However, a few things should be pointed out.

  First of all, probably the most useful thing of all is the double-click.  It
  can be used to change breakpoints, file contents, variables, memory, and just
  about everything else. When the Inspect option is displaying the value of an
  array or structure, you can even double-click on a portion of the variable to
  get another window with a full display of its value. Try this with a nested
  structure to see for yourself.

  Setting a simple breakpoint can be accomplished by clicking once with the
  mouse within the narrow column on the left side of a source file or assembly
  listing window. Double-clicking will bring up a dialog with more detailed
  options. Remember that you can use any combination of these options; you can
  even have a global breakpoint (which will break anywhere in the program) by
  turning off the "Breakpoint at:" option. The program will execute much more
  slowly, but this can be very useful nonetheless.

  When a program is running, you can get back to the debugger at any time by
  pressing Alt-Help.

  The main difference between a Watched value and an Inspection is that when a
  pointer is being examined, a Watch tends to change more often. This is
  because an Inspection deals with indirected values, whereas a Watch deals
  with the actual value before indirection, and the actual value is more likely
  to change than the place it points to.

  The following reserved names for CPU registers (as well as a program's
  variable names) can be used as part of an expression for most addresses, even
  things like the address at which to Dump memory:

    Pseudo Variable    Data Type
         D0-D7       unsigned long
         A0-A7          char *
         PC             char *
         FP0-FP7      long double
         USP            char *
         SSP            char *

  Remember that if you want the Pure Debugger to use the source code in its
  displays, you must not only compile C modules with the -Y option, but you
  must also link using the -G, -L, and -Y options.

  One hint: if your program intercepts system vectors, you should always try
  to make sure that you allow it to finish before quitting the debugger.
  Otherwise, very nasty things can happen.


Pure Assembler
--------------

  The format used by Pure C's assembler is essentially the same which is used
  by other assemblers, such as Atari's MADMAC. The following directives are
  implemented. Each can be preceded with a period ("."), though this is not
  required. Directives which take a "size" can have one of the following
  values:
    symbol    type               length (bytes)
      .b      byte                     1
      .w      word                     2
      .l      long                     4
      .s      single precision real    4
      .x      extended precision real 10
      .p      packed BCD              12

  Constants can begin with various prefixes:
      $       hexadecimal
      0x      hexadecimal
      0X      hexadecimal
      %       binary
      @       octal
      <none>  decimal

  A constant can also contain underscores (_) to separate its digits for
  clarity. For instance, one million could be written 1_000_000. Floating point
  numbers can be written in the same formats that a C compiler understands.

  String constants an begin with ' or ". A string constant must end with the
  same character it begins with. A constant can even be used in normal
  instructions:
        move.b  #'A', d0        ; set d0.b to 65

  Directives:  
    expression = value  Assign a value. For instance:  ROM_base = $fc0000
    *= expression       Set position forward. For instance, to leave a gap of
                        256 bytes:  *= $100
    ALIGN [expression]  Fills with null bytes until the next address divisible
                        by "expression" is encountered. The default value for
                        "expression" is 2 (word alignment).
    ALINE #expression   Generates a Line A instruction. Ex:
                        ALINE $10    ; generates opcode $A010
    ASCII string[,string...]
                        A string of characters, without a NUL at the end. Ex:
                        hello: ASCII "Hello there!", "How are you?"
    ASCIIL string[,string...]
                        A string of characters, preceded by a length byte. Ex.:
                        these two are equivalent:
                                ASCIIL "Hello World!"
                                ; and
                                DC.B    12
                                ASCII "Hello World!"
    ASCIIZ string[,string...]
                        A string of characters followed by a NUL byte. Ex.:
                        these two are equivalent:
                                ASCIIZ "Hello World!"
                                ; and
                                ASCII "Hello World!"
                                DC.B 0
    BSS [expression]    Enter the BSS segment. All subsequent instructions
    BSS "name"          will become part of this segment, until a DATA or TEXT
                        directive is encountered. "expression" can be the
                        number of a segment, from 0 to 3. A "name" for a
                        segment can also be given. When the linker links the
                        segments, it always goes in order from 0 to 3.
    COMM label,expression
                        Defines a block of "expression" NUL-filled bytes in
                        the BSS segment.
    DATA [expression]   Enter the DATA segment. All subsequent instructions
    DATA "name"         will become part of this segment, until a BSS or TEXT
                        directive is encountered. "expression" can be the
                        number of a segment, from 0 to 3. A "name" for a
                        segment can also be given. When the linker links the
                        segments, it always goes in order from 0 to 3.
    DC[.size] expression[,expression...]
                        Defines a constant in the current segment. Each
                        "expression" in the list is "size" bytes long.
    DCB[.size] count[,expression...]
                        Defines "count" repetitions of the remaining
                        expressions. Ex.:
                        dcb.l  2,-2    ; result: $FFFFFFFEFFFFFFFE
                        dcb.w  2,3,4   ; $0003000400030004
                        dcb.b  3,"ABC" ; $414243414243414243
    DS[.size] expression
                        Reserves "expression" NULL bytes. Used primarily in
                        the BSS segment.
    ELSE                See IF.
    END                 End assembly. Text following END is not evaluated.
    ENDC                See IF.
    ENDIF               Same as ENDC. See IF.
    ENDM                End macro definition. See REPT and MACRO.
    ENDMOD              Ends a module. See MODULE.
    EQU label, expression
    label EQU expression
                        This performs the same function as using = or SET.
    ERROR "message"     Terminate the assembler with an error message.
    EVEN                Perform word-alignment by inserting a NUL byte, if
                        necessary.
    EXITM               Exits a macro without processing it any further.
    EXPORT label[,label...]
                        Defines a label as being global. This is necessary for
                        the linker to resolve external references to a label.
    FLINE #expression   Generates a Line F instruction. Ex:
                        FLINE $10    ; generates opcode $F010
    GLOBL label[,label...]
                        Defines one or more labels as being imported into the
                        assembly module, or as being exported out of it.
    IFcc expression     Conditional assembly. The condition code, "cc" can be
      <statements>      one of the following:
    [ELSE                 IF exp        exp != 0
      <statements>]       IFF exp       exp == 0
    ENDIF                 IFB arg       macro arg is not supplied
                          IFNB arg      macro arg is supplied
                          IF1           first assembler pass
                          IF2           second pass
                          IFEQ exp      exp == 0
                          IFNE exp      exp != 0
                          IFLE exp      exp <= 0
                          IFLT exp      exp < 0
                          IFGE exp      exp >= 0
                          IFGT exp      exp > 0
    IMPORT label[,label...]
                        Defines a label as being contained in another module.
                        This is necessary for the linker to resolve external
                        references to a label.
    INCLUDE "filename"  Includes (assembles) a secondary file.
    INCLUDE 'filename'
    LCOMM label,expression
                        Reserves "expression" bytes in the BSS segment with the
                        "label".
    LIST                All text following a LIST directive appears in the
                        listing file generated during assembly. Use NOLIST to
                        disable the list.
    LOCAL label[,label...] 
                        Defines a local label within a macro in the form
                        ____XXXX, where "XXXX" is from 0000 to 9999. For
                        example:

                          macro absolute
                              local   end
                              tst.w   d0
                              bge     end
                              neg.w   d0
                            end:
                          endm
                          absolute        ; uses label ____0000
                          absolute        ; uses label ____0001

    MACRO name[.size] [[param1],param2...]
      <statements>
    ENDM
                        Define a macro with name "name". For example:

                          macro Push.size parm
                            move.size   parm,-(sp)
                          endm
                          Push.l   d0     ; generates move.l d0,-(sp)
                          Push     d0     ; generates move   d0,-(sp)
                        
                        To substitute a parameter within a macro in a place
                        which is not preceded with a separator, the & can be
                        used:
                        
                          macro PushData RegNumber
                            move.l      D&RegNumber, -(sp)  ; move.l Dx, -(sp)
                          endm
                          
    MC68000             Selects the specific type of code to be generated by
    MC68010             the assembler.
    MC68020
    MC68030
    MC68040
    MC68851
    MC68851 -
    MC68881 [expression]
    MC68881 -
    
    MODULE label        Defines a module with name "label". A module serves as
                        a convenient way of preventing the linker from treating
                        different occurences of the same label within one
                        source file as the same occurence. This is similar to
                        the behavior which occurs when multiple assembly source
                        files are used.  Note that for library creation, all
                        the individual routines should either be declared as
                        independent MODULEs, or they should be in separate
                        source files. A MODULE should end with ENDMOD.
    NOLIST              Turn off the listing feature. See LIST.
    OFFSET [expression] Generate constants which define the number of bytes
                        from the start of the OFFSET block. An OFFSET block is
                        terminated by changing segments with TEXT, DATA, or BSS
                        directives:

                          ; Generate offsets for the elements of the C
                          ; structure:
                          ;   struct list
                          ;   {
                          ;     struct list *next;
                          ;     char        name[20];
                          ;   }
                          OFFSET
                            next: ds.l  1       ; next gets 0
                            name: ds.b  20      ; name gets 4
                            EVEN
                          TEXT
                          move.l        next(a0), a0
                          lea           name(a0), a1

    ORG expression      Advance position by "expression" bytes. Same as *=.
    PAGE [expression]   Set the page length for listings to "expression". If no
                        value is given, a form feed is generated.
    PRINT ["message"]   Prints a message within a listing. If no message is
                        given, a newline is generated.
    REG label,registerlist
    label REG registerlist
                        Defines a register list for the MOVEM instruction. Ex.:

                          SavedRegs REG A2-A4/D3
                          movem.l  #SavedRegs, -(sp)
                          ...
                          movem.l  (sp)+, #SavedRegs

    REPT expression     Repeat statements "expression" times.
      <statements>
    ENDM
    
    SET label, expression
    label SET expression
                        Same as = and EQU.
    TEXT [expression]   Enter the TEXT segment. All subsequent instructions
    TEXT "name"         will become part of this segment, until a DATA or BSS
                        directive is encountered. "expression" can be the
                        number of a segment, from 0 to 3. A "name" for a
                        segment can also be given. When the linker links the
                        segments, it always goes in order from 0 to 3.
    SUPER               Select the supervisor instruction set.
    TTL "title"         Define the title for a listing file. The name of the
                        source file can be included in "title" by using %f.
                        Ex.:  TTL "Listing for source file %f."
    USER                Select the user instruction set.
    XDEF label[,label...]
                        Exports labels for use in external modules. See EXPORT.
    XREF label[,label...]
                        Imports labels from external modules. See IMPORT.

  The Pure Assembler will normally try to optimize certain instructions. For a
  list of which instructions are optimized, see pages 189-190 of the Pure
  Assembler manual.


Assembly Language Considerations: Parameter Passing
---------------------------------------------------

  The Pure C compiler passes function parameters in CPU registers to improve
  performance. The data registers D0, D1, and D2 are for passing char's, int's,
  and long's. The address registers A0 and A1 are for passing pointers. Any
  parameters which cannot fit into the correct set of registers are passed on
  the stack. This includes data types such as "double" and all structures.

  To determine which parameter is passed in which register, the function should
  be evaluated from left to right. For instance, say we have the following
  function prototype:

    int foo( char d1, char *p1, struct xx *p2, long *p3, int d2, GRECT g1,
             long d3 )

  and this function was being called as follows:

    foo(     'A',     string,   xxptr,         longptr,  val,    grect,
             43L )

  In this case, the compiler might generate code which looks something like
  this:

    moveq.l   #43, D2         ; parameter d3 into D2 register
    lea       grect+8(pc), a0 ; get address of end of grect structure
    move.l    -(a0), -(a7)    ; push last two elements
    move.l    -(a0), -(a7)    ; push first two elements
    move      val, D1         ; parameter d2 into D1 register
    move.l    longptr, -(a7)  ; goes on stack because A0 and A1 to be used
    move.l    xxptr, A1       ; parameter p2 into A1 register
    move.l    string, A0      ; parameter p1 into A0 register
    move      #'A', D0        ; parameter d1 into D0 register
    jsr       foo             ; call foo

  This type of parameter passing can be defeated in two ways: either with the
  -H compiler switch, or by declaring the function to be of type "cdecl". For
  example, to pass all parameters to the function above on the stack, you could
  use:

    int cdecl foo( ...

  Certain system vector routines (like the critical error handler) can be
  directly replaced by a Pure C function if the "cdecl" type is used in the
  function's declaration.

  Another implicit case when all parameters are passed on the stack is when
  the ANSI C ellipses operator ("...") is used. One example of this is the
  printf function:

    int printf( const char *format, ... )

  The compiler uses D0-D2/A0-A2 for parameter passing and for temporary
  storage. This not only means that any assembly module MUST save any other
  registers it uses, it also means that any routine which calls a routine
  compiled by Pure C will most likely have these registers destroyed.  For this
  reason, special care must be taken when writing interrupt handlers using Pure
  C.


Assembly Language Considerations: Return Values
-----------------------------------------------

  Return values of type char, int, and long are always returned in the D0 CPU
  register. Pointers are always returned in the A0 register. More complex data
  types, such as "double" actually return their values using a pointer to a
  variable of that type which is passed on the stack. For instance, the
  following function:

    double donothing(void)
    {
      return 1.0;
    }

  when called might generate something like this:

    lea       10(a7), a0  ; a pre-defined storage space on the stack
    move.l    a0, -(a7)   ; push it
    jsr       donothing

  The function "donothing" simply takes this pointer and modifies it:

    donothing:    move.l  4(a7), a0           ; get pointer to return
                  move.l  #..., (a0)+         ; set the value...
                  move.l  #..., (a0)+
                  move    #..., (a0)
                  rts
