                        JAZZ V6.5

        System RPL and Machine Language Development Library

        (c) 1995 by Mika Heiskanen & Jan Brittenson


CONTENTS
========

        1. Introduction
                1.1 Copyrights & Ackowledgements
                1.2 The Jazz Library
                1.3 Installing & Deleting the Library
                1.4 Uncovered Jazz mode
                1.5 Entry Tables
                1.6 Universal Font Library

        2  The System RPL/Machine Language Assembler
                2.1 Errors
                2.2 System RPL Assembly
                        2.2.1 Lambda Variable Generation
                2.3 Machine Language Assembly
                        2.3.1 Macros
                        2.3.2 Conditional Assembly
                        2.3.3 Expressions
                        2.3.4 Label Generation
                        2.3.5 Debugging
                2.4 Library Assembly
                2.5 Differences to HP Tools

        3  The System RPL/Machine Language Disassembler
        4  The System RPL Debugger
        5  The Machine Language Debugger
        6  The System RPL Stack
        7  The Entries Catalog
        8  The System RPL/Machine Language Editor
                8.1 The Viewer
        9  Entries Table Utilities


1. Introduction
===============

1.1 Copyrights & Acknowledgements
---------------------------------

All files of the Jazz library are copyrighted (c) by Mika Heiskanen
unless otherwise noted.

The Jazz library is distributed in the public domain in the hope that it will
be useful, but is provided 'as is' and is subject to change without notice.
No warranty of any kind is made with regard to the software or documentation.
The author shall not be liable for for any error for incidental or
consequential damages in connection with the software and the documentation.
So there.

Permission to copy the whole, unmodified Jazz package is granted provided
that the copies are not made or distributed for resale (excepting nominal
copying fees).

Extra credits & acknowledgements:

        Jan Brittenson          DB program is originally from Jan's
                                MLDL library and is still copyrighted by him.
                                The mnemonics have been changed to the ones
                                used by HP + some more or less significant
                                changes have been made.
        Jens Kerle              Bug fixing
        Dan Kirkland            Rewrite of ED/EC keywait subroutines
                                Sorting the default tables sensibly
        Will Laughlin           Backward search & EC key in ED
        Christophe Meynard      Alphabetic sort & search in EC
                                Fill key in ED
                                Register editing in DB
                                Screen reformatting in DB
        Mario Mikocevic         Basis for the machine language instruction
                                disassembler. GNU Tools.
        Detlef Mueller          Inspiration through RPL48 package.
        & Raymond Hellstern
        Rick Grevelle           Medium font
        Davor Jadricevic        Original small font.
        Al Arduengo             Improved small font.
        Cary McCallister        For answering.

Beta testing & suggestions:

        Seth Arnold             Bill Levenson
        Douglas Cannon          Tom van Migem
        Carlos Ferraro          Mario Mikocevic
        Rick Grevelle           Detlef Mueller
        Joe Horn                Richard Steventon
        Boris Ivanovich         Kurt Vercauteren
        Jens Kerle              Vladimir Vukicevic
        Dan Kirkland            Christ van Willegen
        Jeoff Krontz            Stefan Wolfrum
        Will Laughlin

        +countless others

1.2 The Jazz Library
--------------------

The Jazz library provides commands for assembling, disassembling and
debugging both system rpl and machine language. This document describes only
the provided commands, not the languages themselves. For information on the
languages please refer to the tools package published by HP, especially the
files RPLMAN.DOC, RPLCOMP.DOC and SASM.DOC. Familiarity in the fundamentals
is assumed from now on.

Following files available from hpcvbbs.external.hp.com are recommended:

        dist/ms-dos/tools.exe                           HP Tools
        dist/hp48g/programming/entries/ent_srt.zip      Sorted Entries
        dist/hp48s/programming/entries/entries.zip      Address sorted entries
        dist/unix/sadhp105.zip                          Unix Disassembler

GNU Tools are available from fly.cc.fer.hr:

        pub/hp48/gtools


1.3 Installing & Deleting the Library
---------------------------------------

To install the Jazz library you need atleast:

        - GX with sufficient RAM or existing RAM card in slot 1
        - S/G with sufficient expanded RAM
        - SX with existing RAM card in slot 1 or 2

The Jazz commands will not work from a covered port, thus GX banks 2-33
are not allowed storage locations for Jazz.

To install the library to port 0: (similar for port 1)
        a) Remove possible older version with :0:992 PURGE
        b) Download the library to your HP48
        c) Recall the library to the stack and purge the variable
           created by the download procedure.
        d) 0 STO
        e) Execute OFF-ON keys or do ON-C

1.4 Uncovered Jazz mode
-----------------------

Since version 4.9 Jazz includes the JAZZ command, whose purpose is to enable
using Jazz for those who only have a single >128K card, and thus have to keep
it in GX card slot 2.

JAZZ command expects to find Jazz in port 2, and if so it will change the
environment variables maintained by the HP48 so that it will think there is
only a single port which is visible. In other words, the HP48 will think port
2 is the only existing one and but will not realize that it is in fact
working like port 1 (uncovered).

For the JAZZ command to work the user should store both Jazz and the entry
tables described in the next section in port 2 of a multi-bank card, and then
execute JAZZ to start the uncovered mode.

In the uncovered mode:

        - All the higher ports are inaccessible
        - Port 2 behaves as if it was uncovered

Sadly the HP48 is good enough to notice the tampering at the OFF-ON port
checks, and will thus generate a warmstart. This means the user should be
careful not to let ED/EC/SSTK/SDB commands timeout while waiting for a key.

This JAZZ command is only the first attempt at solving the problem though,
the next future consideration is:

        UNJAZZ command which restores the environment back to normal

Until then the only way to exit the uncovered mode is ON-C, or OFF-ON as
described above. And if possible, I might make the process automatic by
including the JAZZ/UNJAZZ calls in all the commands available in Jazz
library. This could create some unforseeable problems, but I am hopeful this
will work out fine.


1.5 Entry Tables
----------------

Jazz enables using two different entries tables:

        RPL.TAB         - Entries sorted by their name
        DIS.TAB         - Accessory to RPL.TAB providing address sort

The purpose of the tables is the same as that of entries.o for HP and GNU
Tools, it provides names for programs and regular objects in ROM. Without the
tables you would have to use addresses for all ROM objects instead of names,
of use equates for the names in each source code. In any case, programming
without proper entry names is extremely tenuos, and thus although Jazz does
not need the tables to operate, using them is highly recommended.

The tables provided in this package were built from HP's latest supported
entries table, with some minor modifications which I thought necessary.
The tables are stored inside a library for easy storage and access, but the
library can be splitted into backup objects should someone want to keep only
the name table (RPL.TAB). Once again though, DIS.TAB provides an address sort
to the entries and thus provides a crucial speed increase in disassembling
commands, so keeping both the tables is recommended.

The tables can be stored in any port. However storing them to a covered port
would mean that whenever the tables are accessed, they must be copied into
user RAM. This means that effective available free memory is decreased, and
of course some speed loss due to the actual copying. However I personally
do keep the tables in a covered port, so it isn't that bad.

If someone has been using entry tables provided in Jazz packages before
version 4.2, it is recommended that the user takes the tables in this package
instead, as the tables have changed and the sorting has been improved. The
table was built from hpentr.a file, which is provided with the package.

gentab2.c is a modified version of Detlef Mueller's gentab.c. The modified
version will build library source code given an entries table as input.
gentab2 also takes preferred entries in disassembly into account by ordering
the names for a given address based on their order in the original input.
Syntax: gentab2 < SupRomEntr.a > table.a


1.6 Universal Font Library
--------------------------

