I tried hard to eliminate all bugs but there may still be some in. Please report them to me.
You cannot make me responsible for any damage that this software may do to your hardware or for any loss of data due to system crashes. BACKUP YOUR MEMORY BEFORE USING THIS SOFTWARE TO AVOID DATA LOSS!
This software is not shareware. Although you can send me money or a postcard if you like my program. :-)
The author (that's me) can be reached:
Stefan Wolfrum
Servatiusstrasse 27
53175 Bonn
GERMANY
The first version of this software was written completely in SysRPL. It was my first larger SysRPL project. Keep this in mind if you want to decompile and study my code!
Later came machine language routines for speeding up things - thanks to Jens Kerle!
I hope everything works fine. Known bugs are listed in chapter six. Suggestions are always welcome!
(c) 1994 by Stefan Wolfrum.
Note: English isn't my native language. So please be patient...
The editor of my choice is Jean-Yves Avenard's Stringwriter. Without it, it would have been much more difficult to hack out SSS. It's the best editor for the 48GX! Even beats QED!
I got some feedback from people who said that they use JAZZ rather than <-RPL-> and ED rather than StringWriter. So I made it possible to use more than one compiler and more than one editor. Namely I'd like to thank Seth Arnold here.
JAZZ was written by Mika Heiskanen and is a complete, powerful Assembler/Disassembler not only for SysRPL but ML, too. ED is a nice little editor which is not included in the JAZZ library but can be found in the latest JAZZ.ZIP file in the EXTRA library from HPBot at IRC channel #hp48. (Date of information: October 1994.)
I'd also like to thank those guys who helped me learning SysRPL via the Usenet newsgroup comp.sys.hp48. Some of the "gurus" are really friendly and tried hard to help me out with my problems. Namely there is Bill Levenson who helped me with the :: ... ; problem of a case struct within a loop... Thanks again!
SSS 2.2 contains an even faster sorting routine, called SORTLS2. This was posted to comp.sys.hp48 some days ago and Jens Kerle modified this ML routine to fit SSS's needs. SORTLS2 was implemented by Todd Eckrich.
Finally I'd like to thank Jens Kerle _very_ much for his great and uncomplicated help with ML routines. I met him personally at the Amsterdam PROMPT conference this year and we talked a lot about the HP48 and SSS and ML. I think Jens more and more becoming the co-author of SSS... ;-)
This seems to be too much switching and pressing for me. So I invented SSS.
SSS simplifies the above mentioned procedure by managing the steps from a menu. The menu provides
That much for intro and motivation. More detailes can be found in chapter 5.
See below for more about using ED.
SSS can use the internal HP editor as mentioned above. If you like to use it you don't have to install any editor of course.
See the next chapter for details on how to determine which editor or compiler to use in SSS.
Installation:
For proper operation the compiler and editor must be installed as well (of course). In case of the <-RPL->, JAZZ and StringWriter libraries just install them like any other library into a port of your choice.
If you want to use ED as editor you have to create an ID in your HOME directory called 'Ed' (note the upper case 'E' and the lower case 'd') that executes ED. SSS looks for that and executes whatever this ID does.
So, for example, if you have the EXTRAS library installed, just make 'Ed' contain ED (enter the list { ED } on the stack, do a OBJ->, a DROP and store the remaining into 'Ed').
If you don't want to install Mika's whole EXTRA library but still want to use ED just make the ID 'Ed' in your HOME directory contain the executable ED. This works as well.
One combination will produce an Error and quit SSS with garbage left on the stack: if you have JAZZ but not EXTRA installed and 'Ed' in your HOME contains the ED command as reference to the EXTRA lib.
INFO shows an informational screen with some data about SSS including the current version number and my eMail address. Feel free to eMail me!
After a keypress you'll get into the credits screen where all the names of the guys who helped are scrolled like in movie titles... Press a key to exit from that.
SSS starts the Shell. The following screen should appear:
The commands are buttons with a small shadow behind them. The NEW button in shown reversed.
Now the following keys work:
Moves around the buttons. They work "round
the corner", i.e. pressing left in the
leftmost column goes to the rightmost
column and vice versa. Same with up/down...
Selects the currently highlighted option.
Allows putting things on the stack.
Allows looking at the stack (first 9 levels).
Evaluates object on stack level one.
Drop object on stack level one.
Invokes EntryCatalog EC; depending on the compiler
setting made in the Compiler Options screen either
<-RPL->'s or JAZZ's EntryCatalog is started.
Invokes Richard Steventon's Jazz Flag Browser
if Jazz is marked as the used compiler in the
compiler options screen.
ON: Quits SSS. Same as selecting the QUIT button and pressing ENTER.
Above the INFO and QUIT buttons you'll find two lines reading MAIN and CURRENT. They tell you the name of the CURRent and the name of the MAIN SysRPL program that will be edited, compiled and executed when the appropriate option is selected. However, there's a little difference between these two names:
The current name is the name of a string as indicated by the ".S" suffix. A current name contains the source code of the SysRPL program. The main name is the name of a compiled, executable SysRPL program and therefore does not end with the ".S" suffix.
The Choose commands allow only the choice of names with or without the ".S" suffix resp.
You can change the current string either by creating a new, empty SysRPL string with the NEW command or by selecting one of the SysRPL strings that exist in the current directory by selecting the CHOOSE option in the "Current" (the first, leftmost) column.
Naming conventions: a SysRPL string's name always ends with the two characters ".S". If you compiled the string successfully an object with the base name, i.e. without the ".S" is created that contains this code. The RUN command simply evaluates this code object.
Once again:
After quitting SSS you'll see the created code objects that contain the compiled SysRPL code in your var menu. ("code" in this context doesn't refer to Assembler CODE objects.)
DON'T TYPE IN THE .S SUFFIX! IT'LL BE GENERATED AUTOMATICALLY BY SSS.
Just type in the base name and press ENTER. Or press ON to abort creating a new SysRPL string.
CAUTION: You could type in a name that's no correct name for an object in User RPL terms (e.g. ".-*"). The object will be created nevertheless. This could lead to severe problems and unpredictable results! One little problem would be that you won't be able to purge this object from within pure User RPL. So watch what you type and just use correct names! Even just a space as name will be possible... Be careful!
You cannot enter an empty string, i.e. entering no char and pressing ENTER. This is prompted with an error message "No name given!" and you'll have to press a key to continue.
If you typed in a correct name the editor is invoked automatically and you can start typing in your program. The new name will be shown beneath the CURRENT: info line in the main SSS screen with it's .S suffix after you've finished editing.
If there is at least one name that matches this name
convention a CHOOSE box is opened which contains - in
alphabetical order - all names of SysRPL strings in the
current directory. Now just walk with the cursor keys up
and down the list and select the desired name by pressing
.
Other keys that work in this choose box are:
Page Up
Page Down
Go to first name in list
Go to last name in list
There's no repeat functionality if you hold down one of those (including the cursor) keys...
Press ON/CANCEL if you changed your mind and want to return to the main menu without selecting a new current string.
If there is no name matching the .S convention in the current directory an error message is displayed ("No current string!") and you have to press a key to continue.
Note that the ED editor doesn't allow to quit editing and discard the changes made so far! You just can leave ED with the ENTER key and thereby accept the changes you made...
If the current name was
If an error occurs during compilation an error window
occurs and you have to press a key. After that you are
led to the editor and can look for the error and edit it.
unfortunalety the cursor isn't placed at the error location.
Haven't found out how to do that yet...
If no error occured during compilation you go back to the
main menu after compilation.
CAUTION: You now have the possibility to put objects on the
stack while running SSS 2.2. But always remember to
put any necessary arguments on the stack if the
program you're going to run needs arguments from the
stack as you know that SysRPL does not make any
argument checking and so strange things can happen
unless you do argument checking within your source.
If there's no object containing the compiled code in the
current directory an error message is displayed and you have
to press a key to continue.
This feature is just for executing purpose. You cannot
change your selected main object. If you'd like to do so
you'll have to load the corresponding ".S" string as your
current object and edit/compile it with the already decribed
menu options.
The choose box contains all names from the current
directory that do not contain the ".S" substring.
A type checking is now done in V2.2 so there should be
just executable programs shown in the choose box.
Again: BE WARNED! If your main program requires arguments
from the stack put them there by means of
the MTH key (see below).
CAUTION: This RUN command does NOT ask if you're sure!!!
Mind installing conditions as mentioned in chapter 4!
If you select an editor whose library isn't installed and you want
then edit a string, SSS exits with a Undefined XLIB Name error.
Clear the stack, start SSS again and select the right editor in that
case.
SSS maintaines a configuration variable called SSSCONF which holds
information about the selected compiler and editor. It's a binary
integer (in SysRPL sense) and it is created in the current dir with
a default setting (<-RPL-> and StringWriter) if it doesn't already
exist in the current or the HOME directory. If found, it's contents is
used so there's no need to change the setting every time you start
SSS.
Just imagine that you're in a SysRPL mode. So if you type
a 5 for example that object on the stack will be a <5h> system
binary.
More generally spoken, consider your input as a string that
is to be parsed by the used compiler. So, if you want to put the
real number 5 on the stack you'll have to enter the string "%5"
(without the quotes, of course). Be careful! The string %5 without
a space between the % and the 5 just works because %5 is a named
entry point (address #2A31Dh on my GX). If you want to put, let's
say 111 on the stack you have to enter a space between the percentage
character and the number.
The entered string will be compiled with the selected compiler
and if that doesn't lead to an error the result it put on the stack.
If there was an error during compilation -- consider for example
you want to put a vector [1 2] on the stack; the string "[1 2]"
cannot be compiled without error by Jazz or ->RPL because it's
not SysRPL syntax -- then the entered string is given to the
internal compiler so that you can enter things just as you are
used to when you're in normal stack mode. This means you can enter
UserRPL programs or arrays or unit objects without converting them
into SysRPL syntax in your head before just like you would do in
the HP48's normal operation mode.
Play a little with this new feature. Put several things on the
stack, quit SSS and look what's there to get used to the feature.
If anybody has an explanation for this behaviour I'd be glad
to hear from you!
News:
News:
Third official release. Released on September 13, 1994.
News:
News:
COMPILE
This starts the compiler (either ->RPL or ASS from JAZZ)
if there was a current name other than RUN
This option executes the current SysRPL program if it was
compiled correctly. A warning box gives you a last chance to
change your mind. Only if you press Y (the +/- key) the
compiled current will be executed. This waning box is due to
the following fact:The "Main" commands:
CHOOSE...
Allows you to select the main object in the upcoming choose
box (keys: look above). There'll be only such names that do
not contain the ".S" suffix and that are executable programs.
This should it make easier to select an already compiled
SysRPL program as your main program.RUN
Says it all... Executes the object whose name you've
selected with the CHOOSE (Main) option.The "Options" commands:
COMPILER
This button allows you to select the compiler. The following
screen comes up where you can select the compiler with the up and
down arrow keys.
Press ENTER to select the compiler, press ON/CANCEL to leave
things unchanged.
EDITOR...
Same as above. A screen with three choices comes up: StringWriter,
ED and HP built-in. Select with up/down arrow keys and ENTER. Use
ON/CANCEL to quit with no changes.
Although mentioned at the bottom of the screen no special library must
be installed if you want to use the internal HP editor, of course.INFO and QUIT commands:
Well, QUIT is obvious and INFO brings up two info screens with
copyright information and credits. Just press a non-shift-key to
go through these pages and return to the main menu.Putting objects on the stack with the
After you've pressed the MTH key you can enter objects
that will be put on the stack. The syntax here is a bit
of getting used to. keyJazz Flag Browser:
Richard Steventon wrote a nice little tool which allows you to
set the flags that Jazz uses in an interactive way. He allowed me
to include his tool into my SSS library. You can access his flag
browser by pressing the key. This works only if you have marked
Jazz as the compiler to be used in the compiler options screen.
Usage is simple: just move around with and ,
flip a flag by pressing and exit with or ON
- they both exit keeping the changes you've made.
6. Known bugs
Contents
7. Revision history & planned enhancements
Version 2.2
Fifth official release. Release on October 24, 1994.
Version 2.1
Fourth official release. Released on October 4, 1994.
Version 2.0
Working title was 1.5 but I decided to call it 2.0
because of the obvious new look of the main menu...
Version 1.1
Second official release. Released on June 29, 1994.
Version 1.0
The first official release;
released on June 22, 1994.Planned enhancements:
I've some features in mind that'll be implemented in future
releases of Steve's SysRPL Shell:
This completes the SSS documentation. Have fun and don't forget
to send me a postcard if you like SSS and use it a lot. Thanks!
Back to SSS V2.2 Homepage
Back to HP calcs Homepage
Last updated: April 17th, 1996
email: wolfrum@cs.uni-bonn.de