About the ShrinkIt archive MERLINDOCS.BXY 
Status: 
Public Domain

This is a ShrinkIt P8 5.25˛ disk archive containing several Merlin
16 related files from Glen Bredonšs ŒOriginalš disk collection. It
has two files that are Merlin.s files containing early version docs
for the P16 versions 3.xx of Merlin:

MERLIN.16.DOC.S
DOC.PART.2.S

I have converted both of the above files into standard ASCII text
files in 80 Col. file format for ease of reading and viewing online.
Those two files are combined and included in full content below.


--------------------------------------------------------------------------------
*                Merlin-16 documentation (Sept. 1, 1987)

    This briefly documents changes between the current Merlin-pro (2.55)
    and Merlin-16.  The version number, now 3.00, will now start changing
    with any future revisions, unless I forget.  Merlin-16 must run on a
    //c or //e equipped with a 65802 chip or a 65816 board, or on a IIgs.

    A * in the left margin marks some changes from earlier version of
    this document.


1.  The SW opcode and sweet 16 assembly are gone.  (If you need them,
    macros for these are available that require only very minor changes
    to source code.)

2.  All address calculations are done in 32 bits truncated to 24 bits
    or 16 or 8 bits as appropriate.  (Some people think that truncation
    should not be done for things like LDX LABEL when LABEL is a 16-bit
    address, and think that the assembler should assume that such a
    case should be interpreted as if the assembler is in 16-bit index
    mode.  However, this syntax has always been accepted by Merlin as
    loading the X-register with the low byte of the value of LABEL.
    I do not think it wise to change this sort of convention.  Thus you
    must pay attention to the register length status; which you would
    have to do anyway.)

3.  Long addressing:  All 65816 opcodes are implemented.  The 16 long
    addressing opcodes xF have the syntax LDAL longadrs and LDAL longadrs,X
    etc.  The assembler DOES NOT convert an ordinary opcode such as
    LDA address into the long addressing mode when the address resolves
    to more than $FFFF.  I think this would be inappropriate because
    I think most usage will be in short addressing with the data bank     
    register set to the desired bank.  This is more efficient in time and 
    space, and I think it would be the most common form of usage.  Thus a
    LDA address will truncate the address to 16 bits.

    Thus the 16 long addressing XF opcodes are taken to be ADCL, ANDL,
    CMPL, EORL, LDAL, ORAL, SBCL, and STAL.

    The long jump, both absolute and indirect, is JML and the long call
    is JSL.  JMP and JSR always assemble to the short forms.  (With
    relocatable code, it is impossible for the assembler to determine
    if the short form is appropriate or not, so you must make that
    determination yourself.)

4.  The MVN and MVP opcodes now use the syntax

       MVN  SOURCE,DEST

    This DIFFERS from the syntax in Merlin-pro.  The assembler calculates
    the bank address of SOURCE and DEST and puts them into object code
    in the opposite order (differing from the order in Merlin-pro).
    This seems to be the syntax of preferance at this time.  Thus, if
    SOURCE = $012345 and DEST = $054321 then MVN SOURCE,DEST assembles
    as  54 05 01.

    Those few who have used Merlin-pro to assemble 65816 code with long
    addressing (via macros) must pay attention to this change in syntax.


5.  There is a new option for the CYC psuedo-opcode.  This is CYC FLAGS.
    (The assember only looks at the "A" so CYC FLAG or CYC FLA would do
    as well.)  This will cause a cycle count to be printed at each
    instruction, but instead of an accumulated total, it will also print
    the value of the "MX flag" as the assembler knows it.  For example,
    the line

001000: A9 00 00     324  EXAMPLE  LDA #0           ;Comment            3 ,01

    indicates that this instruction takes 3 clock cycles and the assembler
    thinks that you are in 16 bit accumulator (the "0") and 8 bit index
    register (the "1") mode.  This is mainly a debugging tool to show
    where the assembler may be wrong about the correct processor mode.
    (If it is wrong then you may have to use a MX opcode to correct it.)

    Since there was a change in the way the assembler handles the
    "MX flag" at version 2.00 the documentation of that is faulty.
    This is the way it works:

    An MX opcode sets the MX flag.
    An XCE opcode always clears the MX flag (makes it 11).
    A  REP or SEP opcode adjusts the flag to what the code is doing.

    Simply put, the assembler tries to follow the program logic and
    adjust the MX flag accordingly.  XCE resets the flag because it
    is true that moving into or out of emulation ALWAYS leaves the
    processor in 8 bit mode,  (Using XCE when in native mode, but still
    staying in native mode does not change the register lengths, but
    this would be an uncommon operation.)  The following sequence, with
    the MX flags shown is an example of this:

                     1             CYC   FLAGS      ;Show modes
                     2
                     3             XC               ;Enable 65816
                     4             XC               ; opcodes.
                     5