Jazz requires the universal font library containing the small and medium
fonts to be installed in order to work properly. For convenience this is
provided in the package. To install it simply upload 'ufl3.lib' and proceed
with the usual library installation procedure. Note however that Jazz
requires UFL to be installed in the same port as Jazz itself - typically in
port 1 of course.





2  The System RPL/Machine Language Assembler
============================================

As opposed to the tools provided by HP Jazz provides only one command to
assemble source code. The assembler assumes the source code to be RPL unless
a switch is made via special tokens.

        Command:        ASS
        Stack:          ( $ --> ob )
        Description:    Assemble source string
        Keys:           ON key aborts assembly
        User flags:
                1 - Report mode on (slows down assembly considerebly!)
                7 - Disables entry tables

In principle the ASS command is equivalent to the following programs put
together
                RPLCOMP         - RPL precompiler
                MAKEROM         - Library builder
                SASM            - Saturn assembler

What the assembler does is in fact simply to change the internal mode
whenever some specific tokens are encountered. However there are some obvious
changes, typically some missing mnemonics, but there are also new ones to
ease programming.


2.1  Errors
-----------

As opposed to the PC assembler's, ASS will stop at the first error it
finds. To make the error message as informative as possible, the internal
error handling code is never executed, the behaviour is only emulated as far
as necessary. The resulting error display is shown in small font as follows:

                                Top of display
                        +----------------------------+
                        |ErrorMsg       line/position|
                        |Token/Source line           |

To avoid unexpected behaviour the emulated error code expects a standard
error trap (SysErrorTrap) to exist in the RPL stream, if this is not the case
then by default it must assume that the error trap may be crucial to the
program which called the assembler. Thus the regular error code is re-entered
to provide proper entry into the error trap. For those programs which find it
necessary to keep the full error messages from the assembler, an errortrap
starting with ":: NOP" also cause the full messages to be shown.  This should
be useful for example in the internal SOL replacements, and for example SSTK
uses the feature.

2.2  System RPL Assembly
------------------------

System RPL assembly is the default mode for ASS, and works more or less as
described in RPLMAN.DOC and RPLCOMP.DOC.

Comments in RPL mode are any lines starting with "*", and anything surrounded
by parenthesis. Note that RPLCOMP also requires there to be whitespace after
the leading "(" character.

The object generating tokens are as follows:

        ;                       --> end of composite object, eg SEMI
        {                       --> start of list, eg DOLIST
        }                       --> end of list, eg SEMI
        ::                      --> start of program, eg DOCOL
        SYMBOL                  --> start of symbolic, eg DOSYMB
        UNIT                    --> start of unit, eg DOEXT
        # hhhhh                 --> system binary
        #hhhhh                  --> system binary               [1]
        ddddd                   --> system binary               [1]
        PTR hhhhh               --> pointer
        ACPTR hhhhh hhhhh       --> access pointer, G/GX only
        ROMPTR hhh hhh          --> rom pointer object
        ddd.dd                  --> real number
        % ddd                   --> real number                 [2]
        %% ddd                  --> long real number            [2]
        C% ddd ddd              --> complex number              [2]
        C%% ddd ddd             --> long complex number         [2]
        HXS     <len> <hh.h>    --> hex number                  [3]
        GROB    <len> <hh.h>    --> grob                        [3]
        LIBDAT  <len> <hh.h>    --> library data                [3]
        BAK     <len> <hh.h>    --> backup object               [3]
        LIB     <len> <hh.h>    --> library object              [3]
        EXT1    <len> <hh.h>    --> external type 1, S/SX only  [3]
        EXT2    <len> <hh.h>    --> external type 2             [3]
        EXT3    <len> <hh.h>    --> external type 3             [3]
        EXT4    <len> <hh.h>    --> external type 4             [3]
        ARRY    <len> <hh.h>    --> array                       [3]
        LNKARRY <len> <hh.h>    --> linked array                [3]
        CODE    <len> <hh.h>    --> code object                 [3]
        NIBB    <len> <hh.h>    --> misc nibbles
        $ "<string>"            --> string                      [4]
        "<string>"              --> string                      [4]
        ID <string>             --> identifier object           [4]
        LAM <string>            --> lambda identifier object    [4]
        TAG <string> <..>       --> tagged object               [4]
        CHR <char>              --> character object            [4]

[1] Instead of outputting an object, the system binary is searched from
    stable ROM areas, and if found then the pointer to that object is
    output instead. (RPLCOMP does not do this)
[2] The value may also be -Inf, Inf or NaN, which mean infinite values
    or an undefined value. Note that these values are actually meaningful
    only in machine language, not in system RPL. (RPLCOMP does not do this)
[3] The length field may also be zero, in which case a null object is output.
[4] Special character substitutions are performed in the string parts.

Other supported tokens are:

        xROMWORD                --> pointer or ROMPTR depending on the
                                    library number the command belongs to
                                    ( For example "xDUP" compiles to a
                                    pointer but "xASS" to a rom pointer)
        INCLOB <name>           --> Include object stored to a variable
        INCLUDE <name>          --> Include source code
        DEFINE <token> <string> --> Define substitute for token
                                    Substitution will not be done inside
                                    multipart tokens, for example
                                    "ID <token>" is not allowed
        CODE <newline>          --> Starts machine language assembly
        ASSEMBLE                --> Starts machine language assembly

2.2.1 Lambda Variable Generation
--------------------------------

To ease the use of NULLLAM lambda variables Jazz implements localized lambda
bindings as follows:

        {{ label1 label2 .. labelN }}

compiles to

        ' NULLLAM <#N> NDUPN DOBIND     (or 1LAMBIND if there is only 1 label)

After the binding the labels can be used as follows

        label1  --> 1GETLAM
        =label1 --> 1PUTLAM
        !label1 --> 1PUTLAM
        label1! --> 1PUTLAM

The maximum number of variables in the declaration is 22. The equates are in
effect until the next lambda variable binding.

For example the following program assembles to

        ::                              ::
          {{ A B }}                       ' NULLLAM TWO NDUPN DOBIND
          B A!                  -->       2GETLAM 1PUTLAM
          ABND                            ABND
        ;                               ;


2.3  Machine Language Assembly
------------------------------

The assembler mode switches to machine language when an ASSEMBLE token
is encountered, or the special CODE-ENDCODE pair is found. In the first case
the RPL token switches back to system RPL mode.

The supported mnemonics are basically those described in SASM.DOC.

The behaviour of the following mnemonics has changed:

        TITLE   text            Text shown on line 1, line 2 cleared
        STITLE  text            Text shown on line 2
        MESSAGE text            Text shown on line 1, line 2 cleared

        D0=D0+  expr            \
        D0=D0-  expr             Allow values between 1 - 256, and
        D1=D1+  expr             generate multiple opcodes if needed.
        D1=D1-  expr            /

The following mnemonics are recognized, but are simply ignored:

        EJECT, REL, LIST, LISTM, LISTALL, UNLIST

The following mnemonics have not been implemented:

        EXITM

        ABS     expr            Not Implemented
        RDSYMB  file            ..
        CHARMAP file            ..
        Dn=HEX  hh.h            ..
        GOSHORT label           ..
        JUMP    label           ..
        INC(n)  label           ..
        LINK    label           ..
        SLINK   label           ..


        NIBBIN  bb..b           ..      (GNU Tools Opcodes)
        NIBGRB  bb..b           ..
        HEX(n)  hh.h            ..
        HEXM(n) hh.h            ..
        ASC(n)  \ASCII\         ..
        ASCM(n) \ASCII\         ..

