+------------------------------------------+
             | How to use Jazz with Jim Donnelly's Book |
             +------------------------------------------+
                          by Joseph K. Horn


Jim Donnelly has published an excellent book entitled "An Introduction
to HP 48 System RPL and Assembly Language Programming".  It comes with
HP's PC-based tools on disk and assumes that the reader will be using
those tools for software development.  But for small to medium-sized
programs, such as the examples in Donnelly's book, Jazz is much easier
to use than HP's tools.  In fact, Jim even recommends Jazz in a few
places in the book.  But he does not explain how to use Jazz with his
source code examples.  Here are the differences that you must keep in
mind for successful assembly of his examples.

(1) Don't use the GUI.H on Donnelly's disk; use the one on this
    Goodies Disk instead.  Download it into your HP48's working
    directory.  All of Donnelly's examples that include the "INCLUDE
    GUI.H" directive will now work correctly.

    --> GUI.H is used in INF2, INF3, INF4, and ORBIT.

(2) All of the ".s" RPL source files on Donnelly's disk begin with:

        ASSEMBLE
                NIBASC /HPHP48-A/
        RPL

    to create the proper header.  Jazz does not use a header, so you
    must delete the above lines either before or after downloading the
    source code to your HP48.  If there are any other lines between
    the ASSEMBLE and RPL, then only delete the NIBASC line.

(3) All of Donnelly's ".a" assembly source code files begin right off
    with the source code, but Jazz assumes RPL mode unless the
    ASSEMBLE directive is used.  So you must insert "ASSEMBLE" as a
    new line at the beginning of all ".a" files.  As discussed above,
    if there is a NIBASC line to create a header, it must be deleted.

(4) WHILE/REPEAT require a single object between them.  HP's tools
    automatically insert :: and ; around WHILE/REPEAT clauses; for
    example, page 65 in Donnelly's book shows

        WHILE
          TYPEREAL? IT %1+     <--- three objects
        REPEAT

    which gets compiled by HP's tools as

        WHILE
          :: TYPEREAL? IT %1+ ;   <--- one object
        REPEAT

    Jazz does *NOT* automatically insert :: and ; between WHILE and
    REPEAT, so you *MUST* insert them manually IF you have more than
    one object between WHILE and REPEAT.  Failure to insert them will
    cause Jazz to compile it the way it's written, without the :: and
    ; resulting in a program that does not run correctly.

    --> The example source code files which use WHILE/REPEAT and which
    must be modified are ADDIT, KB, KCODE, RSTR, and SCRIBE.  Although
    NUMRAN uses WHILE/REPEAT, it only has one object between them, so
    no modification is necessary.

(5) As insinuated in the "EXTERNAL Declarations in Examples" paragraph
    on page 148, Jazz does NOT use the EXTERNAL directive in source
    code for non-library objects.  So all EXTERNAL declarations in
    Donnelly's source code examples must be changed to DEFINEs.  For
    example, see page 150; the source code begins:

        EXTERNAL DoMsgBox
        EXTERNAL MsgBoxMenu

    These must be changed to:

        DEFINE DoMsgBox ROMPTR B1 0
        DEFINE MsgBoxMenu ROMPTR B1 2

    The ROMPTR values can be obtained from the hex number as listed in
    Donnelly's book or in the ENTRIES.A table on his disk.  For
    example, look at the GrobAlertIcon in the middle of page 149.  It
    shows a hex number (top middle of the box) of #850B0h.  This
    indicates that it's ROMPTR B0 85.  Notice how the last two digits
    of #850B0h are the library number, and the first two are the
    number of the command within that library.  So you have to switch
    them around when you change EXTERNAL to DEFINE.

    In general, change every

        EXTERNAL FooBar (where FooBar is listed as #NN0MMh)

    to

        DEFINE FooBar ROMPTR MM NN

    You may wish to place the most common DEFINEs in an INCLUDE file
    (similar to GUI.H) so that you won't have to retype them every
    time.

    When source code includes both an EQU and an EXTERNAL to create a
    ROMPTR, be sure to replace both with a single DEFINE.  And example
    of this can be seen in INF3, which contains these lines:

        ~DoKeyOK EQU #5A0B0   ( and then, a little further down: )
        EXTERNAL DoKeyOK

    Both of these must be replaced with the single line

        DEFINE DoKeyOK ROMPTR B0 5A

    --> The example source code files which use EXTERNAL and must be
    modified are: BRW1, CHS1, CHS2, CHS3, CHS4, CHS5, CHS6, INF3,
    INF4, MBOX, and ORBIT.

(6) The "(DO)" pseudo-op which is required by HP's tools is not
    required by Jazz, and may be removed.  It won't hurt to leave it
    in, however, because it will be ignored as a comment.  Note well:
    HP's tools check for proper pairing of structure words such as
    DO/LOOP.  Jazz does not.  Jazz happily compiles nonsense like

        :: LOOP DO DO ;

    so be careful to pair up the control words correctly.

    --> Donnelly uses "(DO)" in MAGIC, ORBIT, and PLIST.

I *hope* that the above is accurate and complete.  Please post any
addenda or corrigenda.

-Joseph K. Horn-    EQU  jaykaye@kbbs.com