008000: 18           6             CLC              ;Prepare to go      2 ,11
008001: FB           7             XCE              ; to native mode    2 ,11
008002: C2 20        8             REP   %00100000  ;Set long A         3 ,01
008004: A9 34 12     9             LDA   #$1234                         3 ,01
008007: E2 20        10            SEP   %00100000  ;Short A now        3 ,11
008009: 8D 00 10     11            STA   $1000      ;Store low byte     4 ,11
00800C: EB           12            XBA              ;Interchange bytes  3 ,11
00800D: 8D 00 20     13            STA   $2000      ;Store high byte    4 ,11
008010: C2 10        14            REP   %00010000  ;Set long X,Y       3 ,10
008012: A2 00 10     15            LDX   #$1000                         3 ,10
008015: B5 00        16            LDA   0,X        ;Get byte at $1000  4 ,10
008017: 38           17            SEC              ;Prepare to         2 ,10
008018: FB           18            XCE              ; return to emul.   2 ,11
008019: A2 00        19            LDX   #0                             2 ,11
00801A: 60           20            RTS                                  6 ,11


    Note how the MX flags adjust themselves and we never had to use an
    MX opcode at all.  If you look closely you will also see that the
    cycle times also adjust themselves to the state (as understood by
    the assembler) of the processor.  If cycle timing is important, you
    MUST keep the assembler informed of the correct register length.

6.  In long mode a literal is accepted as a two byte constant.  That is,
    the following code is acceptable when the A-register is long:

              LDA  #"AB"

    and assembles object code  A9 C1 C2.  If the A-register is short
    (as far as the assembler knows), then this would give an error.
    The old  LDA  #"A"  is also accepted, but when the A-register is
    long this would set the last byte of the instruction to zero.
    Without the ending quote,  LDA  #"A  would set the last byte of
    the instruction to a space character, here $A0 since the quote
    delimiter indicates high bits on.

7.  The SWAP command in the editor is gone.  It conflicted with the
    full screen editor.

8.  Some changes have been made to better support the full screen
    editor.  The editor is now permanent and is not invoked via the
    "startup".  (XREFA is the default STARTUP file.)  (See, however, 
    item 36 in this list.)  The I command now creates an empty line
    before entering the full screen editor.  The E command sends you
    to the full screen editor even when there is no source in memory.

9.  The space on page 8 is now entirely used by the assembler.
    Thus PRINTFILER has been revised in this light and the XREF and
    XREFA programs have also had to have minor revisions for this.

10. Branch opcodes now show the branching address after the object
    bytes for convenience in following code.

11. In Merlin-pro the BRL (branch long) opcode never gave an error
    because the generated object code was always valid on the 65802.
    In Merlin-16 however, a test for valid range is done.  (This is
    only possible because of the extended value calculations.)

12. Despite more work in calculating 32 bit addresses, Merlin-16 is
    significantly faster than Merlin-pro (which was much faster than
    Merlin).  This is partly due to use of 65802 code, but is mostly
    due to improvement of the time intensive algorithms.  Direct to
    disk assembly is several times faster than before.



13. The linker uses the same space as USER programs.  It is memory
    resident as before after it has been loaded into memory.  To
    support this, the symbol table has been moved up to $1800 in aux
    memory.  Merlin-pro LNK files should be upward compatible as long
    as they do not have externals or entry declarations.  It is wise,
    however, to reassemble them in case I have forgotten some
    difference.  The LINK command from the editor has slightly
    different syntax in that you do not specify an address.

    Linker command files (nee NAME files) have much more flexibility,
    They support comments, are able to do batch assemblies before
    linking and are able to create multiple output files.

    To use the linker, first you must BRUN LINKER from exec mode.
    (If you use a program selector like PROSEL, you can specify the
    linker as the "startup" and it will be automatically loaded.)
    To invoke it, you must delete the source file in memory (save it
    first) and then type LINK'command file name' from the editor.

    The command file is just a text file looking much like a standard
    Merlin source file, but you DO NOT ASSEMBLE it.  It can have
    comments in the usual comment format for source files.  Commands
    to the linker are put in the opcode field.  Commands now
    supported are:

    ASM, PUT, OVR, LNK (or LINK), ORG, ADR, SAV, TYP, EXT, ENT, DAT,
    LKV, END, and LIB.

    These have the following syntax and meanings:

    ASM pathname

       Assemble the source file specified in pathname.  (The source
       should do a DSK or SAV or this is pointless.)  All ASMs should
       be done before ANY other linker commands.  The ASM command
       checks bit 0 of the "auxtype" of the source file, and does not
       do the assembly if this is set.  Otherwise it sets that bit
       and does the assembly.  You can defeat this by zeroing the
       appropriate bit in the parms (read the parms source).
       This bit is cleared whenever you save a source file, so this
       will force assembly of that file.  (Also see the PUT command
       below.)

    PUT pathname

       Check (and set) auxtype bit 0 of this file (presumably a PUT
       file in the next source).  If the file has been modified then
       force the assembly of the next ASM instruction.


    OVR

       Override the auxtype 0-bit check and force assembly of the next
       ASM instruction.  This flag is reset by any ASM.  With the
       syntax  OVR ALL  it will force assembly of all files in the
       linker list, so that you don't have to use OVR before each
       ASM instruction if you want all assemblies to be done.

    LNK pathname

       Link the LNK file specified.  Generally you will have several
       of these in a row.

    ORG hex address

       Sets the run time address of the following LNKs.  Must be
       used between each SAV and the next group of LNKs.  (Address
       will also be put in the auxtype if no ADR command follows.)

    ADR address

       Sets the load address of the next linked file.  Must be
       used only after an ORG setting the run time address.
       The ORG automatically sets this address, so you don't have
       to have an ADR command if it is the same as the ORG.
       (The "load address" is the address put in the auxtype of
       the file.  For non-BIN files it could have some other
       meaning.)

    SAV pathname

       Saves the linked file.  This MUST be in the command file or
       there will be no resulting linked file.  It should come
       after all the LNKs for a given output file.  The linker
       now supports 64 separate output files.

    TYP byte

       Sets the file type for the next linked file.  If all the SAVs
       are to use the same type output file, this need only be used
       once in the command file.

    EXT

       Tells the linker to print addresses of all resolved externals
       and not only the ones with errors.  This is turned off after
       each SAV.

    ENT

       Tells the linker to print the entry list.  This should come
       after all the linking of all output files.


    DAT

       Causes the linker to print the current date and time.

    END

       Marks end of linker command file.  Optional.

    LIB directory name

       If used, this should ordinarily come after all LNKs and
       before the last SAV.  It tells the linker to look for any
       unresolved (at that point) external labels and search the
       given directory for corresponding files (the files must
       be LNK files of the SAME NAME as the entry label they
       correspond to).  Any such files found will be linked to
       the present module.  Not finding a file will not cause
       an error because some other file linked this way may
       contain the entry in question.  If not, an error will
       result when the final external resolution is done.
       This feature could have been made automatic, but was not
       because that would substantially impair performance when
       it is not needed.  Also, making it an option in the
       command file provides more versatility.

       For example, suppose one of the linked files has the
       label PRINT declared as an external, and suppose the
       linker comes to the line LIB LIBRARY, and that, at that
       point, none of the linked files has an entry called PRINT.
       Then the linker will look in the directory LIBRARY for a
       file called PRINT, and, if that file is found, it will be
       linked to the present module.  Then the linker will search
       for further unresolved externals (including those from the
       file PRINT just linked) and act on them in a similar way.

    LKV byte

       Checks that the version of the linker in use is correct.
       See item 54.

    For multiple output files, start each group of LNKs with an
    ORG and end it with a SAV.  External references will be
    resolved between such groups by a second linker pass.


