-----BEGIN PGP SIGNED MESSAGE-----

Hash: SHA1

JAZZ V6.8

System RPL and Machine Language Development Library

(c) 1995-2001 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
Lots of bug fixes
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.
Andre Schoorl For UFL, JAZZHOOK, bug fixes, and taking over
maintenance.

Beta testing & suggestions:

Seth Arnold Daniel Lidstrom

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

+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
lenght 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 lenght 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.

- ----------------------------------------------------------------------
-----BEGIN PGP SIGNATURE-----
Version: PGPfreeware 5.0i for non-commercial use
Charset: noconv

iQA/AwUBOrureOhzXOws+qC7EQINJwCfVG7VJ2/2/ot4kRgq5vpgJkPRv20An3lj
GrEmFYDDPeTbpx5fhEM1mLCY
=FGWO
-----END PGP SIGNATURE-----