Ripped from http://agora.rdrop.com/~hideki/sysrpl.html
Please note -- this is my first try at a sys-rpl help file. I would be open to any suggestions regarding this document. Most helpful would be content-related at first, but if you think the format should stay the same, or change, let me know!
Well, I have received no complaints from anyone about this as an html-only file. That means one of two things:
So, html is all there is.
I decided to write this to help aspiring sysrpl programmers write programs in sysrpl with a minimum of trouble. When I first got interested in programming sysrpl, I had many problems learning. I hope that this will help at least one would-be programmer.
One of the most important things about learning system RPL: memory clears are a facet of life. If you have things you want to keep, please be sure to back them up to a RAM card, or your computer. You have been warned.
First of all, there are a few ways to compile sysrpl. Unlike userrpl, which can be entered directly on the HP48, sysrpl needs to be compiled. RPL is a threaded language; it just stores the memory address to jump to next, and does a simple GOTO, rather than looking up an address from a lookup table using the actual name of the command, such as a language like BASIC does. It isn't compiled in the manner of C or C++; those languages output machine language when compiled. Sysrpl isn't the actual machine language. Instead, it is just the addresses of machine language in ROM. It makes program size a lot smaller.
You essentially have two options to 'compile' sysrpl:
Jazz is now at version 4.0. It takes about 95k on your calculator, so it is limited to running on a GX, SX with RAM card, or a memory expanded calcuator. (Details for expanding your memory are on ftp.cis.com, in the uploads dir. The file is named something like 256kram.doc. I know it has a '256' in the name.) Fin will post any and all future versions to hpcvbbs.external.hp.com.
SJ, also known as Will Laughlin has authored a few changes into Jazz. He has messed with Rick Grevelle's library splitting routines (to make them better :-) added those, and made some interesting changes to ED. Take a look, assuming you can find it; I don't know where it is, but take a look at hpcvbbs.external.hp.com and search around. Hopefully you will find it. Look for a version number 3.5.
I have no experience with gnu tools. I have only heard of experiences with it. If you have DOS, use hptools. If you have something else, compile gnu tools. I don't remember where it can be found on ftp, although I expect it to be on hpcvbbs.external.hp.com.
If you have Jazz, then you might want to fire up EC. EC is the interactive entries catalog I mentioned earlier. For now, just look at the names of many of the Entries. Most are made by appending the names of a few others together; this gives some hint to the purpose of the entry. You will notice some characters in the names that so far, have no meaning to you.
Probably the most obvious is '#'. You will see this often. It stands for Binary Integer, which ranges from 0x0 to 0xFFFFF. (0x in front of a number means it is represented in hexadecimal. I will use this pretty much here only, using HP's notation of #0 to #FFFFF in the rest of the document.) Also called BINT. To see an example on your calculator, without having Jazz or a similar program, just type in :&:[number] where [number] is any real number that isn't a library on your calculator. ie, if there are no libraries number 810 on your calculator, then you can use :&:810 EVAL to get <810d> (depending on your modes value.)
The next symbol you might see is 'hxs'. This is actually a user binary integer, also called a Hex String. The manual HP sent along with your calculator says that they are limited to a word size of 64 nibbles. This is true only in userrpl. In sysrpl, there are very few rules. (Well, a lot, but less than userrpl.)
Another symbol you will see often is '%'. These are normal real numbers, what you use most of the time in user RPL. You may not use it as often in sysrpl, since sysrpl is based mostly on bints. Its brother symbols include 'C%'for complex number, '%%' for Long Real and 'C%%' for Long Complex. Long numbers are similar to Reals, but have 15 digit mantissas, and can go to powers of ten up to 19999. I rather like them. :-)
'$' means string of chars, eg, "hello"; :: means a program (more on this later), {} are lists, eg, {obj1, id1, %%}. 'ID' are ids, just as can be entered on the stack as normal. Eg, 'bob'. LAM is a temporary variable, also called lambda variable. I don't know why, but I would guess it came from Lisp. In user rpl, LAMs were called Local Variables.
There are of course other symbols, but I think these may be enough to understand sysrpl enough to get a decent head start.
Lets review for only a second, what a program is. In user rpl, you learned that a program is of the form <<...>> and you were happy with it, trusting HP when they said that the <<>> were program delimeters. Well, they lied. If you take a User RPL program, and DIS it (DIS is a program from Jazz), you will see a string. Use VV (also from jazz... do you see where this is leading? :-) to view the string. Lets assume you DISsed this program: << DUP >>. The output is " :: x<< xDUP x>> ; ". Let me explain this a bit. The "::" and "; " are the real program delimeters. Now, for a small hurdle: << and >> are actually commands, just like DUP, SWAP, etc. They require no arguments, and set up the calc to allow termination of your programs via the ATTN key. (The 'CANCEL' key on GX... most people still call it ATTN, because, face it, ATTN is a better name. :-)
Here is one of the problems with learning system rpl. When users get used to DUP, they don't usually think about what goes into making sure that there is something to duplicate on the stack. That is okay, since they don't need to, but you are compelled to find out what. I know, because you made it this far. (If no one makes it this far, imagine my embarrasment.) Well, there is a difference between the user rpl command DUP, and sysrpl DUP. The sysrpl DUP makes no checks to make sure there is something to copy. If nothing is there, bad things can happen. (ie, "Try to Recover memory?")
So, when you write system rpl programs, you will want some argument checking to make sure that the user has input the correct args to make the program work. A common practice (I don't like it much, but it works) is using a shell around the core sysrpl routines made of user rpl. This way, you get the protected environment of user rpl to validate things, and once underway, switch to sysrpl for speed.
The other popular method of argument checking, and much more secure, is the command CKn&Dispatch, where 'n' is the number of things to check on the stack. You would use it like this:
::
CK2&Dispatch Invokes checking
#11 Two real numbers?
%SQ Yes? Then Square the lower one.
#0 The catch all 'any'
:: Use user rpl to duplicate and multiply whatever..
xDUP
x*
;
;
I hope it isn't too bad for you... A full list of object types (different in sysrpl from user rpl) is in many manuals, RPLMAN.DOC from HP, Jim Donnelly's new book, and Jim Donnelly's old book.
Most of the entries in the supported list have names that somewhat resemble what the program at that address do. For example, SWAPDUP first SWAPs then DUPs. There are a few that give the user absolutly no clue what they do based on their name. And some are kinda obvious, but are for use in ML instead of sysrpl. If you ever need an entry for a specific purpose, ask me via email for something, with a good description of what you are looking for, and if I don't have a clue, ask on comp.sys.hp48.
Absolutely the best way to learn programming is to write code. To get to the point of writing code, first you need some experience reading it. Try to find as much source code for programs as possible; I really enjoy the Public Domain concept for this reason (and more); it allows you to ask for, and usually receive the full source code for a program, allowing you to either customize it to your needs and/or desires, or base your own programs off ideas learned in these programs. If you do, however, please give credit to the original author. They might have spent hours working on it, perhaps even months and years of effort. PD software only works when we all work together, and not stifle some unheard-of genious by stealing his/her code, and not giving credit, where credit is due.
Try to find well commented source. A good example is in the source code for Shapes, a game by Doug Cannon. He manages to teach the reader many things along the course of the program, assuming that you want to learn ML. Still, it is a useful example of what to look for. A really good source for examples is Jim Donnelly's newest book, An Introduction to HP 48 System RPL and Assembly Language Programming, which is just chock-full of examples, comments, and a load of other goodies too good to mention.
This might be enough for you to go off, writing programs. If not, then just email me, and I will see what I can do to improve it! :)