14. The GS linker (LINKER.GS) works in the same way as the absolute
    linker except that it creates LOAD files for the IIgs only.
    The ORG is accepted but should ordinarily not be used.

    Only one output file is supported, and there is a maximum
    length of the final file in the neighborhood of 32K for the
    code portion and another 32K for the relocation dictionary.
    Another version, LINKER.XL, does not have these restrictions.


    In addition to the linker commands of the standard linker, the
    GS linker has the following commands:

    VER  (version)

       This is used to specify the version of the Object Module
       Format you want the linker to use.  At this time versions
       1 and 2 are supported.  Thus the operand must be $1 or $2.
       The VER instruction should come before any other linking
       instructions except ASMs which don't matter.

    KND  address

       This specifies the value (1 byte for VER $1, 2 bytes for VER $2)
       that you want put in the KIND location of the OMF header.  This
       must come after the VER so that the format is known to the linker.
       If in doubt, just ignore this command and accept the default.

    ALI address

       This specifies the ALIGN field in the file header.  It defaults
       to 0.  Use only $10000 to align to a bank boundary or $100 to
       align to a page boundary.  In most cases you should just leave
       this alone to the default 0.  (Our tests indicate that the bank
       align does not work on OMF version 1.)

    DS  address

       This tells the linker to reserve this number of bytes (which will
       be zeroed by the loader) at the END of the program.  (This number
       is put in the RESSPC field of the header.)  Using this instead
       of reserving space with a DS in the source file will result in
       smaller object files.

    NOTE:  The linkers have only primitive address calculation ability.
    All addresses must be in hex and preceded with the "$" sign.


15. The EXT and ENT opcodes now accept the syntax:

           ENT  PLACE1,PLACE2,PLACE3

    (With this syntax you MUST NOT label this line.  That will cause
    the assembler to assume you are using the old syntax.)

    This makes it possible to declare absolute symbols as entries.
    For example, if PLACE1 was an equate instead of a location in
    the code then it can still be used as an external by other
    modules.  Thus it does not have to be equated in all the files
    using it.  (Remember, however, that using this, instead of just
    putting equates in the source files, will tend to enlarge the
    linker library and result in possible memory overflow.)


16. The ADR psuedo-opcode has been established for placing three
    byte long addresses (low byte first) into object code.  The
    syntax is:

            ADR  address1,address2,address3

    In addition, ADRD or ADRL does the same for a four byte address.
    (For writing GS programs, you will usually use the ADRL form.)

17. Interrupts and break processing.  The 65816 BRK and IRQ processing
    is very different from that on the 6502 and the Apple ROMs do not
    support it on the //e or //c.  Thus you MUST NOT try to use
    interrupt driven routines while Merlin-16 is running.  There is
    no valid BRK vector in memory when the processor is in native
    mode.  Thus, if you want to set a break point in a routine you
    are testing, you MUST return to emulation before the BRK with a
    SEC, XCE, BRK sequence instead of just the BRK.