The following new mnemonics have been implemented:

        LCSTR   \ASCII\         Reversed LCASC
        LASTR   \ASCII\         Reversed LAASC
        CSTRING \ASCII\         NIBASC with 0-byte terminator
        ABASE   expr            Sets allocation counter to address
                                specified by <expr>.
label   ALLOC   expr            Allocates <expr> nibbles for label at the
                                allocation counter, then increases allocation
                                counter by <expr>
        Dn=Dn+r                 f.ex D0=D0+A ==> CD0EX C=C+A CD0EX
        Dn=Dn-r                 f.ex D0=D0-C ==> AD0EX A=A-C AD0EX
        Dn=Dn+P                 f.ex D0=D0+P ==> CD0EX C+P+1 CD0EX
        Dn=Dn-P                 f.ex D0=D0-P ==> CD0EX C=-C C+P+1 C=-C CD0EX
        r=Dn                    f.ex A=D0    ==> AD0EX D0=A
                                f.ex B=D0    ==> CD0EX B=C CD0EX
        INCLOB <name>           Include object stored to a variable.

        Note that in Dn=Dn-P the carry is set unless the result is zero.

        INCLOB will behave differently from code than from rpl. Depending on
        the type of the object being included it is either included entirely
        or the leading nibbles (prolog + possible data fields) are skipped for
        following object types:

                Prolog  Skip    Prolog  Skip    Prolog  Skip
                ------  ----    ------  ----    ------  ----
                DOCODE  10      DOEXT0  10      DOGROB  20
                DOCSTR  10      DOEXT2  10      DOARRY  5
                DOHSTR  10      DOEXT3  10
                                DOEXT4  10


2.3.1  Macros
-------------

The assembler does not implement macros as described in SASM.DOC, in
particular no argument substitution exists for now.

The following is used to define macros:

<label> MACRO
        <line1>
        ..
        <lineN>
<label> ENDM

The last label is optional, and if it exists it is simply ignored.

For the case when the macro definition takes only one line, the following can
be used to compress the source code:

<label> MICRO   <definition>

As there are some obvious uses for micros in terms of register assignments,
the following can be used to assign a symbolic name to a scratch register:

<label> REG     <scratch register name>

For example the following line

X       REG     R2

would be equivalent to the following four micro definitions

A=X     MICRO   A=R2
C=X     MICRO   C=R2
X=A     MICRO   R2=A
X=C     MICRO   R2=C

Note that as the assembler does not use mnemonic tables for speed, it cannot
do full reserved word tests in assembly. Thus the user might mistakingly
declare a scratch register name to be P, which of course causes problems
if the user intends to use the "C=P <n>" opcode elsewhere in the source.
Caution is thus adviced in the use of symbolic names.


2.3.2  Conditional Assembly
---------------------------

Jazz does not follow the unnecessarily complicated conditional assembly
opcodes as HP Tools or GNU Tools. Instead Jazz enables comparison operators
in expressions and thus the conditional assembly opcode set is reduced to

        IF <expr>
        ELSE
        ENDIF

The opcodes are implemented label independantly, thus the label convention
used in RPLMAN.DOC should not be used either - it would result in duplicate
label errors. This means that all IF's must have a matching ENDIF - which
ASS of course checks. However due to the simple implementation method ELSE
racking is not possible and therefore if there are multiply nested IF's
an extra ELSE between them might be missed. This causes no ill-effect since
it can happen only when ELSE code shouldn't be assembled anyway.

The maximum nesting depth for IF-ELSE-ENDIF is 64. The matching tokens must
be located in the same source file.

The opcodes are currently implemented only in assembly mode, but the
implementation allows using them for RPL too as follows

  ASSEMBLE
        IF sBEGINNER
  RPL

     DROP SWAP DROP

  ASSEMBLE
        ELSE
  RPL

     DROPSWAPDROP

  ASSEMBLE
        ENDIF
  RPL

Proper tokens for doing the same directly from RPL mode are planned for
future Jazz versions via #IF, #ELSE and #ENDIF tokens.


2.3.3  Expressions
------------------

The expressions in assembly source are defined as described in SASM.DOC, with
the additional binary integers and local labels.

        Factors:
                #hh.h           hex integer
                %bb.b           binary integer
                dd.d            decimal integer
                =symbol         global symbol (RPL.TAB checked too)
                :symbol         local symbol
                symbol          local symbol
                *               PC counter
                + - ++ --       Local labels

        Operator:       Priority:
                ^       9
                *       8
                /       8
                %       8       (modulo)
                +       7
                -       7
                &       5       (and)
                !       4       (or)
                <=>     2       (comparison operators)

Note in particular that ascii factors are not implemented. As in sasm all
symbols must be surrounded with parentheses when operators are used.

The allowed comparison operators are < <= == >= > <> - none of which are
implemented either in HP Tools or GNU Tools. All comparisons are performed
using unsigned integer math.


2.3.4  Label Generation
-----------------------

Sometimes assigning names for insignificant branches can be tiresome, to ease
programming the assembler implements local label generation:


        +       refers to the next + label
        ++      refers to the next ++ label
        -       refers to the previous - label
        --      refers to the previous -- label

For example to search for a next newline character one might use:

        LCASC   '\n'
-       A=DAT0  B       <--+
        D0=D0+  2          |
        ?A#C    B          |
        GOYES   -       ---+

Note that overuse is not advisable, as it can make the source unreadable and
can easily cause errors if several label generators are used in a short
range.

2.3.5  Debugging
----------------

The assembler will recognize DEBUG as a special opcode and will output a
GOSBVL call into the proper entry point inside DB debugger. Note that
although the end result will be the same, the calling address is inside the
library as opposed to a RAM variable as in the entry point hooks explained in
the DB section. Naturally one may still use GOSBVL =DBGX (or =DBSX).


2.4  Library Assembly
---------------------

ASS can be used to assemble MAKEROM source code with the following tokens:

        xROMID #hhh             Defines hex library number.
        xROMID dec              Defines decimal library number
        xTITLE <title>          Defines title to be rest of the line.
                                If title is missing then nulltitle is used.
        xCONFIG <label>         Defines the location of the configuration
                                object via a label. If label is missing then
                                no config is taken to exist.
        xMESSAGE <label>        Defines the location of the message table
                                via a label. If label is missing then no
                                message table is taken to exist.
        EXTERNAL <label>        Defines label to be external. Order of
                                introduction determines the command number
                                of the commands in the library so that
                                visible commands will be first, then
                                nullnames.
        xNAME <label>           Specifies location of a visible command.
                                Name: "xlabel"  Hash: "label"
        sNAME <label> <hash>    Specifies location of a visible command.
                                Name: "label"   Hash: "hash"
        hNAME <label>           Specifies location of a 'visible' command.
                                Name: "label"   Hash: null
        NULLNAME <label>        Specifies location of a hidden command.
                                Name: "label"   Hash: none
        tNAME <label> <hash>    Specifies secondary hash for command.

xROMID and xTITLE must be used at the start of the source code, to be
specific before any actual code has been output. Also xROMID must come before
any other MAKEROM token.

xCONFIG and xMESSAGE declarations can be anywhere (or absent), but a suitable
location is after the xROMID and xTITLE declarations.

EXTERNAL declaration is needed if the corresponding command is used before
its location is specified by its NAME declaration. Suitable location is after
the header declarations, and it is probably best to declare all commands.

xNAME, sNAME, hNAME and NULLNAME specify command location, thus they should
be right in front of the object they define as a command. All but NULLNAME
also define the romid/cmd header field properly and thus require a propfield,
typically the value 8 to mark a regular command and 000 to mark a regular
function, for other values please refer to entries.srt or other documents.
Above also define a symbol '~label' having a 6 nibble value, low 3 nibbles
containing the romid and high 3 nibbles the command number.

