BEGIN_DOC roldx.doc version 6.5, 10 Nov. 1995 James Weisbin. Roldx for the HP48 v.6.5 (c) 1995 James Weisbin, is a "rolodex" style data browser for the HP48 which includes fast sequential and binary search routines, sorting, a 7 to 10 line display, editing, printing, database selection from within the program, password encryption of individual entries, viewing of entries in "full-screen" or in "headings only" mode (with repeatable scrolling-menu line display) and can be used as a general pur- pose list-browser. Version 6.5 can call "Stringwriter" or "QED" (not included). This is the latest version of the Roldx program, an older version of which was on on HP's "back to school" disk. Roldx is a library with ID number 1765, approximate size 9.7 Kbytes, and is "shareware", $15.00 U.S. to register. (James Weisbin, 115 West Broadway, New York City, New York, 10013 U.S.A.) e-mail: 73457.3462@compuserve.com (c) James Weisbin 115 West Broadway NY NY 10013 USA 73457.3462@compuserve.com Noncommercial distribution allowed, provided that this copyright message is preserved, and any modified versions are clearly marked as such. THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. Roldx has been tested on a rev M (GX) and should work on all previous rom versions, as well as rev P and S and SX versions, but no guarantees or warranties are either made or implied. USE AT YOUR OWN RISK PLEASE BACK UP YOUR CALCULATOR'S MEMORY BEFORE USING THIS SOFTWARE. I am in no way responsible for any loss of data through the use or misuse of this program. Changes to Roldx version 6.5 from version 6.2: 1. right-shift-edit (from keyboard or menu) invokes "QED". The program invokes QED which must either be in the current directory of in the home directory. If that program is not found, then the HP's native editor is used instead. QED is not supplied with Roldx. Contact Rick Grevelle, 2300 Broadmoor #73, Bryan, Texas 77802 (409) 774-1169 for the latest version. I have tested Roldx with verson 2.01 of QED (GX version) ONLY. 2. If left-shift-edit is used to invoke Stringwriter, but that library is not found, then Roldx now uses the HP's built in editor instead, instead of giving an error message. 2. Fixed DBRDX which now starts up with 7 fields as a default. 3. Fixed problem with stringwriter when editing an empty data- base (null list) which caused Roldx to not display the edit- ed entry. 4. Added the ability to SortR to use a user supplied sort program, USORT, instead of the built-in < comparison for strings. 5. Roldx 6.5 has been tested with version 4.4 of Stringwriter on the HP48GX. Changes to Roldx version 6.2 from version 6.0: 1. left-shift-edit (from keyboard or menu) invokes "String- writer" by J. Y. Avenard, provided that you have installed that library on your machine. "Stringwriter" is not supplied with Roldx. Contact Jean-Yves Avenard, 16 Rue de Savigny, 91390 Morsang sur Orge, France. email: avenar_j@epita.fr 2. A new command "DBRDX", has been added. This is a version of Roldx which expects the name of a database and a number of the position to start in to be on the stack, and does not read or write "rdPAR". This is useful if you want to call Roldx from another application and use it to browse data. 3. "nexch" has been removed, because you can cut and paste much more easily with "Stringwriter". The source code is listed below, for anyone who wants it. 4. "rpar" (read rdPAR) and "wpar" (write rdPAR) have been made visible, accesible from the Roldx library menu, for those who want to be able to modify it directly. See below. 5. Roldx now saves its flags in rdPAR, and restores the user's flags when done. This means that you can no longer "pre- configure" the flags for ROLDX, but you can with DBRDX. Since the flags are remembered by ROLDX, and wont be changed by other programs, this shouldn't be objectionable. Roldx is written entirely in System-RPL for speed and compactness. Thanks must go to the following people for their contributions to this program: Glenn Robertson, for the binary search routine and for his encouragement, Simone Rapisarda, for the Coder program, Joe Horn, for the sorting algorithm, Detlef Mueller, for RPL48 (Great!), Raymond Hellstern, for LIB, and J. Y. Avenard, for Stringwriter. Note - for a really powerful "personal information manager" try Glenn's PIM48, which works well in conjunction with Roldx. It's written in System-RPL, and has many features, including separate appointment and "to-do" lists for each day, and an outliner. Its awesome! Shameless advertisement: HVAC engineers might want to try my "Psychro" program for psychrometric calculations involving air/water mixtures. It is also written in system-RPL, is very fast, and has an interface which is similar to Roldx. Roldx has many features that other rolodex programs lack, such as the ability to view only the "headings" of up to 8 entries at once (by "heading" I mean the first line, but any line number can be selected), password encryption of individual items, sorting, database selection, editing, and a scrolling-menu display (like the equation library card). The database structure is "free form" in the sense that you can store anything you like on any line, an "item" being a collection of fields in a list. Up to seven fields of 22 characters each can be displayed when using the medium font, or up to 10 lines with the small font, depending on whether the menu is visible or not. The HP48 can display up to 10 lines of text quickly and I find this to be adequate room to store names, addresses, phone, fax, and email data. Roldx 6.5 is dist- ributed as an auto-attaching library, with ID number 1765, size 9721 bytes, checksum # 1684h. To install the library, first transfer the binary file RLDX65.LIB to your machine using Kermit in Binary transfer mode on both the HP48 and the host machine. Then put the library on the stack, by pressing the menu key that shows up labeled RLDX65.LIB. You should then see this on the stack: Library 1765: ROLDX... Decide which port you want to store the library in. Port 0 doesn't get backed up when you use the Archive command, so you might want to use port 1 or 2, if you have a battery backed-up ram card in one of those. Enter the number of the port (e.g.: 1) and then press STO. Then turn your machine off and on again. The screen will flash off and back on again when the '48 reconfigures itself. Now press the LIBRARY key (right-shift LIBRARY on the GX), and keep pressing NXT until you see ROLDX on the menu. If you don't see it, it hasn't been installed properly - try again. To uninstall the program, go to the MEMORY menu ( left shift LIBRARY on the GX). Enter 1765 on the stack and press DETACH, then PURGE the library by doing :port#:1765 PURGE. NOTE: If, when trying to purge the library, you get the message that the object is in use, go to the PRG CTRL menu (HP48SX) or PRG ERROR (HP48GX and press ERR0 to clear the last error. If you still can't purge Roldx, then try a warm start (ON-C) first. ON-C wipes your stack, so store any needed data into a variable first! If you have Raymond Hellstern's "Lib" library, tou can use the PGLIB command to purge the library. To run the program, make sure that you have switched to the directory where you wish to keep your data. Note: Roldx "auto-attaches" at start-up, and is therefore available in any directory, including the home directory. However, I recommend that you NOT store your data in the home directory, for reasons cited below. If you've managed to install Roldx correctly, then go to the directory that you wish to run Roldx from. (See below for a small program to automate this). NOTE: If you have a data-base list that you've been using from an older version of Roldx, copy it to that directory. Otherwise, it is best to start the first time with a directory with no lists in it at all. Now press ROLDX from the library menu to start the program. If this is the first time you're running Roldx you will get the message: "Invalid rdPAR Press any key". Don't panic - press any key and Roldx will go into data-base selection mode. Select a list from the menu by using the arrow keys to highlight it, then press ENTER (or ATTN or backspace). If Roldx couldn't find a valid list then it created its own called List1. You will now be placed in "Headings only" mode. Press ENTER to see the full screen. You can't delete the first item if there are no others, but you can edit it - or you can exit the program, put the list on the stack, and edit it using the normal HP48 editor. If you don't see a menu line, press * to get to the main menu, at which point you will see the following menu items: FIND FIND text prompted for. If one character only, only the 1st character of the line selected is checked for a match. If more than one character, a match is sought in any position. Only the line number set by the variable rdLINE is searched. Case is ignored (lowercase text is temporarily converted to uppercase). NOTE: If lock mode is "on" (flag 39 clear) then password protected items WONT be found. Note: the text from the last search is stored in rdPAR and used as the default input line. Press ON once to clear the command line and start fresh. Pressing ON again will abort data-entry and return to the current viewing mode. You can also interrupt an active search by pressing ON. STATUS find out about and change settings. Brings up the following menu: LINE? |---> ==== >--? abc MAIN The first menu key prompts you for the line number to search, and display if in headings mode, and then prompts for the number of fields to enter when adding items. If you enter a number larger than 10 or smaller than 1 for the number of the line to search/display, Roldx will report an error and go back to the status menu without changing the value. If you enter any number larger than 1, Roldx may look odd when in headings-only mode, since many of the entires might be blank. After the lines? prompt, you are prompted for the number of fields, which should also be in the range of 1 to 10 (7 is the default). Note: you are not limited to 10 fields - your data may contain as many as you like, provided that you create them outside of Roldx and then insert them. This value only affects the number of fields to be entered for new items within Roldx itself. The second key changes whether the database is searched from the top or from the current item to the end. The third menu key changes whether one line of each item ("headings-only" mode), or all lines of the current item are displayed (full-screen mode). The fourth menu key (picture above is supposed to look like a key) toggles lock mode. When toggling it "off" you will be prompted for the password. There is no "wrong" password, but your data will be garbled unless you use the same one you used when you encoded it. The fifth menu key selects whether, when adding or editing an entry, lower case or upper case mode is initially selected. The last menu key (MAIN) returns you to the main menu. You can also use backspace, or ATTN. HELP brings up 2 short help/about screens ->STK puts the current item on the stack. Left-shift ->STK puts only the first field from that item left on the stack. See RCAR below for more information shift about this feature. If the item is encoded (pass- ->stk word protected), it is NOT decoded when placed on the stack, so you can use ->STK to move your items around (Don't use Left-shift ->STK to try to move items, because it STK-> expects a list) STK-> insert an item from the stack. If it is not a list, an error is generated. Inserts BEFORE the current item. EXIT quit the program. EXIT can also be initiated by pressing the backspace key or the ON (ATTN) key, no matter which menu page is showing. To get to page two of the main menu, press the NEXT key (PREV takes you back to page one of course.). When in page two, the following items are presented: BFIND This is based on Glenn Robertson's binary search routine. Only the first character of the text entered is used, and only the first character of the first line of each entry is searched. The file MUST be in alpha sorted order for this to work properly (see SORT below). If you consistently get to items which you didn't want, then the file is probably not sorted. This routine is also always available from the EEX key, no matter which menu page is showing. See FIND above concerning text entry. Suggestion: try entering more than one character to Bfind, e.g. "ABC". Bfind will find the first item beginning with "A" (assuming one exists). Then use Find, starting from the current position, to find the actual text "ABC". This method is very fast. ADD add an item BEFORE the current item. This routine is also always available from the + key, no matter which menu page is showing. DEL delete the current item. You can't delete 1 of 1 from within Roldx, but of course you can at the operating system level. This routine is also always available from the minus (-) key, and the DEL key, no matter which menu page is showing. EDIT all lines must be processed, an empty string is OK. Pressing the ATTN (ON) key once clears the line, pressing it a second time exits edit mode, discarding all input, with the message "interrupted". This routine is always available from the +/- key, no matter which menu page is showing. WARNING: whatever you EDIT gets turned into a string, so DONT edit lists such as IOPAR or PPAR that are needed by other programs or the operating system! Sorting such lists is also not advisable. right right-shift EDIT from the menu, or right-shift +/- shift from the keyboard, tries to invoke QED (the case EDIT must match) which must either be in the current directory of in the home directory. If that program is not found, then the HP's native editor is used instead. QED is not supplied with Roldx. Contact Rick Grevelle, 2300 Broadmoor #73, Bryan, Texas 77802 (409) 774-1169 for the latest version. I have tested Roldx with verson 2.01 of QED (GX version) ONLY. WARNING: If a program called "QED" is found in the current directory or above, it will be run, even if it is not the "QED" editor by Rick Grevelle. If this happens, the results could be disastrous. Therefore, DONT label any programs "QED" that are in the current Roldx directory or in the home directory. (The clever user could use this as a "back door" editor, but I dont support it). It's possible that you could have an entirely different program stored in a variable called QED. If you do, then make sure it's not in your home or current directory, as noted above. If you have a program called QED which is either of the following: << >> or << QED >> Roldx will go into an infinite loop and you will have to press on-C to rcover. If you exit QED by pressing left shift ENTER, or you exit the HP editor or stringwriter by pressing ON (cancel), or you entirely clear the current item, Roldx will NOT update the database with that item. Do NOT set up QED to leave a return code number on the stack, and DONT exit with keys that leave a return code. Doing so will exit the editor with the error message "EDITOR error" and leave the data unchanged. left left-shift EDIT from the menu, or left-shift +/- shift from the keyboard, tries to invoke stringwriter, EDIT which must be installed as a library, ID 1303. If that program is not found, then the HP's editor is used. Stringwriter is not supplied with Roldx. Contact Jean-Yves Avenard, 16 Rue de Savigny, 91390 Morsang sur Orge, France. email: avenar_j@epita.fr I have tested Roldx with verson 4.4 of stringwiter (GX version) ONLY. Stringwriter and QED are a powerful editors written in machine language. They can increase your editing speed tremendously, but they can also trash your ROLDX data if you're not careful. DO NOT REMOVE THE LIST OR STRING DELIMITERS WHEN EDITING if you don't want unpredictable results. Also, editing ANY item turns it into a list, so be careful if you're editing something that isn't a lists of lists to start with. WARNING: Neither stringwriter nor QED understand Roldx's data encryption format, so DON'T try to edit password protected items with them. If you do, you'll trash that item. PRINT print current item to the current printer. This routine is always available from the left-shift- print key, no matter which menu page is showing. DATA start the data base selection program. Roldx searches for all lists in the current directory. Move the selection bar to the list you want using the arrow keys. SORT sorts the selected list into alphabetical order (CASE IS IGNORED!) and then selects that list, returning to the main ROLDX program. See USORT below. NOTE: When the data selection program is exited using ON or backspace or the MAIN menu key, whatever list was highlighted becomes the current database - there is no "quit and don't save" mode. In addition to the menu keys above, the following key- presses are supported: ("with repeat" means you can hold down that key to scroll continuously): right-arrow, down-arrow next item, with repeat. up-arrow, left arrow previous item, with repeat. left-shift right-arrow, left-shift down-arrow next 7th (or 8th) item. left-shift left-arrow, left-shift up-arrow prev 7th (or 8th) item. right-shift right-arrow, right shift down-arrow go to last item. right-shift left-arrow right-shift up-arrow go to first (top) item. ENTER switch between "headings-only" and "full-screen" modes. right-shift OFF pauses program and turns the machine off, turning password protection (lock mode) back on in the process. (This is to prevent someone from accessing your password and data after the machine has been turned off and back on again, since you might forget that you have left the machine "unlocked". The 48 will beep when restarted, and resume the operation of Roldx. * Toggle the menu line on or off. / (The "division" key). Toggle between the small font and the large font, only affects full-screen mode. With this, you can view up to 10 lines of text if the menu line is off. To exit the program, press the backspace key, or the ON key, or EXIT from the main menu. The settings of user flags 32 through 39 are as follows. Use the STATUS menu key to enter status mode and change the settings. Note that the flags will only have effect if DBRDX is invoked (no rdPAR) or if ROLDX was invoked with an invalid or missing rdPAR. Otherwise, Roldx uses the flag settings saved in rdPAR: Flag 31 if clear, Roldx displays text in the medium (5x7) font. If set, it uses the small (3x5) font, in full-screen mode only. Flag 32 if clear, the menu line is displayed, plus (up to) 7 to 9 lines of text. If set, the menu line is not displayed, allowing 8 to 10 lines of text. Note: when entering text using Roldx's editor, you can only enter as many fields as you have selected using the LINE menu key in the status menu (see above) but only up to 10 lines will display. Flag 33 if clear, the FIND command searches from the current position in the list, if set, it searches from the beginning, which can be fairly slow for large databases. Note that only the line number in rdLINE is searched (searching all lines would be too slow - perhaps a future version will overcome this). The search mode used is sequential, rather than binary. BFIND ignores this flag. Flag 34 if clear, display all lines of each item (full-screen mode), if set, display only one line of each item (headings-only mode). Headings-only mode is useful for quickly scrolling through the file. With flag 34 set, the line disp- layed for each item is the value of rdLINE. Flag 35 temporary flag, set when in data program only. Flag 36 temporary flag internal to Roldx. Flag 37 used to toggle between 1st and 2nd main menu pages, clear at start-up for menu page one. Flag 38 alpha mode lower case when set, upper case when clear. Affects input of text. Flag 39 when clear, lock mode is on and individual items which are password protected will appear garbled. When set (this must be done from the status menu, and the password given), the items will be readable only if the password given was the correct one, otherwise they will appear garbled. Flag 40 set for QED edit, clear for stringwriter (not avail able to the user). Flag 41 clear for internal < sort, set for USORT (not avail. to the user). When Roldx is first started with an invalid or missing rdPAR (the rdPAR from previous versions will be invalid) it automatically scans the current directory for lists. If it doesn't find any, it will create a "List1". If you invoke Roldx from your HOME directory, or another directory contain- ing lists like IOPAR, PPAR, and others used by the operating system, you might inadvertantly alter them. For this reason, I recommend that you make a special directory to store your data, and use the following program to access it. You can store this program in your HOME directory, and call it something like Rldx (note lower case letters) to distinguish it from the ROLDX command: %%HP: T(3)A(D)F(.); \<< PATH \-> p \<< HOME mydir ROLDX p EVAL \>> \>> The above example switches to a directory named "mydir" (edit as needed) and, when done, switches back to the current directory. The following programs are supplied with Roldx and are accessible from the library menu: DBRDX, same as ROLDX, but takes the name of a database in level 2, and the starting position as a real number in level 1, and neither reads nor writes to rdPAR. If the name is not the name of a list, an error is generated. If the number is invalid, the program starts from the top. SortR, which is based on a program by Joe Horn, expects a list and sorts it into non-case-sensitive alpha order. NOTE: sortR does NOT decode password protected items when sorting, since this would slow it down to a crawl. If you sort a file with password protected items, they will all wind up at the beginning of the file. You can move them around with ->stk and stk-> as noted below. SortR will use a user-supplied sorting algorithm if one is found called USORT (case must match) in either the current or home directory. USORT must take exactly two arguments off the stack and leave one real number, 0 (false) or positive number (true). Failure to do this will default back to the internal sort. The following USORT is equivalent to the internal sort (but slightly slower): << < >>> To sort in ascending order, USORT could do this: << > >> You can experiment with more complicated methods, as long as your program can compare two strings and return a number for true or false. Coder, written by Simone Rapisarda, works as follows: Put a string to encode or decode in level 2, password string in level one, press CODER. If the string to decode is longer than the password, the password is repeatedly concatenated to itself until its length equals or exceeds the string. The two strings are then XOR'd, in system-RPL. Simple, but effective. Rcar does a recursive CAR on a list. In non-nerd terms, it gets only the first object in a list of list of list...etc. To use this outside of Roldx, go to the item that you want, press ->STK, exit Roldx. Now you have a list on the stack. Press rcar from Roldx library menu, and just the first object from that list will be on the stack. This is useful for setting alarms. Go to the time menu (or use the PIM of your choice), set your time and date, and then press EXEC to make the object on the stack (assuming its a string) the exec alarm. Note: from within Roldx, left-shift ->STK does an rcar on the current item. Upcase translates the letters a-z to A-Z. It ALWAYS converts the object to a string. rpar reads the library data in object rdPAR and converts it to a list with the form: { bint bint bint string name HXS }. The meaning of these is: { position_in_list line_number number_of_fields last_search_text database_name Roldx's_flags }. wpar writes the data back to the library data format for use by Roldx. WARNING: misuse of these utilities could crash your machine! These programs were created using Raymond Hellstern's LIB library builder/splitter. NOTE: The library ID (1765) is encoded in rdPAR, and therefore can't be changed by simply decompiling the library and editing $ROMID. If you need to have a different number, I'll send you a recompiled lib with the number of your choice (registered users only). You can edit each item outside of the ROLDX program by using ->STK, then edit it with the normal 48 object editor, then run ROLDX again and use STK->. If the stack does not contain a list, an error will be generated. To move an entry from within Roldx, execute ->STK, DEL, (move to the item you want it inserted before), then STK->. The data format makes it fairly easy to transfer data to a PC and edit it there - you must use ASCII mode to transfer it, with character trans- lation on number 3. As stated above, Roldx uses some "unsupported" entry points, but these have been tested up to rev M (GX) and work. For s-rpl gurus, here they are: 142A6 internal < for strings $ $ ---> %1|0% E4DE delete an item from a list {list} # ---> {list}' E461 insert an item {list} obj # ---> {list}' 539A0 set lower-case alpha mode Again, please, PLEASE, please remember to back up your data BEFORE using Roldx. James Weisbin 115 West Broadway, New York City, New York, 10013, U.S.A. email: 73457.3462@compuserve.com (James Weisbin) END_DOC BEGIN_RPL source code of nexch (exchange stack level 1 and n) %%HP: T(3)A(D)F(.); ":: CKN { LAM t_ } BIND LAM t_ UNROLL LAM t_ #1- ROLL ABND ;" END_RPL jsw@well.sf.ca.us (James Weisbin)