11/07/90 DB48.DOC Copyright 1990 Ross Barnes This document is for: DB48 Version 2.01 Program size: 7513 bytes Checksum: #14939d Romid: 769 OVERVIEW -------- DB48 is a library containing a database system for the HP48SX. You can create any number of databases with one to ? fields in each database. Once a database is created you can add, view, modify, or delete records. The first record in a database CAN be edited but CANNOT be deleted. This record is used for the field names in the database. All records are alphabetized by the first field. You can find a record using the keyed first field or find a string anywhere in the database. You can scroll through the records or jump to the end or back to the beginning. Records can be copied to and from the stack. ** Databases must be in user memory. ** USAGE POLICY ------------ The DB48 library and its documentation are Copyright 1990 Ross Barnes, all rights reserved. DB48 is "shareware". The DB48 library and documentation may be distributed freely by individuals and BBS operators as long as the library and documentation (both unmodified) are provided TOGETHER. Individuals may use DB48 for two weeks. If DB48 is something you will continue to use then register it. The cost is $10 (cash or money order, no checks). See SUPPORT for registration benefits. Corporate or institutional use is prohibited. The sale of DB48 for profit, either alone or together with other software or hardware is prohibited. SUPPORT ------- General Support - All letters to the author will be answered. If you have a problem using the library send me a letter. If you decide not to register let me know why. A newer version of DB48 may be available to answer your complaints. Registered Support - In addition to the support above the registered users will be notified of bugs and bug fixes, as well as limited telephone support (my home number - available evenings and weekends). They will also be notified of the availability of new versions of DB48. Registered users can have the library id of DB48 changed if there is a conflict with another rom card or library. Registered users will receive priority for correspondence. Address all correspondence to the author: Ross Barnes 8412 N. Boone #104 Kansas City, MO 64155 DISCLAIMER ---------- The author shall not be liable for any damages, incidental or consequential, resulting from the use of DB48. PROCEDURE --------- 1. Transfer the library to your HP 48. 2. Recall the library object and store it to a RAM port (:p:x STO, where p is the port number (0, 1, or 2) and x is any number. You can now purge the original variable. 3. Turn the HP48 off, then on. This adds the library to the system table. Making sure you are in the root directory execute 769 ATTACH. 4. To start the program type DODB [ENTER]. 5. The program prompts you for a database name: New database name? .DB 6. Enter a name, e.g. TELE.DB [ENTER]. Do not use quotes around name. Using .DB as the extension will allow the program to detect databases in the current directory. 7. It prompts you for the number of fields: Number of fields? 8. Enter a number from 1 to ?. The first 5 fields can always be seen. Use [ENTER] or [left-shift][ENTER] to view any field. If 3 was entered the display will now have: FLD1 FLD2 FLD3 in the display. This is the first record in the database. This record contains the field names. It can be edited but not deleted. When the database is sorted this record will remain at the top. 9. At this time the database has been created. It contains one record. All database functions are active. To add new records press {ADD}. The functions of the database and the keys necessary to access them are described below. MENU KEYS --------- {USE} --Finds all the variables with .DB in the name, prompts for a database to use. Select a database and [ENTER]. {FIND} --Prompts for a fast find string and uses a binary search of the first field to find the record with a first field equal to or greater than the fast find string. The last fast find string is remembered for the current database. The first record in the database is not included in binary searches. [left-shift] { FIND } --Prompts for a slow find string and sequentially searches for the string throughout every field in every record starting at the current record plus one to the end of database. To search the entire database [right-shift][up-arrow] first to go to the top then [left-shift]{ FIND }. The search IS CASE SENSITIVE. Using only uppercase letters in the database is probably a good idea. If the string is found the record containing the string is displayed. If the string is not found the current record will be redisplayed. {EDIT} --Prompts for a field to edit while displaying all the fields as menu keys. Select a field and [ENTER]. You are prompted with the field name and a ?. The default input is the current field's value. Be sure to turn off alpha when using the edit menu or for the following menu. {right-shift}{ MENU } (last menu) will bring up a menu of common punctuation: [ ? ][ ! ][ @ ][ & ][ $ ][cents]. [left-shift] {EDIT} --Brings up the first field name prompt followed by a ?. The default input is the current field's value. All fields are prompted for in consecutive order. The other menus mentioned in {EDIT} are also available. {ADD} --Adds a record to the current database and then edits the record. [left-shift] {ADD} --A new list of menu keys are displayed. {+DB} --Creates a new database, prompting for the name and the number of fields in the new database. This database is now the current database. {+REC} --Adds a record to the current database and then edits the record. {+FLD} --Adds a new field to every record in the database. This field is appended to the end of the record and is empty except for record one which has "NEW FLD" as its value. {UP} --Returns to menu containing {ADD}. {DEL} --Prompts to delete current record. Select "Y" or "N" and [ENTER]. If "Y" is selected the current record will be deleted. [left-shift] {DEL} --A new list of menu keys are displayed. {-DB} --Prompts for a database to delete while displaying all databases in current directory as menu keys. Select a database and [ENTER]. Once a database is selected it is PURGED immediately. You cannot delete the current database. {-REC} --Prompts to delete current record. Select "Y" or "N" and [ENTER]. If "Y" is selected the current record will be deleted. {-FLD} --Prompts for a field to delete in current database while displaying all fields in current database as menu keys. Select a field and [ENTER]. The selected field will be deleted from all records. {UP} --Returns to menu containing {DEL}. {EXIT} --This exits the program. {ABOUT} --Version, author and copyright notice. [left-shift] {ABOUT} --Displays number of records in database, amount of RAM occupied by database and free RAM. {->STK} --Copies current record to top of stack. This can be used with {->DB} to copy a record from one database to another. [left-shift] {->STK} --Copies each field of current record to stack tagging them with field names. {->DB} --Add new record to database by copying record from top of stack. If record on stack contains more fields than current database the excess fields are deleted. If record on stack contains fewer fields than current database the extra fields are initialized to empty. [left-shift] {->DB} --Replaces current record with record on top of stack. {SORT} --Sorts current database using first field as key. This should not be necessary in normal circumstances. The program keeps the database sorted for you in most cases. If you have an unsorted database (you created on your own) this command will sort it for you. The sort is slow. Thirty seconds for thirty records. Use a PC to sort large databases (>50 records) unless you have lots of memory and time. Record one is never included in the sort since it contains the field names. OTHER KEYS ---------- [NXT] --Moves to next menu on current level. [ENTER] --Prompts for field to display of current record. Select a field [ENTER]. [left-shift] [ENTER] --Displays each field of current record. Press any key to display field. [up arrow] --Move up one record in current database. [left-shift] [up arrow] --Moves to the top of the database briefly displaying each record. Press any key (except ON) to stop. [right-shift] [up arrow] --Moves to top of current database. [down arrow] --Move down one record in current database. [left-shift] [down arrow] --Moves to the bottom of the database briefly displaying each record. Press any key (except ON) to stop. [right-shift] [down arrow] --Moves to bottom of current database. HELPFUL HINTS AND WARNINGS -------------------------- If you are "low" on free memory (1.25 times the size of the current database) certain operations ADD, DEL, EDIT, SORT, and ->DB will not be allowed because they would fail. This is to help prevent corruption of a database. Nothing can be tested for every circumstance so REMEMBER TO BACK UP YOUR DATABASES! Once you have created a database {EDIT} the first record and change the field names to something more meaningful. If you are asked for input [ENTER]ing an empty string will, in most cases, abort the action. An exception to this is a field EDIT or record ADD. If you are asked for input and there is a default value you can hit the [ON] key to clear the default input. Be careful not to press the [ON] key more than once or the program will be terminated. Always use a .DB for the database names so they will show up in the {USE} menu keys...unless you are trying to hide it. To copy a record from one database to another {->STK} to copy record from database to stack, {USE} the new database and {->DB} to copy the record from stack to database. ------------------------------------------------------------------------------- NOTE: The variable DBINFO is created if it does not already exist in the current directory. This variable contains a list consisting of the current active database in the current directory, the current record number and the last find string. If an error occurs when you try to run the program check the DBINFO variable and if invalid purge it and rerun the program. ------------------------------------------------------------------------------- RECOVERY HELP!!! ---------------- If the program crashes or you accidentally pressed the [ON] key and halted the program you may have corrupted the current database. RCL your database variable to the stack. If it only contains the first record (field names) then you will have to try to recover the records off the stack. Use [up arrow] key to examine the stack. Remove all non-record entries from the stack. Determine the number of records on the stack using DEPTH. Recreate the old database with ->LIST. Save it to the database variable. You should then execute [SORT] from inside DB48 to make certain the database is properly ordered. ** REMEMBER TO BACKUP YOUR DATABASES!! ** Version Info ------------ Version 2.01 - fixes a problem with garbage left on stack after entering "" for a [left-shift] {FIND} (slow find). Version 2.0 - major improvements over 1.0. Implemented sorted databases with binary search. The program was made into a library rather than run from a directory. Available memory is constantly monitored to prevent database operations from failing. Many other features were added or improved. Converting 1.0 databases to 2.0 is straightforward. The 2.0 databases are sorted, 1.0 databases are not. Use the following procedure to sort the 1.0 databases: Start DB48 Version 2.0. {USE} the version 1.0 database. Once the 1.0 database is the current database, press [NXT] and {SORT}. This will sort the old database on the first field. This sort is slow. Once the sort is completed you can use all the features of 2.0. Version 1.0 - the original program for the HP48. Searches were sequential. The program was in a directory in :0, :1, or :2. Few features.