18. The BRK opcode now accepts an operand.  If there is an operand
    then it assembles as a two byte opcode.  If not then it assembles,
    as it used to, as just the one byte 00.  This is to allow people
    who think it should be two bytes to use it that way, but maintain
    compatability with old sources that use it to just put a zero
    into object code.

19. The number of parameters in a macro call is now passed to ]0.

20. File names (EXEC load etc) that end with "/" will not have the
    ".S" appended.  This allows loading text files without this
    extension into the editor without having to rename them.

21. Merlin-pro restricted the acceptable OBJ file types.  There is
    no longer any restriction; you are responsible for assuring the
    type you use is appropriate.

22. The TR opcode has a new option  TR ADR  which causes the first
    two digits in the address portion of the listing to be suppressed.

23. The value associated with equates is now shown.

24. TTL pseudo-op added.  This has the same syntax as ASC and resets
    the page title for the editor PRTR command.  Usually you will
    want to follow this with a PAG pseudo-op.

25. Maximum length of labels and opcodes has been increased to 15.

26. New editor command "UNNEW" which retrieves a text file lost by
    a NEW command.

27. Full screen editor commands changed:  OA-X is now cut, OA-C is
    copy, and OA-E is exchange.  (These can be changed by the user
    in the PARMS file.)


28. Caution:  When the assembler sees an opcode like FindControl
    (one of the GS macro names) it looks first to see if there is
    a macro defined of that name.  If it is not found (eg. if that
    set of macros has not been specified by a USE and is not a
    macro defined in the main source) then the first three characters
    (Fin) are taken as the opcode.  If (as in this case) this is
    regular opcode or pseudo-op (FIN) then it is treated as such,
    and no error is generated.  This can be a source of confusion.
    Happily there are few such examples.

29. The date is printed in the PRTR header of each page.  This can
    be defeated by clearing the appropriate bit in the PARMS file.

30. Sourceror changes:  This version of sourceror is set up like
    the linkers.  It can be a "STARTUP" (from a program selector)
    or can be run by a BRUN SOURCEROR/OBJ from Merlin.  It is no
    longer a USER routine but, instead can be called from the
    command mode editor by the DISasm command.  You must give the
    name of the object file to be disassembled in the command,
    for example DIS "MYFILE" or DIS $1000"MYFILE".  If an address
    is given (non-zero) then that address is taken as the initial
    running address to use.  (SYS files are exceptions to this
    and always are assumed to have running address $2000.)
    If the address is not specified then it is taken to be the
    auxtype of the file.  Other changes:

    (a) The reversed word (DDB) is no longer supported, the WW
        command is used, instead, to generate a 4-byte long
        address (psuedo-op ADRL).

    (b) The sweet-16 commands S and N are gone and sweet-16
        disassembly is not supported.

    (c) The disassembly is full 65816.  It attempts to follow
        the flow of the program in assigning the length of
        immediate operands (ie. this is changed by REP, SEP and
        XCE) in the same way as the assembler does.  This cannot
        always be successful, and so Sourceror allows you to
        reset this mode by using an address with the L command.
        When the L command is accompanied with an address the
        M and X status bits are taken from the byte following
        the L, default is MX = 00.  For example, 1012L01<RTN>
        restarts disassembly at address 1012 with long M and
        short X (MX = 01).

    (d) Sourceror can be used (in fact, expects to be used) in
        80-column mode, unlike earlier versions.

    (e) The "menu" of commands (and the I command) is gone due
        to lack of sufficient room.


    (f) For large object files, there is the alternative version
        SOURCEROR/XL.  This creates output files instead of
        putting the created source in Merlin's source file
        memory.  The output files are put in the current prefix
        directory active at the time the DIS command is issued.

    (h) Command "O" added.  This allows changing the ORG on the
        fly during disassembly.  It is very useful for programs
        that move code to other places after loading.  The syntax
        of this command is "adrs O newadrs"; for example, the
        instruction  1045 O 300<RTN> tells Sourceror to backup
        to address 1045 and place there an ORG $300.  [NOTE: You
        should NOT type the spaces in this command; they are
        added here only for clarity of reading.]

31.  Added commands in full screen editor:

        OA-A  assembles current source file.
        OA-M  goes directly to the EXEC menu.
        OA-H  toggles split screen (10 lines at bottom frozen,
              13 lines at top scroll).  This does not work on
              the Ultraterm.

32.  PARMS now includes the full screen editor command keys,
     which can be changed to suit one's whims.  Note that the
     cursor keys are there, but MUST NOT be changed.

     PARMS also has a default PRTR init string, used if the
     init string in the PRTR command is empty and the slot
     specified is not 3.

33.  F command added to EXEC menu - goes directly to full
     screen editor.

34.  Loading a file now goes directly to the full screen editor
     instead of to the command line editor.  However, if the
     open apple key is held down during the load, it will go
     to the command line editor.

35.  Upon exit from Merlin, the current source file is moved to aux
     memory.  Upon reentry it is moved back provided a number of
     integrity checks prove out.  If the source buffer is empty then
     the clipboard, if any, may still be intact after reentry.