The internal menu display routines stop showing library menus if a command
with no hash is found. Thus any command declared after a hNAME will not be
shown in the library menu, but will of course have typable/disassemblable
command names as usual if so specified by NAME tokens.

tNAME can be used anywhere after the declaration of the romp the secondary
hash is assigned to, a suitable location is right after the corresponding
NAME location declaration. Note that tNAME can be used to declare names for
NULLNAMEs, thus providing easy access to low level subroutines if needed. One
command can have several secondary names.

Note that INCLOB does not do any ID --> ROMP conversion work on the included
object like the common DIR --> LIB library builders do.

Example: Jazz MAKEROM source would start like this:

        xROMID  992
        xTITLE  Jazz v4.0 Fin'95 10.06.95 mheiskan@gamma.hut.fi
        xCONFIG JazzCfg
        xMESSAGE JazzMsg

        EXTERNAL xASS           ( User ASS command )
        EXTERNAL Assemble       ( Main assembler code object )
        [..]
        EXTERNAL UnShowSel!     ( Low level subroutines of SSTK )
        EXTERNAL >SelPict!

        LABEL JazzCfg           ( Configuration object )
        :: 992 TOSRRP ;

        LABEL JazzMsg           ( Message table )
        ARRY hhhhh hhh..h

        NIBB 1 8                ( Easier than ASSEMBLE CON(1) 8 RPL )
        xNAME ASS               ( Note: the EXTERNAL declarations )
        :: CK1 ... ;            ( declared fonts to come before ASS )
        [..]                    ( when assigning command numbers )


2.5  Differences to HP Tools
----------------------------

Besides the obvious missing or additional mnemonics, there are several
differences to HP Tools by design, of which the most important ones are
described next.


1. Since the assembly is performed on the calculator itself, there is no need
   to include the download header line (NIBASC 'HPHP48-X') in the source code.

2. Symbol/label handling allows more than SASM. For example the following would
   cause an error in HP Tools if used in an expression:

                (=GETPTR)-(=SAVPTR)

   The symbol handling does the absolutely necessary error checks though, for
   example each expression value is determined to be absolute or relative, and
   accordingly some opcodes would error. For example

                D0=D0+  label                   ==> Error
                D0=D0+  (label2)-(label2)       ==> Valid

3. The Saturn processor contains bugged opcodes, and accordingly SASM
   will error for example if A=A+CON fs,expr is used with a single nibble
   field selector. Jazz assembler will allow the opcodes to be used, as
   although they are bugged they do show predictable behaviour. For those
   interested, the bug appears as the addition/substraction operating in all
   the 64 bits of the register, starting from the nibble specified by the
   field selector. Also the carry is not properly set. Those who are not sure
   should try to DB on the following example:

        CODE
                A=0     W               Clear A[W]
                A=A+CON S,15            Works fine since there is no overflow
                A=A+CON S,2             See for yourself..
                LOOP
        ENDCODE

4.  As there is no specific linker in Jazz, it must expect some symbols to be
    resolvable when introduced. Such symbols are those defined by the equate
    mnemonics (=, EQU, ALLOC, ABASE).


5.  The EXTERNAL token is not implemented the same way as in RPLCOMP.
    In particular it cannot be used to declare "~symbol" to be external
    so that that "symbol" would compile to a ROMPTR. However using
    a DEFINE in this case would of course be much simpler.

6.  RPLCOMP automatically inserts "::" and ";" at proper places between
    a WHILE-REPEAT segment. This because WHILE expects only a single object
    before the REPEAT command. However HP Tools will also introduce the
    delimiters when not desired, for example for "WHILE DROP REPEAT" where
    there is only a single object between the tokens. This unnecessarily
    increases code size and slows down the code.


3 The System RPL/Machine Language Disassembler
==============================================

