SSS - Steve's SysRPL Shell -------------------------- for SX/GX Version 2.21 October 24, 1994 --- User's Manual Contents: --------- 1. Disclaimer and Copyright 2. Credits 3. Introduction/Motivation 4. Requirements & Installation 5. Operating instructions 6. Known bugs 7. Revision history & planned enhancements --------------------------------------------------------------- Note: I marked new text/differences to the old DOC file with a |* sign at the beginning of those lines. --------------------------------------------------------------- 1. Disclaimer ------------- This software is public domain. There's no operational restricion built in. Use it as you like. Copy and distribute it as you like. But keep the two files SSS.LIB and SSS.DOC together. 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 eMail: wolfrum@uran.cs.bonn.edu (preferable) Stefan_Wolfrum@su.maus.de (less than 10K, please) 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! 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. Be patient... 2. Credits ---------- This software wouldn't have been possible to write without the famous and excellent libraries <-RPL-> and <-LIB-> from Detlef Mueller and Raymond Hellstern. THANKS A LOT for this great software! It's just fun to work with it. 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 lates JAZZ.ZIP file in the EXTRA library from HPBot at IRC channel #hp48. (Date of information: October 1994.) [Note: ED *is* included with Jazz 4.0, which is the version on this disk. -jkh-] 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.21 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... ;-) 3. Introduction/Motivation -------------------------- While learning SysRPL on my HP48GX I discovered very soon some unconvenience in handling the different objects, sources, compiled code, the compiler etc. Consider the following: you have <-RPL-> and Stringwriter installed and |->RPL| and |Visit| in your CST menu. To start with a new SysRPL routine you have to o create a new (empty) string, o store this into a variable, o recall the variable's id to the stack, o switch to the CST menu, o press |Visit|, o edit the string, o leave Stringwriter by pressing ENTER, o switch back to the VAR menu, o recall the contents of the variable (the edited string to the stack, o switch back to the CST menu o press the |->RPL| key to compile the string, o store the resulting code to another variable, o switch back to the |VAR| menu o press the appropriate key above the variable name that holds the code until you see what your routine does... 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 o creation of a new SysRPL source string, o selecting existent SysRPL source strings, o editing the currently selected SysRPL string with an editor, o compiling the string with a compiler and o running the compiled object. In addition to that, a MAIN file (executable) can be handled so that you can write and test larger projects. That much for intro and motivation. More detailes can be found in chapter 5. 4. Requirements & Installation ------------------------------ SSS requires the following HARDWARE: a) A HP48SX or HP48GX. A HP48G or S won't work if you want to use <-RPL-> because of d). I tested SSS 2.1 successfully on ROM revisions A, E and P. SSS may work on other ROM revisions but I'm unable to test that. You are encouraged to tell me about success or problems with other ROM revisions. b) At least a 32K RAM card if you want to use the <-RPL-> library as your compiler. This is due to the <-RPL-> library which has to be stored into port 1. c) For those who don't have any RAM card but a GX with 128K internal RAM: be happy! You have to store the JAZZ lib, RPL.TAB and my SSS library into port 0 and have app. 54K RAM free. You'll then have to use the internal editor which may not be that useful. In this case just install the StringWriter 4.2b library into port 0, too. You still have enough RAM to develop SysRPL programs. [Note: these numbers have changed as the JAZZ and RPL.TAB files have been upgraded and grown in size. -jkh-] The following SOFTWARE is required: d) Compiler: One of the following compilers is needed: --------- o <-RPL-> by Detlef Mueller & Raymond Hellstern. See their documentation for installing <-RPL->. o JAZZ by Mika Heiskanen (You can, however, install both libraries if you want. No problem.) e) Editor: One of the following editors is needed: ------- o StringWriter 4.2b by J.Y. Avenard. o ED by Mika Heiskanen. ED is now found in Mika's JAZZ library. ED needs the JAZZ library to work. Therefore the combination <-RPL-> as compiler and ED as editor won't work if you have just <-RPL-> installed. You could install JAZZ _and_ <-RPL-> and then use <-RPL-> as compiler and ED as editor. But this is not recommended as it steals too much RAM for the whole JAZZ library which is nearly unused except for ED. |* |* See below for more about using ED. |* SSS can use the internal HP editor as mentioned above. If you wish 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: 1. Unpack the file SSS.ZIP. It should contain SSS.DOC (this file) and SSS.LIB (the library). [Already done for you. -jkh-] 2. Transfer SSS.LIB (binary mode!) to your HP48. 3. Recall the contents of SSS.LIB to the stack: press [right shift] and the menu key that holds SSS.LIB 4. Purge 'SSS.LIB': press ' and then again the menu key that holds SSS.LIB. Press PURG ([left shift] [EEX]). The library remains on the stack. 5. Depending on where (in which port) you want to store the library enter the number of the port (e.g. 0 or 1) and press [STO]. 6. Turn your HP48 off and then on again or do a ON-C reset. The library (ID=1414) attaches itself and should be visible in the Library menu. 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. 5. Operating instructions ------------------------- _ To use SSS go to the Library menu and press | SSS |. Two commands are exported: SSS and INFO. 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: Current Main Options ------- ------ ------- NEW... CHOOSE... COMPILER CHOOSE... RUN EDITOR... EDIT +------------------- COMPILE | MAIN: RUN |CURRENT: +------------------- |INFO... QUIT (well, in fact it's a little nicer... ASCII is a drawback!) The commands are buttons with a small shadow behind them. The NEW button in shown reversed. Now the following keys work: Cursor Up, Down, Left, Right: 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... ENTER : Selects the currently highlighted option. MTH : Allows putting things on the stack. (see below) |* PRG : Allows looking at the stack (first 9 levels). |* |* EVAL : Evaluates object on stack level one. |* |* <- : Drop object on stack level one. |* |* F : 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: 'NAME.S' : SysRPL string containing the SysRPL commands as you typed them in. 'NAME' : The executable code compiled from 'NAME.S'. The latter kind of objects aren't visible for the user of SSS during an SSS session excepted for the Main:CHOOSE command where you have to select a compiled object for MAIN. 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.) The menu commands: ------------------ A. The "Current" commands: -------------------------- NEW... ------ This creates a new, empty SysRPL string. After you selected this option you are prompted for the name of the new string. ALPHA mode is on so you are ready to type. 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. CHOOSE... --------- This is the other option to change the CURRENT string. It allows you to select one of all the strings in the current directory (and just there!) whose names end with the .S suffix. 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 ENTER. Other keys that work in this choose box are: Softkey E: Page Up y^x key : Page Down Softkey F: Go to first name in list NXT key : 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. EDIT ---- If the CURRENT name isn't , selecting the Edit option invokes the editor with the contents of the current name. You can now edit your SysRPL program as you like. 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 an error message is displayed and you'll have to press a key to continue. COMPILE ------- This starts the compiler (either ->RPL or ASS from JAZZ) if there was a current name other than . The screen displays a logo while the compiler runs. 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. 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: CAUTION: You now have the possibility to put objects on the stack while running SSS 2.21. 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. B. 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. 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.21 so there should be |* just executable programs shown in the choose box. RUN --- Says it all... Executes the object whose name you've selected with the CHOOSE (Main) option. 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!!! C. The "Options" commands: -------------------------- COMPILER -------- This button allows you to select the compiler. A 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. 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. If you select ED as editor and don't have 'Ed' in your HOME directory ED cannot be invoked. But the id 'Ed' is left on the stack. 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. D. 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. |* E. Putting Arguments on the stack with the MTH key |* -------------------------------------------------- |* |* 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. |* 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. |* |* |* |* F. Jazz 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 the cursor up and down keys, |* flip a flag by pressing the +/- key and exit with the ENTER or ON |* key - they both exit keeping the changes you've made. 6. Known bugs ------------- - Sometimes a binary integer is left on the stack if SSS was started by typing in SSS in the command line and pressing ENTER instead of starting SSS by pressing the |SSS| key in the Library or your CST menu. If anybody has an explanation for this behaviour I'd be glad to hear from you! 7. Revision history & planned enhancements ------------------------------------------ |* Version 2.21 |* ----------- |* Fifth official release. Release on October 24, 1994. |* |* News: o PRG key for looking at the stack |* o EVAL key evaluates object on stack level one |* o <- (Backspace) key fro dropping object on stack level one |* o Jazz Flag Browser bug fixed! Thanks to Richard Steventon!! |* o some error grobs removed => smaller size |* o credits grob packed => smaller size but slower scrolling |* o check is done whether 'Ed' exists in HOME dir (if editor |* to use is ED) |* o check is done whether StringWriter lib is installed; error |* window is produced otherwise |* o just executables in CHOOSE Main choosebox |* o dramatically improved speed when waiting for an upcoming |* choose box for selecting a current or main object (thanks |* to Jens Kerle for his ML routine here; it was inspired |* by Mika Heiskanen and Rick Grevelle who did fundamental |* work on this...) |* o SORTLS2 from Todd Eckrich, modified by Jens Kerle improved |* sorting time and therefore shortens waiting time for upcoming |* choose box, too. In fact, there's almost no waiting any longer... |* o Softkey F invokes RPL's or JAZZ's EntryCatalog corresponding |* to the compiler selection in the Compiler Options screen |* o bug fixes in put-on-stack-routine... Version 2.1 ----------- Fourth official release. Released on October 4, 1994. News: o possibility to put thigs on the stack o jazz flag browser (with bug :( ) o slightly smaller in size because of compressed grobs o you can now write programs that modify the current path, like :: HOMEDIR ;. This wasn't possible before because SSS couldn't find its control variables if you changed the dir. Now the current path is saved before a run and restored afterwards. (Thanks to Thomas Weidlich for pointing me to that problem.) 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... Third official release. Released on September 13, 1994. News: o completely new look and user interface ----- o no longer shortcut keys... (probably not a feature) o not restricted to <-RPL-> and StringWriter o can make use of JAZZ, ED and the internal editor o SX compatible because of self-written choose box and sorting commands Version 1.1 ----------- Second official release. Released on June 29, 1994. News: o Main file function ----- o slightly changed look 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: - Placing cursor at error location when compiler errors and SSS jumps to the editor. Placing the cursor somewhere in the text directly after starting StringWriter is possible. But I don't know how to get the position of the error from ->RPL or ASS... - Possibility of aborting ED without making the changes... - No error exit if editor is called that isn't installed properly. - Machine Language routines whereever possible. Would be _extremely_ handy for getting a list of all IDs in the current dir that end with .S and those which don't end with .S because if you have lot's of source strings in the current dir you have to wait quite a long time until the choose box comes up... Jens Kerle is working on that... 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! Stefan. ---------------------------------------------------------------