36.  The horizontal stability of the cursor in the full screen editor
     has been improved.  Also there is an alternative editor (TXTED in
     the UTIL directory) which will break a line upon a carriage return,
     and can delete carriage returns.   I believe, however, that the
     action of the present editor with respect to these things is more
     convenient when working on source files.  TXTED can be substituted
     by the command "BRUN UTIL/TXTED" from EXEC mode, or it can be
     loaded upon boot as a "startup" by putting its name in the startup
     position or by declaring it as the startup from PROSEL or other
     program selector.

37.  In the full screen editors the right arrow key will now select
     the next page (to line 11 on the next screen) when in select mode,
     making selection of a large chunk of the source file easier.
     NOTE: Do not hold down the right arrow key when doing this, or the
     keyboard buffer will pile up right arrow keys and it will continue
     selection when you release the key.

38.  There is a new bit in PARMS (read PARMS.S), now the default,
     which causes return to EXEC upon a key press following assembly,
     or, if there was an assembly abort (because of a fatal error or
     a ^C abort command), it returns to the full screen editor at the
     point of the abort.  If REL is active then it returns to the full
     screen editor at the end of the source file, or for any
     circumstance that disables the object save.  If this option is
     disabled, or if the open apple key is held down when hitting
     the key, the assembler returns to the command mode editor as before.
     (I did not make it return to the full screen editor in all cases
     because that would defeat the possibility of saving the object
     code from EXEC mode.)

39.  New assembler error message: "Misalignment".  This means that
     the value of a label on the second pass differs from what it was
     on the first pass and should indicate a forward reference
     (usually to a zero page equate or dummy section) that the
     assembler could not deal with.  (However, misalignment may be
     caused by a previous error.)  Some "forward reference errors"
     have been removed deference to this new error check, allowing
     use of some forward references that the assembler did not allow
     in the past.  A misalignment error is given only once in order
     to avoid the error routine on all subsequent labels, all of
     which are likely to be misaligned.

40.  The ESC key, as well as ^C, aborts assembly now.

41.  Input routines in EXEC mode and the command line editor
     have been changed as respects the DEL and TAB keys.
     DEL does what it should.  TAB moves the cursor to the
     end of the line, or to just past the next "/" character.

42.  If the available object file space has been exceeded the
     assembler now prints a "Object space overflow" message.
     (Previously no message was given and the only indicator
     was that the object save was disabled.)  However, this is
     not counted as an assembly error.

43.  The address range of the symbol table is now printed
     (in hex) at the end of an assembly.  This allows you to
     see when you may need to use an OBJ or to switch to
     direct assembly to disk (DSK opcode).

44.  The USR opcode has been extended to allow up to 10 USR
     opcodes USR0 through USR9.  The old version USR is
     equivalent to USR0 and is upward compatible.  The number
     0-9 is doubled and placed in the X register and then
     a JSR $B6DA is done (same address as before).  You can
     place, at B6DA, a JMP (VECTORTBL,X) where VECTORABL is
     a list of addresses of your routines placed at any
     free spot such as page 3.  To use routines that would
     not fit on page 3 you could set the source address at
     $A,B higher (you may have to copy this to $E00A,B), 
     or you could set HIMEM lower.  (To do the latter, set
     both $C,D and $73,74 to the lower address.)

     USR routines are entered in native 8-bit mode and can
     be exited in any mode.  The documented routines that
     can be called must be entered in native 8-bit mode.

     An example source file with 3 USR routines is provided
     in the file SOURCE/USR.EXAMPLE.S.

45.  In the full screen editors the closed apple key now
     functions as a key speedup.