Several disassembler commands are provided for different purposes. The user
should note that having DIS.TAB in addition to RPL.TAB speeds up the
disassembler considerably (binary search vs linear search).


        Command:        DIS
        Stack:          ( ob --> $ )
        Description:    Disassemble object. If stk1 is a pointer to a ROM
                        address only the pointer will be disassembled.

        Command:        DISXY
        Stack:          ( hxs_address hxs_end_address --> $ )
        Description:    Disassemble memory area.
                        Guesses start mode, switches mode during
                        operation if necessary.

        Command:        DOB
        Stack:          ( ob | #address | hxs_address | "entry" --> $ )
        Description:    Disassemble memory area.
                        Guess start mode and end address.

        Command:        DISN
        Stack:          ( hxs_address %N --> $ )
                        Disassemble memory area as machine language only.

        User flags:
                2 - disable guess mode
                4 - disable machine language disassembly for DIS
                5 - disable tabulator, use spaces instead
                6 - force generated labels on their own rows
                7 - disables entry tables

In guess mode the disassembler will try to guess data structures embedded in
machine language. Currently only the following types are recognized:

                GOSUB   +
                REL(5)  +               Optional leading size indicator
                BSS     expr            Data is all zeros
        +       C=RSTK

                GOSUB   +
                REL(5)  +               Optional leading size indicator
                NIBASC  \ASCII\         \ Possibly alternating and spanning
                CSTRING \ASCII\         / multiple lines.
        +       C=RSTK

                GOSUB   +
                REL(5)  +               Optional leading size indicator
                NIBHEX  hh.h            Miscellanoues data
        +       C=RSTK


The sufficient condition for an ascii guess to be successful is that the data
area should consist mostly (75%) of common ascii characters.  The ascii lines
are splitted to CSTRINGs or by newline characters or so that the maximum
length will be 40 chars.

Should the beginning machine language programmer wonder why the guess mode is
necessary, one should suffice to say that as machine language is not a
structured high-level language, there is no telling when machine language
ends, or even when it starts. In particular, there's no telling when somebody
has embedded for example a data table inside machine code. The call to a
C=RSTK instruction is a common way to pass the address of such a table, but
there are other ways which the disassembler cannot reasonably be expected to
guess. Thus there are cases in which the disassembler is bound to fail.


For convenience all disassembler commands also check for variable 'Romps' in
home directory which can contain names for romptr objects. This feature
should be especially useful when debugging libraries. The variable should
contain a list of the form

        {
                ROMPTR hhh hhh  ID name1
                ROMPTR hhh hhh  ID name2
                ...
        }

Just to advertise an associated product, the Profiler library which performs
execution time and crash analysis on libraries provides a command which
creates the Romps variable given a text file containing the names of the
various romptrs.


Warnings:

- DOB, DISXY and DISN disassemble areas of memory instead of well defined
  objects. Using these commands to disassemble memory in the temporary object
  area is dangerous since a possible garbage collection during run-time can
  move the memory being disassembled.  Use only DIS to disassemble objects in
  tempob!!!
- Composite history is tracked up to 64 levels. If that is exceeded a ";" may
  be output when "}" is due.
- As opposed to the assembler the disassembler cannot handle hidden hash
  tables, thus some named ROMPTRs will be disassembled to "ROMPTR xxx yyy".
- Label values are guessed for Dn=(2) and Dn=(4) instructions if
          - Dn=(2) is likely to refer to the IO page
          - Dn=(4) is likely to refer to a RAM variable
  This works well for disassembling ROM but doesn't does badly when
  disassembling a program that uses even-page method in it's data
  allocation. Benefits are clearly greater though.


4  The System RPL Debugger
===========================

Command:        SDB
Stack:          ( seco | id | lam | romp --> ? )
Description:    Start debugging program indicated by stack level 1.

If the srpl debugger is already running then SDB command will only show the
SDB menu:

        ->SST           - Single step next command
                          If right-shifted then single-steps rest of
                          the stream as a single unit

        ->IN            - If possible then enter the program referred to
                          by the next command, else single step command.

        SNXT            - Show next commands on status area
                          Pressed for the second time shows return stack

        SST->           - Start continuous ->SST mode, subsequent presses
                          toggle slow/fast mode, eg whether stack display
                          is updated after each command or not.
                          Any other key aborts continuous evaluation

        IN->            - Start continuous ->IN mode.

        DB              - Start DB on next code object

        xKILL           - The HP48 KILL command
                          (xCONT can be evaluated through LS+ON keys)

        SKIP            - Skip next command. If right-shifted then skips
                          rest of current stream, eg executes a SEMI command.

        SEXEC           - Execute stk1 as the 'next' command.

        SBRK            - Set breakpoint object to STK1. If right-shifted
                          clears breakpoint object.

        LOOPS           - Browse loop environments. Up/Down to scroll, any
                          other key to exit.
                          If right-shifted dumps topmost environment to the
                          stack.

        LAMS            - Browse lam environments. Up/Down to scroll lams,
                          left/right to decrease/increase environment. Any
                          other key to exit.
                          If right-shifted dumps topmost environment to the
                          stack.

        IN?             - Toggle ->IN mode to never enter into secondaries,
                          only into IDs/LAMs/ROMPTRs when allowed. Prevents
                          the debugger from entering into ROM subroutines
                          during continuous debugging.


Note that SDB is meant for debugging system rpl, not user rpl. Thus some
user rpl commands will not be single stepped right when using SDB. One
example is xHALT, for which the substitute xSHALT is provided. Note that SDB
must be running before SHALT works.

Warnings:
        Debugging system-rpl is very hairy and undoubtedly
        SDB cannot debug some lesser known commands correctly.
        If such commands are found SDB can even cause a crash
        and memory loss. This is unfortunately unavoidable since
        there really is too much code in ROM to worry about.
        SDB should manage to debug all normal programs though.

        SDB either enters commands or executes commands (by emulation
        if necessary). None of the interactive commands in HP48 ROM
        are emulated, most importantly PolOuterLoop. To emulate
        POLOuterLoop you need to insert SHALT commands into the
        display objects or whatever you want to debug, then start
        SDB, then use CONT to reach the point of the SHALT command.



5  The Machine Language Debugger
================================

Command:        DB
Stack:          ( id --> )
                ( romp --> )
                ( $entry --> )
                ( #address --> )
                ( hxs_address --> )
                ( code --> )
Description:    Debug machine language


Special entry:
                SX: GOSBVL #70520       aka "DBSX"
                GX: GOSBVL #806A0       aka "DBGX"

The special entry hooks are initialized by DB whenever started. To ensure the
hooks are active before evaluating the hooked program, just to "0 DB" which
does all the initialization but returns immediately. User flag 1 disables the
entries so that they return immediately, thus enabling free run tests in
development phase. An easy way to ensure all is fine is to do "0 DB" which
initializes the hooks, sets the display size and aborts as real number input
is invalid.

The special entry cannot do all the initializations like the regular entry,
most importantly:
        - The tables cannot be searched normally
        - Display cannot be initialized normally

SSTK binds the tables into LAMs, this is easy enough to check in machine
language so to use the tables in special entry start SSTK before evaluating
the hooked program.

The text display grob is usually 7 lines high, while DB uses the expanded 8
line size. The expansion cannot be done in machine language without violating
the CPU register contents, so make sure your text display is in the expanded
size before evaluating the hooked program. The easiest way is to use "0
DB". If this is not done, PICT might be corrupted and memory could be lost.

The cycles used by DB are those measured experimentally with CTIM in HACK
library for G/GX calculators. The cycles have been scaled by 4 to avoid
units of 0.25 cycles.


        Screen Keys:

                [alpha] - Help screen
                [A]     - Screen 1 (general registers)
                [B]     - Screen 2 (general 64-bit registers)
                [C]     - Screen 3 (general instruction stream)
                [D]     - Screen 4 (stream disassembly)
                [E]     - Screen 5 (memory dump)
                [F]     - Screen 6 (machine language disassembly)
                [MTH]   - Screen 7 (general registers + breakpoints)
                [VAR]   - Screen 8 (watchpoints)
                [SPACE] - Update display
                [EEX]   - View PICT (if it exists) as long as EEX is down
                [CST]   - Shows argument in binary

        Screen 4 subpages:

                [D]     - If screen 4 is already active switches the active
                          page format
                [SQRT]  - Toggle screen 4 to show D0,D1 or both
                [SQRT]  - If ARG then setup new CON(m)/REL(n) table format
                          from the low nibbles of ARG
                [^]     - Toggle showing D0 or stack level N
                          Expects further keypress for the value N (0-8)

        Arguments:
                [0]     - Start inputting argument.
                          [0-9A-F]      add digit
                          [DEL]         abort input
                          [BS]          delete last digit
                          [+/-]         negate arg

        Movement keys:

                [NXT]   - Skip instruction      (or ARG instructions)
                [left]  - PC=PC-1               (or -ARG)
                [right] - PC=PC+1               (or +ARG)
                [up]    - PC=PC-16              (or -16*ARG)
                [down]  - PC=PC+16              (or +16*ARG)
                [.]     - Set mark to PC        (or to ARG)
                [+/-]   - Swap PC and mark
                [ENTER] - If ARG then set PC = ARG
                [EEX]   - If ARG then set PC += ARG (else view PICT)

        Debug keys:

                [+]     - Single step (ARG) instructions
                [-]     - Single step (ARG) instructions,
                          debug GOSUBs as a single instruction
                [*]     - Single step (ARG) instructions with display update.
                          If no ARG then sets ARG to #FFFFF.
                [/]     - Single step (ARG) instructions with display update,
                          debug GOSUBs as a single instruction.
                          If no ARG then sets ARG to #FFFFF.
                [EVAL]  - Continue until end or breakpoint

                [SIN]   - Save current registers
                [COS]   - Save registers with the saved ones
                          (first save is done at startup)

                ARG + [SIN]     = set cycle counter 1
                ARG + [COS]     = set cycle counter 2

        Exit keys:

                [DEL]   - Restore registers & exit
                [BS]    - Exit now
                [1/x]   - Exit via reset, press second time to confirm

        Breakpoints:

                [PRG]   - Set breakpoint to ARG
                [STO]   - Set breakpoint counter to ARG

        Options:
                [CST]   - Toggle option number (next key)

                        3       - Ascii/hex mode
                        4       - Shift memory dump by 1
                        5       - Automatic switch between PICT/ABUFF
                                  during debug
                        6       - Disable/enable RPL.TAB and DIS.TAB
                        7       - Opcode/cycles display

        Register editing:

                [']     Edit register indicated by next keypress:

                [A] : A[W]      [P] : P         [0] : R0[W]     [S] : SB
                [B] : B[W]      [T] : ST        [1] : R1[W]     [X] : XM
                [C] : C[W]      [Y] : CRY       [2] : R2[W]     [ENTER] : @PC
                [D] : D[W]      [H] : HEX/DEC   [3] : R3[W]     [ARG]: @ARG
                [E] : D0        [K] : DAT0      [4] : R4[W]
                [F] : D1        [L] : DAT1      [R] : RSTK1
                [.] : Recalculate CRC of the library the PC is inside of

                Editing keys:

                [BK] : Cursor left      [ENTER] : Save & exit
                [CL] : Cursor left      [/] : /16       [+/-] : Negate
                [CR] : Cursor right     [*] : *16       [EEX] : Logical not
                [CU] : Rotate left      [-] : /2        [1/X] : Reverse
                [CD] : Rotate right     [+] : *2        [DEL] : Clear



Sample screens which can be reasonably reproduced by

        "#>HXS" DB      (or #59CCh DB)

and then typing

        012345 [PRG] 1  - set breakpoint 1 to address #12345
           090 [STO] 1  - set breakpoint 1 counter to #90 = -70


        Screen 1  - General CPU State (key [A])
                                        +----------------------+
        Mnemonic....................... |GOSUBL  SAVPTR        |
        Opcode......................... | 8E4CD0               |
        PC, P, Cry, Hex/Dec, ST........ |@059D1 P:0 CH ST:B318 |
        A[A], C[A], MP, SR............. |A:059CC C:B1CB7 MP SR |
        B[A], D[A], SB, XM............. |B:A90E1 D:01BF8 SB XM |
        D0 and 6 bytes @D0............. |D0:2345C/6B436F6A04B2 |
        D1 and 6 bytes @D1............. |D1:B1CBC/000000000000 |
        Top 3 levels of RSTK........... |RST:00000:00000:00000 |
                                        +----------------------+
        HST variable names are shown, and are in inverse video if set.


        Screen 2  - General CPU State II (key [B])
                                        +---------------------------------+
        Mnemonic....................... |059D1 8E4CD0  GOSUBL  SAVPTR     |
        A[W],  P, ST................... |A:6A51F4941A9059CC P:0 ST:B318   |
        B[W],  ST[X] bits.............. |B:00000000000A90E1 0011 0001 1000|
        C[W],  Cry, Hex/Dec, HST....... |C:B0000000077B1CB7 CH MPSRSBXM   |
        D[W],  D0, @D0................. |D:9800000000001BF8 D0:2345C/6B436|
        R0[W], D1, @D1................. |0:00000000000A51E9 D1:B1CBC/00000|
        R1[W], RSTK.................... |1:6A51F4941A9059D1  00000 00000  |
        R2[W], RSTK.................... |2:6A51F4941A9CEF94  00000 00000  |
        R3[W], RSTK.................... |3:6A51F4941A900000  00000 00000  |
        R4[W], RSTK.................... |4:00000000000B2302  00000 00000  |
                                        +---------------------------------+

        Screen 3 - CPU State & Instruction Stream (key [C])
                                        +---------------------------------+
        A[A], C[A], D0, @D0............ |A:059CC C:B1CB7 D0:2345C/6B436F6A|
        B[A], D[A], D1, @D1............ |B:A90E1 D:01BF8 D1:B1CBC/00000000|
        Instruction 1, P, Cry, Hex/Dec. |059D1 GOSUBL  SAVPTR    |P:0  CH |
        Instruction 2, ST.............. |059D7 GOSUBL  POP#      |ST:B318 |
        Instruction 3, HST............. |059DD R1=A              |MPSRSBXM|
        Instruction 4, R0[A]........... |059E0 C=0     A         |R0:A51E9|
        Instruction 5, R1[A]........... |059E2 LC(1)   5         |R1:059D1|
        Instruction 6, R2[A]........... |059E5 GOSUB   MAKE$N    |R2:CEF94|
        Instruction 7, R3[A]........... |059E9 C=R1              |R3:00000|
        Instruction 8, R4[A]........... |059EC DAT0=C  A         |R4:B2302|
                                        +---------------------------------+

        Screen 4.1 - Data Stream (key [D])
                                        +---------------------------------+
        D0 Memory Dump................. |D0:409C1/9CB0428A0459A04C4A040691|
        D0 Ascii Stream................ | 40980:......-..@..V.@94..@....  |
        ............................... | 409B0:..- .@.o..@..T.@L...a.n.  |
        ............................... | 409E0:....ENTER{y..a#2..b*q...  |
        ............................... | 40A10:..Q...[....[...>M...#2..  |
        D1 Memory Dump................. |D1:B5CA1/000000000000000000000000|
        D1 Ascii Stream................ | B5C50:.........@p...@....E....  |
        ............................... | B5C80:W*R..?0W..@pK..D........  |
        ............................... | B5CB0:..................... ..  |
        ............................... | B5CE0::....:..,......|........  |
                                        +---------------------------------+
          Current D0/D1 position is shown in inverse
          [SQRT] key will toggle showing only D0,D1 or both
          [CST] [3] keys will toggle the memory dump to/from ascii
          [D] key switches to screen 4.2


        Screen 4.2 - RPL Stream (key [D])
                                        +---------------------------------+
        D0 RPL Stream.................. |D0:409C1 AtUserStack             |
        ............................... |   409C6 KeyOb@                  |
        ............................... |   409CB KeyOb0                  |
        ............................... |   409D0 Custom?                 |
        ............................... |   409D5 NOTcaseDROP             |
        D1 RPL Stream.................. |D1:B5CA1 PTR 00000               |
        ............................... |   B5CA6 PTR 00000               |
        ............................... |   B5CAB PTR 00000               |
        ............................... |   B5CB0 PTR 00000               |
        ............................... |   B5CB5 PTR 00000               |
                                        +---------------------------------+
          [SQRT] key will toggle showing only D0,D1 or both
          [^] [0-8] keys switch showing stream at stack level N instead of D0
          [D] key switches to screen 4.3


        Screen 4.3 - Data Table Stream (key [D])
                                        +---------------------------------+
        D0 Table Stream................ |D0:409C1 CON(5) #40BC9           |
        ............................... |   409C6 REL(5) L81448           |
        ............................... |   409CB CON(5) #40A95           |
        ............................... |   409D0 REL(5) L8141C           |
        ............................... |   409D5 CON(5) #61960           |
        D1 Table Stream................ |D1:B5CA1 CON(5) #00000           |
        ............................... |   B5CA6 REL(5) LB5CA6           |
        ............................... |   B5CAB CON(5) #000000          |
        ............................... |   B5CB0 REL(5) LB5CB0           |
        ............................... |   B5CB5 CON(5) #000000          |
                                        +---------------------------------+
          [SQRT] key will toggle showing only D0,D1 or both
          [ARG] [SQRT] keys will toggle the table format
          [^] [0-8] keys switch showing tables at stack level N instead of D0
          [CST] [3] keys switch to showing ascii instead of hex constants
          [D] key switches to screen 4.1


        Screen 5  - Memory dump (key [E])
                                        +---------------------------------+
        Locations 5990-589F............ | 05990:3AE680D0F40D4F01 .n..O... |
        Locations 59A0-59AF............ | 059A0:56113680913420CC e.c..C.. |
        Locations 59B0-59BF............ | 059B0:4E0156716FCC56FD ..e...e. |
        Locations 59C0-59CF............ | 059C0:015B38D5E0101D95 ...]...Y |
        Locations 59D0-59DF............ | 059D0:08E4CD08E46C0101 .N..N... |
        Locations 59E0-59EF............ | 059E0:D230574911191443 -.u...A4 |
        Locations 59F0-59FF............ | 059F0:4E4A201101311456 ......Ae |
        Locations 5A00-5A0F............ | 05A00:12280A50143174E7 !...A.G~ |
        Locations 5A10-5A1F............ | 05A10:8E58D01311741431 ...1.GA. |
        Locations 5A20-5A2F............ | 05A20:743450000EA248BE GC...*.. |
                                        +---------------------------------+
         current location is indicated by an inverse character.


        Screen 6  - ML Instruction Stream (key [F])
                                        +---------------------------------+
        Instruction 1.................. |059D1 GOSUBL  SAVPTR             |
        Instruction 2.................. |059D7 GOSUBL  POP#               |
        Instruction 3.................. |059DD R1=A                       |
        Instruction 4.................. |059E0 C=0     A                  |
        Instruction 5.................. |059E2 LC(1)   5                  |
        Instruction 6.................. |059E5 GOSUB   MAKE$N             |
        Instruction 7.................. |059E9 C=R1                       |
        Instruction 8.................. |059EC DAT0=C  A                  |
        Instruction 9.................. |059EF LC(5)   =DOHSTR            |
        Instruction 10................. |059F6 A=R0                       |
                                        +---------------------------------+


        Screen 7  - Breakpoint Table Screen (key MTH)
                                        +---------------------------------+
        Mnemonic..................BRK1. |GOSUBL  SAVPTR       |1:12345 -70|
        Opcode....................BRK2. | 8E4CD0              |2:00000  00|
        Cycles / Total Cycles.....BRK3. |14                0  |3:00000  00|
        PC, P, Cry, Hex/Dec, ST...BRK4. |@059D1 P:0 CH ST:B218|4:00000  00|
        A[A] C[A] MP SR...........BRK5  |A:059CC C:B5C9C MP SR|5:00000  00|
        B[A] D[A] SB XM...........BRK6. |B:A9634 D:027AF SB XM|6:00000  00|
        D0 and 6 bytes @D0........BRK7. |D0:409C1/9CB0428A0459|7:00000  00|
        D1 and 6 bytes @D1........BRK8. |D1:B5CA1/000000000000|8:00000  00|
        Top 3 levels of RSTK.....R0[A]. |RST:00000:00000:00000   R0:A56F6 |
        R1[A] R2[A] R3[A] R4[A]........ |R1:059D1 2:DE77D: 3:00000 4:BFA21|
                                        +---------------------------------+

        Any breakpoints at the current location are displayed in reverse.

        Screen 8 - Watchpoints (key [VAR])
                                        +---------------------------------+
        Watchpoint 1................... |1:00000:2369B108DADF1008 2.......|
        Watchpoint 2................... |2:00000:2369B108DADF1008 2.......|
        Watchpoint 3................... |3:00000:2369B108DADF1008 2.......|
        Watchpoint 4................... |4.00000:2369B108DADF1008 2.......|
        Watchpoint 5................... |5:80100:3707020403047020 sp @0@..|
        Watchpoint 6................... |6:80319:A1A1A1A1A1A1A1A1 ........|
        Tempob Bottom Watch............ |  817CC:000000E4A20DB000 ...N*...|
        Tempob Top Watch............... |  A960C:00000895836B5834 ...Y8..C|
        RPL Return Stack Watch......... |  A963E:5A5E3A534F4C4147 ...5...t|
        RPL Data Stack Watch........... |  B5C7E:1075A22549FEF303 .W*R..?0|
                                        +---------------------------------+

          Watchpoints 1-6 are changeable using [ARG] [VAR] [N]

          Watchpoints 5-6 are changeable, but are initialized by DB to
                 5: IRAMBUFF base address (#70100/#80100)
                 6: uart_buffer address (#701FC/#80319)

          Watchpoints 7-10 are fixed, and are updated continuously by DB from
                 7: TEMPOB RAM variable, bottom of tempob area
                 8: TEMPTOP RAM variable, top of tempob area
                 9: RSKTOP RAM variable, top of RPL return stack
                10: DSKTOP RAM variable, bottom of RPL data stack


6  The System RPL Stack
=======================

The SSTK command starts a new kernel which is a modified version of the
internal one. To exit SSTK just execute SSTK again.

Modifications to the internal kernel:

- Stack has 5 lines, including the interactive stack.
- Flag 3 toggles the stack decompiler:
        Set:    Use internal decompiler
        Clear:  Use a system rpl decompiler
- Multi-line mode is not supported.



7  The Entries Catalog
======================

EC command is a browser for the entry tables. Since the entries are listed in
address sorted form both RPL.TAB and DIS.TAB are needed to run EC.

Keys are:

        Up Arrow        - Up one entry
        Down Arrow      - Down one entry
        LS + Up Arrow   - Up one page
        LS + Down Arrow - Down one entry
        RS + Up Arrow   - Jump to first entry
        RS + Down Arrow - Jump to last entry

        Right Arrow     - View the contents for selected entry
                          with ED (or VV for grobs).

        A               - Alphabetical/address sort toggle
        B               - Toggles substring/exact match mode
        F/alpha         - Input find string (entry name grep)
        NXT             - Find next match
        LS + NXT        - Find previous match
        EEX             - Toggle grep mode (show only matches)
        ENTER           - Push entry to stack as :name:address
        LS + ENTER      - Push entry address to stack
        RS + ENTER      - Push entry name to stack
        0-9             - Find entry starting with input address
                          Use 0-9A-F to input a more specific
                          address.
        ON              - Exit browser
        +/-             - Toggle beep on/off


8  The System RPL/Machine Language Editor
=========================================

ED is an editor intended for editing rpl and machine language source code. ED
makes no duplicate of the edited string if it is in temporary object area,
thus enabling editing very large strings. Note that this implies that no
backup of the original string is kept!

Note that ED is very fast but since it supports the tabulator it has to do
special calculations whenever the display is scrolled. Thus scrolling the
display when very long lines are present can be quite slow.

As a hopefully useful feature ED will accept an optional cursor position
argument on stack level one. Thus if ASS gives you the error position you
will be able to jump to that position immediately.

If input is not a string or a string with optional position argument ED
disassembles the object for editing and assembles it at exit. Any error in
assembly causes the editor to restart at the error location.

Most of the normal character keys are in their normal places, others can be
fetched via the special character browser.

Special keys having different definitions are mostly in the non-alpha
plane. The NS,LS,RS planes are defined as follows:

        +-------+-------+-------+-------+-------+-------+
        |BSTART |BEND   |BCOPY  |BCUT   |       |FIND   |
        |       |       |       |BDEL   |GREPL? |REPL?  |
        |BLKUP  |BLKDN  |BSWAP  |BKEEP  |GREPL  |REPLALL|
        +-------+-------+-------+-------+-------+-------+
        |ARG?   |ECCAT  |MEXEC  |REVERSE|UP     |NEXT   |
        |ROW?   |CHR?   |MSTART |TOHEX  |PGUP   |PREV   |
        |POS?   |CHRCAT |MEND   |TOASC  |TOP    |STATUS |
        +-------+-------+-------+-------+-------+-------+
        |''     |STK    |       |LEFT   |DOWN   |RIGHT  |
        |       |BPUSH  |       |LWORD  |PGDN   |RWORD  |
        |       |RCLSTK1|       |LSTART |BOTTOM |LEND   |
        +-------+-------+-------+-------+-------+-------+
        |GOTO   |GOSUB  |GOYES  |       |  ^    |DFIND  |
        |GOLONG |GOSUBL |GONC   |       |CNTRINI|       |
        |GOVLNG |GOSBVL |GOC    |       |CNTR   |       |
        +---------------+-------+-------+-------+-------+
        |EXIT           |TOGSPD |TOGBEEP|DEL    |BS     |
        |               |ASS    |TOGCASE|DELLINE|BSLEFT |
        |               |DOB    |TOGOVER|DELRGHT|BSRIGHT|
        +-------+---------+---------+---------+---------+
        |alpha  |7        |8        |9        |/        |
        |       |SETMK7   |SETMK8   |SETMK9   |()       |
        |       |GOMK7    |GOMK8    |GOMK9    |#        |
        +-------+---------+---------+---------+---------+
        |lshift |4        |5        |6        |*        |
        |       |SETMK4   |SETMK5   |SETMK6   |[]       |
        |       |GOMK4    |GOMK5    |GOMK6    |ASS_RPL  |
        +-------+---------+---------+---------+---------+
        |rshift |1        |2        |3        |-        |
        |       |SETMK1   |SETMK2   |SETMK3   |<<>>     |
        |       |GOMK1    |GOMK2    |GOMK3    |""       |
        +-------+---------+---------+---------+---------+
        |REDISP |0        |.        |SPC      |+        |
        |       |         |,        |TAB      |{}       |
        |OFF    |GOMK0    |NEWLINE  |TAB      |::       |
        +-------+---------+---------+---------+---------+

Explanations:

TOGBEEP - Toggle beep on/off. Default value is taken from the system flag.
TOGCASE - Toggle lower/upper case characters. Also bound to alpha+ls+alpha.
TOGOVER - Toggle insert/overwrite mode.
TOGSPD  - Toggle regular/fast mode

LSTART  - Jump to start of line
LEND    - Jump to end of line
LWORD   - Skip word to the left
RWORD   - Skip word to the right

DEL     - Delete character under cursor
DELLINE - Delete line under cursor
DELRGHT - Delete characters to right of cursor.
BS      - Backspace
BSLEFT  - Delete word to the left
BSRIGHT - Delete word to the right

BSTART  - Set block start address
BEND    - Set block end address
BLKUP   - Set block = start-cursor
BLKDN   - Set block = cursor-end
BCOPY   - Copy block/clip to cursor position
BCUT    - Delete block (copied to clip)
BDEL    - Delete block (not copied to clip)
BKEEP   - Delete all but block (clip not modified)
BSWAP   - Swap clip and text
BPUSH   - Push block/clip to the stack
RCLSTK1 - Pop string from stk1 into cursor position

FIND    - Incremental search. Search is case sensitive if find string
          contains lower case characters.
REPLALL - Find/replace all
REPL?   - Find/replace with verification
GREPL   - Global replace all without changing cursor position
GREPL?  - Global replace all ... with verification
          For example to globally replace "L05512" with some more
          descriptive label just
                - put cursor on the label, press GREPL
                - press alpha to turn off alpha mode
                - press down-arrow to insert the label in the input line
                - press enter to accept it
                - type the replacement and press enter

NEXT    - Find next match
PREV    - Find previous match
DFIND   - Find matching delimiter for delimiter under cursor

MSTART  - Start defining macro key sequence
MEND    - End macro key sequence
MEXEC   - Execute macro key

ARG?    - Input repeat count for next key press
ROW?    - Input row to jump to
POS?    - Input position to jump to
CHR?    - Input character number to insert
CHRCAT  - Character browser, ENTER key echos chosen character to cursor
          position, ON key exits.
ECCAT   - Entries catalog. Any entry you push from EC is inserted into
          the cursor position.

SETMKn  - Set mark <n>
GOMKn   - Jump to mark <n>
GOMK0   - Go to previous cursor position

TOHEX   - Convert block to hex nibbles (Suitable for NIBASC -> NIBHEX)
TOASC   - Convert block to asc nibbles (Suitable for NIBHEX -> NIBASC)
REVERSE - Reverse chars in block/word
ASS     - Assemble source code, if error occurs shows the error message and
          after a keypress jumps to the error position.
DOB     - Disassembles entry under cursor using DOB, spans a new editor to
          view the disassembly. After exit back to the original editor the
          disassembly will be in the clip (if memory allows) ready to be
          inserted into the text if so desired. Special cases:
                #hhhhh          --> view (like plain entry)
                Lhhhhh          --> view
                ROMPTR hhh hhh  --> view
                PTR hhhhh       --> view
                ID name         --> visit contents      (RCL+DIS+ED+ASS+STO)
                INCLOB name     --> visit contents      (RCL+DIS+ED+ASS+STO)
                INCLUDE name    --> visit text contents (RCL    +ED    +STO)
                GROB hhhhh hh.h --> view grob
STK     - Starts a normal SOL. Recursive EDs are allowed. Exit back to ED
          with CONT key. All internal markers except cursor position will be
          lost.
CNTRINI - Initialize counter variable. Number of digits used determines width
          of counter, possible leading  "#" determines a hex counter.
CNTR    - Insert counter into text and increment it. At start the width is
          initialized to 1 hex nibble, so for example pressing
                        [ARG?] 16 ENTER [CNTR]
          will produce "0123456789F"

Special keys during inputline:

        ENTER           - Input ok
        ON              - Cancel
        DEL             - Delete char
        BACKSPACE       - Delete previous char
        LT/RT           - Move left/right. During find input pressing RT at
                          the end of input will take the next input char from
                          the current match location, thus making it easier
                          to complete the match.
        NXT             - Next match during find input
        PREV            - Previous match during find input.
        RS+PRG          - Starts character catalog
        DOWN            - Puts word under cursor to editline

Special keys in alpha plane:

        A LS -  =       ::\n;           (with indent checks)
        A RS -  =       $ ""
        A LS +  =       {\n}            (with indent checks)
        A RS +  =       CODE\nENDCODE
        A ENTER =       \n + indent the same way as the previous line
        A DEL   =       ECCAT
        A BACKSPACE =   FILL (fill entry name with best match)

Notes:
        Repetition and macro key execution can be aborted with the ON
        key. Repetition, macro save and macro execution are aborted
        automatically if an error occurs. Max length of a macro key sequence
        is 50 keys.


8.1  The Viewer
---------------

Command:        VV
Stack:          ( $|grob --> $|grob )
Description:    Simple string/grov viewer.
Notes:          If AGROB command is implemented (EQSTK or Java) it is
                automatically used to view any other type objects with
                size 1 (small).

Keys when viewing a string:

        Up/Down/Left/Right      = scroll display
        PRG/STO/'/EVAL          = scroll onedisplay page
        F/NXT                   = top/bottom
        -                       = slow scrolling
        +                       = fast scrolling (default)
        ON/ENTER                = exit

Keys when viewing a grob:

        Up/Down/Left/Right      = move grob
        .                       = center grob
        ON/ENTER                = exit
        A-F                     = choose scroll speed 1-6

The grob viewer uses a grob! replacement with automatic cutting. Masking
grobs less than 4 bits wide is not not properly implemented yet. Viewing is
done on the text grob, thus the following will create a weird effect: ::
ABUFF xVV ;



9  Entries Table Utilities
===========================

Command:        EA
Stack:          ( $entry   --> hxs_addr )
                ( hxs_addr --> $entry   )
                ( ob       --> hxs_addr )
Description:
                Converts between entry name and it's address.
                For other argument types the address of the object
                is given.

Command:        RTAB
Stack:          ( --> $ )
Description:    Recalls RPL.TAB

Command:        DTAB
Stack:          ( --> $ )
Description:    Recalls DIS.TAB

Command:        RTB->
Stack:          ( --> $ )
Description:    Converts RPL.TAB into readable form

Command:        ->RTB
Stack:          ( $ --> $' )
Description:    Converts an entry list into RPL.TAB form
                Lines accepted are:
                [=]name[whitespace][EQU #]address\n
                ~~~                ~~~~~~~
                optional           optional

                Note that the input should be sorted, no checks for
                that are done. Also the last character in the input
                string should be a newline character.

Command:        ->DTB
Stack:          ( --> )
Description:    Creates a DIS.TAB based on RPL.TAB, stores it to home dir.


Adding a new entry to RPL.TAB:

        - Use RTB-> to get an editable string
        - Use ED to add the new entry definition, must add it to
          it's correct position.
        - Use ->RTB to get the new RPL.TAB
        - Replace the old RPL.TAB with the new one
        - Use ->DTB to get a new DIS.TAB
        - Replace the old DIS.TAB with the new one

Deleting entries is similar.

Prefferred method of editing is to edit the given hpentr.a and use gentab2 to
produce the new tables.

----------------------------------------------------------------------

