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)