46.  The parms file now has an option to enable 65816 (or
     65C02) assembly as the default.  See the parms file
     source.  With this option you do not need the two
     XC psuedo-opcodes to enable 65816 assembly, but they
     are accepted if there.

     Also, to further support this, the assembler's XC
     pseudo opcode now has an XC OFF option which makes
     the assembler revert to vanilla 6502 mode, in case
     one wants to write code that must run on all Apples.
     After an XC OFF, further XC codes have the old effect
     of enabling 65C02, and then 65816, code.  (Note that
     having the correct XC option established is needed for
     the cycle timing {with CYC} to give correct results.
     Merlin's cycle timing is even more correct than that
     given in the chip manufacturer's data sheets.)

47.  In LINKER.GS (but not in the others because it is not useful
     in them) the command LINK'=', or simply LINK without a
     file name, from the command line editor will assemble the
     file given by the default file name (the name appearing when
     you give the load or save commands from EXEC), then will link
     the resulting file (it is assumed that a LNK file was produced
     by the DSK and REL opcodes), and will then save the linked file
     using the name of the LNK file with the last two characters
     cut off.  (It is suggested that you use a ".L" extension on
     the DSK filename; eg, MYFILE.L, so that the saved file will
     be MYFILE.)  Note that this command does not require a linker
     command file, and that it uses the defaults in the linker,
     producing an S16 filetype in object module format version 2
     (currently), and of "kind" $1000 (code segment that cannot be
     loaded to special memory).  This syntax should not be used if
     there are more than the single object file to link.

     The command LINK1 will do the same but produces a file in
     object module format 1 of "kind" 0 and type S16.


     If there is a source file in memory when this command is
     issued then that file will automatically be saved under the
     default file name (caution, this can be dangerous).  If not
     then the file given by the default file name will be loaded
     and assembled and then linked.

     If the LNK file produced by the assembly has a name ending in
     ".x" where x is a digit (0 to 9) then the linker will, instead,
     look for the file with the same name but ending in  ".0"  and
     will link that file together with subsequently numbered LNK
     object files until it finds no more.  In this way, up to 10
     files can be linked without using a linker command file.

48.  There is now a "LINKER.XL" which is a version of LINKER.GS
     which makes two passes and links to disk to produce a
     multisegment file.  Use of the SAV command will cause the
     linker to process the code to that point as one segment of
     a load file.  This can produce much larger object files
     than the other linker.  However it is also much slower,
     so the other version is being kept available.  This version
     does not have the LINK'=' capability discussed in item 48.
     The maximum number of segments in the output file is
     currently 25, each with up to about 32k of code (excluding
     relocation dictionary).  For LINKER.XL, the filename in the
     FIRST SAV command is taken as the output file name.  The rest,
     including the first, are placed in the "segment name" field of
     their respective segment header.  If the name is more than the
     allowed 10 character space in the header then it is truncated
     to 10 characters.  This linker and LINKER.GS use page 3 of main
     memory and page 8 of aux memory, areas not normally used by Merlin.
     Linker.gs also uses page 3 of aux memory.  LINKER.XL does not
     presently support the EXT or ENT commands (almost useless on
     OMF files, and I needed space to support LIB) and LINKER.GS does
     not support ENT (see item 65).

49.  Use of the "backup bit" in the linkers has been changed to
     use bit 0 ot the "auxtype" of the source file.  Note that this
     required a change to the assembler and will not work correctly
     with older versions of MERLIN.SYSTEM, because resaving a file
     from older versions will not clear that bit.  There is no
     problem with using source files created by an earlier version,
     but revisions should be done using MERLIN.16 if you expect this
     feature of the linkers to work correctly.

     (See new description of ASM and PUT in item 13.)

50.  Printfiler was modified to work with the command line editor's
     Print and List commands.  (This required changes to the editor
     and it will not work correctly with old versions of Merlin.System.)


51.  New full screen editor commands:

     OA-1 does a "PRTR1" and "ASM"
     OA-2 does a "PRTR1" and "USER" and "ASM"
     OA-3 does a "PRTR3" and "ASM"
     OA-4 does a "PRTR3" and "USER" and "ASM"
     OA-6 does a "LINK"  (useful only with Linker.gs).

     (Cases 2 and 4 are primarily intended for use with XREF and XREFA.)
     The default printer init string, if any, will be used with OA-1
     and there will be no page break title unless the source file sets
     one with the TTL psuedo-opcode.

     The PARMS file has changed (again) to reflect these new commands.

52.  The psuedo-ops TR and EXP are now included in printed listings.

53.  If TRON is invoked in the command line editor before going into
     the screen editor then text in comments will be ignored by the
     Find and Exchange commands.

54.  The linkers now have the opcode command LKV (linker version)
     which will cause an abort if the linker in use does not
     correspond to the value of the operand.  Currently the
     standard P8 linker "LINKER" is version 0, "LINKER.GS" is
     version 1, and "LINKER.XL" is version 2.  Thus, for example,
     if you want to guarantee that LINKER.XL is the linker in use,
     put the line

                     LKV  $02

     in the linker command file.

55.  TABS were changed to be the distance from left boundary.
     (This required changes in many files - don't use old
     versions of anything.)

56.  The MX default is now in the parms file.

57.  The default STARTUP is now in the parms file.

58.  There is a new bit in PARMS which tells the assembler to
     continue without the siren on an error.

59.  The old editor is now gone (as far as the user is concerned).
     For old Merlin addicts, it can be re-enabled via a bit in the
     parms file.  However, many commands have been removed since their
     function is duplicated in the full screen editor.  Gone are:
     Insert, Replace, Copy, Move, Length, Change, and Find.  Commands
     which remain are now accessible through the OA-' (open apple,
     single quote) command in the screen editor which brings up a box
     from which you can issue the old editor commands, such as PRTR, NEW,
     TABS, DIS, LINK, USER, MON, to name a few.  Unless the parms bit
     enabling the old editor is set, the E command is absent from the menu,
     but it is still accepted and sends one to the full screen editor.

60.  In the Exchange command in the full screen editor, if you
     hold down the open apple key when pressing the RETURN which
     terminates the input of the replacement string then then
     Exchange will operate on ALL strings found and not just
     on "words".  (This makes up for deletion of that function
     from the old editor.)

61.  No longer goes into 40 col mode upon a PRTR1 unless the
     machine has an Ultraterm and is in a mode with more than
     24 rows.

62.  An addon to the full screen editor called AUTO.EDIT (and
     another version of the same) is now available in the
     UTIL directory with source in the SOURCE directory.
     This works in a similar manner to EDMAC.  It is invoked
     (after a BRUN or placement as the STARTUP) by the OA-\
     command from the full screen editor.  The source indicates
     how similar addons can be implemented.

