Programming HP48GX/49G Calculators

in SystemRPL
Overview

What is the difference between SystemRPL and UserRPL?

Why should we use SystemRPL?
How does it work?
What are Entry Points?
What tools are available to compile a systemRPL program?
What does a simple SystemRPL program look like?
How do we compile the simple program?
Where do you go from here?

What is Difference between SystemRPL

and UserRPL?

SystemRPL is the built in programming language custom designed for

the calculators processor
UserRPL is the lanaguage that is documented in the calculators
reference material and is readily programmed on the calculator
through the use of the << >> commands. UserRPL is a subset of
SystemRPL.
Most UserRPL functions are actually small systemRPL programs.
For Example:
The UserRPL function:
::

BEEP is actually a SystemRPL program

Ck2&Dispatch
2REAL
DOBEEP

;
This small program ensures that there are two objects on the stack
and if so dispatches there types in this case 2Reals. If we have
two reals then the systemRPL function DOBEEP is called.
So why should you use SystemRPL rather than UserRPL?

Why use SystemRPL?

For many years I have noticed that surveyors have been dissatisfied
with the HP48GX/49G because of speed problems. Many programs
available today do not go a long way to dispelling this perception.
So why does the calculator suffer from these perceived speed
problems? The answer lies in the language in which the programs
have been written.
If you use UserRPL than you may suffer from two problems:
1.

Each of your UserRPL functions will run a small SystemRPL

program therefore adding additional execution time
2. UserRPL functions have built in argument and error
checking again adding to execution time
It would seem that the answer lies in programming the calculator
directly in SystemRPL therefore eliminating the above problems.
However the novice programmer should be aware that by using
SystemRPL, you are responsible for all built in argument and error
checking. Although many SystemRPL functions also have limited error
checking builtin.
By using SystemRPL execution time for programs can be up to 10
times faster than UserRPL.

How Does SystemRPL work?

To understand how SystemRPL works, you must have a good

