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 EQU #3448A=4PICK#+ EQU #3679D

=4PICK#+SWAP EQU #35E20=4PICK+SWAP EQU #35E20=4PICKOVER EQU #3610B=4PICKSWAP EQU #35F2E

• 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 don’t 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 SURVEY.ASASM SURVEY.A

SLOAD -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 Binary File Compilation ProgramREL Survey.O

OUTPUT Survey.gxLLIST Survey.lr

SEARCHEntries49.o SUPRESS

XREFEND

• 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/