63.  New option for LST pseudo-op:  LST RTN will return the LST
     status to what it was previous to the last instance of LST.
     For example, one could put LST OFF and LST RTN surrounding
     a macro library and then the library would not be listed
     but listing will resume after it IF it was enabled at the
     start of the macro library.

64.  Suppport has been added for such syntax as LDA >LABEL
*    (to force long addressing), LDA |LABEL (to force absolute
     addressing) and JSL [adrs] (alias JSL (adrs)).  The older
     syntax is still supported (and is superior in my opinion).
     PEA #^adrs  is now accepted (as well as PEA ^#adrs etc,
     both of which are of use in macros).

65.  The command LIB has been added to the linkers.  See items
     13 and 48.  Commands ENT and EXT had to be removed from
     LINKER.XL in order to support this.  The are of little use
     for OMF output.  Command EXT has been removed from LINKER.GS
     for similar reasons.  All the linkers recognize these commands
     but "removed" means they do nothing.

66.  Things you may or may not want to document:  At relative
     byte $47 of the file MERLIN.SYSTEM, following a long
     string of zeros is the byte $08.  If changed to $00 then
     the pause on bootup will be defeated.  The next two bytes
     are both $FF.  If these are both changed to $00 then the
     checksum testing at bootup will be defeated (useful if
     patches have to be made to the file - but in any case the
     checksum test will allow you to continue if it does not
     come out correctly - a friendly checksum, no less!).

                   <<< continued next file >>>

*                 Merlin-16 documentation (part 2)

67.  LINKER.GS and XL now produce more compact dictionaries in
     OMF vers. 2 mode.  In the XL version this necessitated using
     aux memory pages 2 and 3 - thus that version permanently
     disconnects the standard RAM volume (until a reboot).  I don't
     think this is much of a problem on the GS.

68.  The EXEC mode BRUN (or -) command will now execute an S16
     file provided the boot was into P16.  If the boot was into
     P8 then trying this will just quit from Merlin - no questions
     asked.

69.  New command in command line editor:  FIXSpc.
     This is the same as FIX except that it removes multiple
     spaces except in comments and ascii strings.  Note: the
     decision of what is an ascii string is based on them being
     delimited by single or double quotes, so this may not always
     work as desired.  The operation of this command, as well as
     the old FIX, is now reasonably fast - on the order of 3
     seconds for a large file.

70.  The maximum number of segments that LINKER.XL can produce
     (number of SAVs) has been increased to 25.

71.  There is now a byte in the parms which will enable recognition
     of RETURN as the same as "Y" when the question mark appears
     after a file name in EXEC mode.  As now, and previously, set
     RTN cancels the command.

72.  The menu box now accomodates long prefixes.

73.  New options for the IF psuedo-op:  "IF MX..."  results in the
     MX (at the beginning of the operand only) being interpreted
     as if it were a label containing the value of the current
     MX flag (0-3) and then the following arithmetic, if any, is
     done.  If the result is zero then a DO 0 condition results,
     else a DO 1 condition results.  This is intended for use in
     macros to test the register length.  For example,

            IF  MX/2   is "IF M is short"
            IF  MX&1   is "IF X is short"
            IF  MX     is "IF either M or X is short"
            IF  MX!3/3 is "IF both M and X are long"

74.  Cycle times, when enabled, now print on all lines except comment
     lines and empty lines.  This is mostly to support unexpanded macros.
     Note that times shown on macro calls are the times at the beginning
     of the macro and not the end as with regular opcodes.  This is
     because the macro has yet to be processed (the same reason that it
     is not possible to show object bytes for unexpanded macros, at
     least not easily).  The accumulated time is now also kept across
     macros.

75.  Added command line editor command: SYM, which prints the symbol
     table from last assembly.  (Care should be taken that this not be
     used if a valid symbol table does not exist.)  Note: If the printing
     is aborted and then the command reissued, only a partial listing
     will result.  This is because of symbol flagging that is done during
     the sorting.  If the printing is allowed to continue to the end,
     the next usage of the command will print the entire table.

76.  Bugs fixed in version 3.30:  (1) Incorrect numeric sorting of symbol
     table.  (2) Open-apple-3 (etc) sometimes did a page eject and page
     two header before assembly began (I neglected to set a flag).
     (3) Linkers probably bombed on a memory full error.  (I have no files
     large enough to show that, but there was a clear mistake in one of
     the memory error routines.)  (4) In both Sourcerors: disassembly of
     MVN and MVP corrected (they disassembled into Merlin-pro syntax,
     which differs).

77.  Version 3.30 has had some massive changes, moving portions of code
     to make more efficient use of memory for possible future use.
     I think I made all necessary adjustments, but it is possible I
     messed something up - virtually all files had some changes.
     All linkers and both Sourcerors now use page 8 in aux memory,
     as well as all aux memory above page 8.  (As noted before,
     Linker.xl also uses pages 2 & 3 of aux memory, and permanently
     disconnects standard /RAM.)  [I really should convert the assembler
     source to use the linker, but that would entail even more massive
     changes - sometime perhaps.]