understanding of how programs are executed on the calculator.
Essentially UserRPL and SystemRPL programs are similar in that the
calculator does not store the names of functions, only a series of
memory addresses.
When a program runs, execution jumps to each memory address
subsequently ( similar to a GOSUB statement ).
Some more execution may take place there or execution may possibly
jump to another address, eventually execution will return to the
original program and continues until the program is finished.
If the calculator only stores programs as addresses then how can we
edit UserRPL files? The calculator actually contains a table (an area
in the ROM) that is used to cross reference the addresses to UserRPL
command names.
When you view a UserRPL program, the information displayed is the
readable form of the addresses.
When you edit your program, the calculator searches the table for
the corresponding address and constructs a program containing only
memory addresses.
What happens however, if there are other addresses (more commonly
know as entry points that do not have names?

What are Entry Points?

Entry Points are addresses in the calculators ROM that allow the user
to access the 3000+ SystemRPL commands that do not contain names
in the calculators UserRPL table.
SystemRPL commands have recognised names, they are simply not
stored on the calculator and therefore cannot be compiled internally
like UserRPL programs.
When you write a SystemRPL program, the compiler searches for the
name in an entry point table (this is a table that contains a series of
command names and their corresponding addresses in the Calculators
ROM)
Below is an example of part of an entry point table
=4PICK
=4PICK#+
#35E20
#35E20
#3610B
#35F2E

EQU

EQU
#3448A
#3679D

=4PICK#+SWAP
=4PICK+SWAP
=4PICKOVER
EQU
=4PICKSWAP
EQU

EQU
EQU

When the compiler encounters a 4PICK in the programming code, it

will construct a program using the corresponding address.

What are Entry Points?

The compiler will develop a program into a series of addresses that

execute one after another until the program is finished.
This, as you can see is similar to how the calculator internally compiles
UserRPL programs.

What tools are available to compile a

systemRPL program?

There are many tools available today to compile a SystemRPL program

ranging from PC to calculator based.
An excellent place to start looking is http://www.hpcalc.org
The preferred option for this presentation is the PC based HP-TOOLS
available from http://www.hpcalc.org/hp48/pc/programming . Look
for HP Tools for WIN32. The latest version was uploaded
29/12/2002
There is one more important tool that a programmer should have, that
is an Emulator. This is a program that runs on a PC, that imitates a
HP48/49 calculator.
Programs can be tested on the emulator prior to uploading to the
calculator to ensure they are free from errors and run correctly.
This is particularly useful because the only way to test a compiled
SystemRPL program is on a calculator and you would not want to
upload the program each time you wish to run the program.

What tools are available to compile a

systemRPL program?

The following is a screen shot of an emulator for the HP49G:

What does a simple SystemRPL program

look like?

There are several options available for writing and compiling a

SystemRPL program.
The option for this presentation, is to write some source code in a text
editor (such as notepad) then compile and build the final binary code.
You can simply this process by writing a batch file. This is discussed
later.
Lets write some source code. Our program will convert a bearing and
distance to the corresponding rectangular coordinates.
For this program two objects are required on the stack, the bearing on
stack level one and the distance on stack level two. Below is a sample
of the source code:
ASSEMBLE
NIBASC /HPHP49-C/

RPL
::

CK2&Dispatch
2REAL
::

%HMS>
%POL>%REC
;

What does a simple SystemRPL program

look like?

So how does the program work?

Firstly we need to look at the header information:
ASSEMBLE

NIBASC /HPHP49-C/

RPL

All HP files contain header information (including UserRPL files, but

you dont see it) that lets the calculator know for which version of the
HP the program was written.
Since we are compiling and building source code on a PC, no header
information is automatically added. Without the header information
files will not upload correctly to the calculator.
The next line contains the start of the program shown as :: (know
as secondary marker). The end marker is ;. This is similar to the
UserRPL << >>.
Where the real power of SystemRPL is in the removal of error
checking. In our example, we use the command CK2&Dispatch. The
commands checks two objects on the stack and dispatches their
respective types. In this case 2 reals. If we confident that two reals
were on the stack, then these commands could be removed
completely.

What does a simple SystemRPL program

look like?

We could also remove the command 2REAL and the secondary under
that as we no longer need to check for two reals. The program would
simply be:
ASSEMBLE
NIBASC /HPHP49-C/
RPL
::
%HMS>
%POL>%REC
;

How Do We Compile Our Program?

So how do we compile and build the program?

The first step is to create some source code and save it with say a .s
extension. Such as survey.s
Next create a batch file that contains the necessary PC programs to
compile and build the final file, say binary.bat:
RPLCOMP SURVEY.S
SASM
SURVEY.A
SLOAD

SURVEY.A

-H B.M

So how does it work? Firstly we run RPLCOMP SURVEY.S

SURVEY.A. This will generate a file survey.a. Which is the Saturn
assembly source code. The files RPLCOMP, SASM and SLOAD each
contain 200+ manual and are beyond this presentation.
Now we run SASM SURVEY.A. This will generate two files: survey.l
and survey.o. The saturn assembly code object.
The saturn referred to here, is the processor on the HP48/49 and all
files need to be compiled into a format that the processor can
understand.
Next we run SLOAD H B.M. This will produce the final binary file
that can be uploaded to the calculator.

How Do We Compile Our Program?

You may have noticed the file B.M in the last command. You will need
to create this file containing the following:
TITLE
REL
OUTPUT
LLIST
SEARCH
SUPRESS
END

Binary File Compilation Program

Survey.O
Survey.gx
Survey.lr
Entries49.o
XREF

You may notice the reference to entries49.o. This is a saturn object

code file that contains a listing of the entry point table discussed early.
You can download the latest Entry Point Table from
http://www.hpcalc.org
Finally you should check the file Survey.lr for any errors. If none exist
then your program should be ready to go otherwise correct the source
and rerun the batch file.

Where to from here?

You can download several articles that can assist in learning

SystemRPL
Programming in SystemRPL: Eduardo Kalinowski & Carsten Dominik,
2002
http://www.hpcalc.org/hp48/docs/programming
RPLMAN.pdf: A guide to programming in SystemRPL, 1998
http://www.hpcalc.org/hp48/docs/programming
HP48GX/49G Entry Reference: Carsten Dominik and Thomas Rast,
2003
http://zon.astro.uva.nl/~dominik/hpcalc/entries/