78.  Doc suggestion:  One correspondent was clearly confused about
     use of SAV in a linker command file.  SAV must ONLY be used after
     one or more LNKs.  It is not to be used to save the object code
     after an ASM - the assembly source should have the SAV or DSK
     command to do this (DSK if linking is to be done, and the linker
     is not just being used to do batch assemblies).  All ASMs must
     precede any LNKs and SAVs.

     If SAVs are done without LNKs the resulting files may be incorrect
     and an error will result on the third one or so.

79.  Maximum symbol length has been increased to 26 characters.  Some
     tool macro files have been revised to change the long names I had
     to truncate, back to Apple's labels.  I may have missed some.
     Actually this change was to accomodate an improved algorithm that
     could shorten assembly time.  It does so slightly on the moderately
     long files tested, but it is an improvement proportional to the cube
     of the file length, so very long assemblies may gain substantial
     benefit from the change.

80.  A new bit in the parms has been added, which enables listing of
     local labels in the symbol printout.  This is useful in eliminating
     unused labels when the symbol table gets too large.  Also the
     actual memory addresses of the various parms are shown when
     assembling the parms file.  These addresses can be used if it is
     desired to make a temporary change in one of the parms directly
     from the monitor.  (Some of these addresses may change, but most
     are relatively stable.)


                      ---- Version 3.31 -----

81.  New option for the command line editor SYM command (see #75):
     the command SYM: inverts the "print locals flag" and then prints
     the symbol table.  Thus it is not necessary to change the parms
     bit controlling this to see the local label list.  Also, both
     SYM and SYM: accept a string, and then print only those labels
     starting with that string.  For example, SYM'TR' will show all
     labels, and only those, starting with 'TR'.  Note that the
     symbol printout must be allowed to go to completion or the next
     use of the SYM or SYM: command will not print all symbols.
     (If aborted during alpha printout, the SYM command will restart
     where it left off.)  Also note that if the symbol table was not
     previously listed then the SYM: command will not show the local
     labels in the alphabetical listing on its first use.  This is
     due to the flagging used in sorting the list.

82.  Delete is now gone from the command line editor.

83.  As the result of testing cycle times by a program I wrote for
     that purpose, about 2 dozen cycle times (out of 1024) have
     been corrected.  The former times were based on the original
     65816 data sheet, which was wrong.  The same errors are in
     the Eyes-Lichty book, but a close look at the current data
     sheet confirms the corrected times.  (Most of the corrections
     are in the long X mode of the processor, and the old times
     could be regarded as correct if the added cycle flag were
     reinterpreted, but the assembler knows there is an extra cycle
     and it should not be left to the user to do this adjustment.)
     [Incidently, the cycle time tester took about 2 days of running
     to cover all cases - mostly because my current clock driver
     only gives times to a one second accuracy.]

     Note: To have the correct branch times listed, one must have
     the XC flag set to indicate the right processor (XC OFF for
     emulation mode, or just one XC for 6502 or 65C02 times) as
     well as having the MX flag indicate the correct microprocessor
     status.  For the 65802/16 in native mode, there are no added
     cycles for page crossing, and the cycle time listing indicates
     this if the assembler is set to full 65816 assembly by the
     two XC codes.

84.  Object space overflow is now a regular error "Obj overflow"
     and is counted in the total errors.  This change was made in
     order to release space needed to correct the cycle time
     algorithm.

85.  Bug fix in the Sourcerors:  the JSR $BF00 translation did not
     "relabel" the parameter table address - now it does.



86.  Assembler bug fixes:  (1) Sometimes a "bad variable" error was
     not reported in a macro call failing to give a required variable.
     (Usually some other error resulted.)  (2) Macros containing
     instructions that changed register length (SEP, REP, MX)
     sometimes did not work correctly.  (3) Put files that are
     too long for memory sometimes crashed assembler.

87.  Alternate mnemonics now supported (in addition to BLT & BGE):

      TAS = TCS,  TSA = TSC,  TAD = TCD,  TDA = TDC,  SWA = XBA.

                      ---- Version 3.32 -----

88.  The assembler DSK output now supports sparse files.  That is,
     if there is a large DS to reserve space the result will be a
     sparse file instead of a file with a lot of zeros.  This is
     a minor feature, but one for which I had a use.  (Note: only
     DSK does this, not SAV.)

89.  Changes to screen editors: (1) ^X now cancels find mode (in
     addition to old ways),  (2) Select mode is no longer cancelled
     at top of page.  [Don't know now if these can be fitted into
     Merlin-8 versions - space is tight there.]

90.  Bug fixed in the GS linkers: Under unusual circumstances an
     incorrect relocation record was written.

                      ---- Version 3.33 -----

91.  Bug in LINKER.GS introduced in 3.32 fixed.  Main menu box
     fixed: did not like a null prefix.

92.  CDAs reassembled.  The linker bug (#91) may have had an effect
     on the ones I sent with 3.32.

93.  Bug in screen editors' exchange function fixed.  Under rare
     conditions it used to mess up ends of some lines.
-------------------------------------------------------------------------------

-END OF FILE-