*********************************************************************** Databases and database directories created by previous versions are completely compatible with this new version. Caution: If you use a previous version of dBase after using this new version, the old version may crash. The new version modifies a hidden variable called DBINFO in the database directory. Note that this software creates a directory in your hidden directory. # 15781h SYSEVAL should get you into the hidden directory -- Careless use of SYSEVAL may corrupt memory. Subject: Database Application for HP48 S/SX/G/GX (DBASE), Version 3.1 Author: Todd Eckrich ( mte@delphi.com ) BYTES: # DAD7h, 9073 VERSION HISTORY 1.1 Sped up the full-screen display of individual records. The medium-fonts for the HP48G Series are not hidden, as in the HP48SX Series, allowing for very fast text display. 2.0 Wrote new title browser into library ( previously used internal browser that EQNLIB uses ). Defined null-named local variables instead of explicitly named variables. Better management of the return stack for cleaner exit. Fully supported calling from within the command line and, upon exit, returning to the original command line. Allowed cancellation of record adding and editing from input prompt. Marked stack prior to input prompts for data input so that the interactive stack would be more usable and reliable. Wrote machine code search routines. Allowed searches of all databases. Replaced ABOUT command. 3.0 Added machine code sort routine to sort database records on selected field. Moved selection of field shown for records browser from menu to left and right-arrow keys. Reorganized find utilities and added next feature (instead of prompting for search string every time). Added feature to place database and its global name onto the stack. Added command to take list and global from stack and store as database, testing list. Made compatible to the S series. Added option to select String Writer or other user-specified editor for records. Added feature to add or delete fields. 3.1 Added external commands to search database, recall database names, and recall database. The following are prominent features of this database application: * Written in System RPL and Machine Language. * Allows multiple databases with variable numbers of fields. * High-speed browser to browse database names and records (by any field). * Records exceeding the display boundaries can be scrolled. * Case-insensitive string searches of current or all databases. * Linefeeds in strings split text into separate display rows. * Repeat key features. * Sorts database records by selected field using ml sort routine. * Databases accessible from any directory. * Allows using String Writer or other editor for records. * Commands available to be used in programs to access databases. * Fully supports calling from within the command line and, upon exit, returning to the original command line. OVERVIEW Each database consists of a number of records. Each record contains a number of fields. The physical structure of each database is a list of list(s) of string(s). The databases are stored in the hidden directory (#640BEh SYSEVAL to enter -- caution: careless use of SYSEVAL may corrupt memory). As depicted below, there are three main environments. The arrows indicate the access paths between the different environments. Record Viewer <---> Records Browser <---> Database Browser Record Viewer: -Displays one record at a time. Each field is displayed starting on a new row. If a field contains linefeed characters, then the next character after the linefeed is displayed on a new row. If the record displayed extends beyond the display boundaries, then the display can be scrolled to view the entire record. Records can be searched, pushed to the stack, copied, added, deleted, and edited. Record Browser (Title Browser): -Browses records by any field. Records can be searched, added, deleted, edited, and sorted. Database Browser: -Browses database names. Databases can be added, deleted, renamed, pushed to the stack, and have fields added or deleted. INSTALLATION To install the DBASE library, follow the instructions for an auto- attaching library in the HP User's Guide. As always, backup memory before using. DBASE can be called from within the command line if in a user menu or assigned to a user key in the System RPL form :: TakeOver DBASE ;. INSTALL.REF Use INSTALL.REF to install eight sample databases including: Airlines, Hotels, and Rental_Cars which contain various 800 numbers. INSTALL.REF can be used when other databases have already been created by this version of DBASE or previous versions. MOVING BETWEEN ENVIRONMENTS The following shows the keys used to move between the main three environments: Record_Viewer <-ENTER-> Records_Browser <-ENTER Database_Browser DB-> DEFINING A DATABASE If no database exists or the user chooses to add a new database, the user will be prompted to define a new database name (such as Phone_Personal, To_Do...) and then specify the number of fields in each record. The user is then prompted to name the fields of each record (such as Name, Phone, Misc,...). The field names are stored as the first record in each database. This first record describing the fields cannot be deleted or sorted but can be edited. A database name can be any sequence of characters. Thus, permissible database names can start with a number or contain spaces. Database names cannot be null, but fields can be. SEARCHING RECORDS AND DATABASES NAMES There are two types of searches: Alpha Search: Case-sensitive search by first character of first field of database records. Press "alpha" key and then unshifted or shifted key for any valid character (including lower-case letters, numbers, and special characters). Search starts at first data entry. In record browser or viewer, searches current database for record starting with specified character. In database browser, searches for database name starting with specified character. String Search: Case-insensitive search by string of one to fifteen characters. LOCAL searches the current database starting at the next record. GLOBAL searches the current database and following databases starting at the next record. An search string of upper-case characters will match both upper and lower-case characters. The first records (field names) of databases are not searched. EDITING AND ADDING RECORDS WITH INTERNAL HP48 EDITOR When using the internal editor if the command line contains any characters, pressing the "ON" key erases the contents of command line. If the command line contains no characters, then pressing the "ON" key cancels the edit or add procedure. If a character string from the stack is placed into an empty command line, the leading quotation mark and trailing quotation mark and space will automatically be stripped when entered. CONFIGURING DBASE FOR RECORDS EDITOR To select the editor used for editing records, select CFG from the database browser menu. Three options are given: the Internal HP48 Editor, String Writer, or a User Specified Editor. Highlight the desired option and press ENTER. If the user-specified option is selected, then the user is prompted to enter the name of an editor. The name can be a global name or a library command. If the specified editor is not found, then the internal HP48 editor is used. Specifying something other than an editor may crash system. LIBRARY COMMANDS These commands can be used in programs to access and manipulate the database information. These commands are available from the DBASE library menu. DBASE ( -> ) Starts database environment. DBfind ( 'global_dBase_name' "search_string" %start_position -> %found_position ) Does a non-casesensitive search of dBase database specified by global name. Returns a real number indicating found position or zero if match not found. DBnames ( -> { globals_of_dBase_database_names } ) Returns list of all dBase database names. DBrcl ( 'global_dBase_name' -> { database } ) Recalls database list from dBase database name. DBsto ( { } 'global' -> ) Stores list as a dBase database if the list is a valid list of list(s) of string(s). The global name becomes the database name. WARNINGS As always, backup memory before using. I take no responsibility for any damage resulting from use of this library. Do not alter the contents of the database directory outside of dBase (do not purge variables in the database directory outside of DBASE). RECORD BROWSER ENVIRONMENT KEYS When the browser is active to view the records in a database, the keyboard is defined as follows: 11.1 FIND-> See SEARCHING RECORDS AND DATABASES NAMES. 12.1 DB Starts database browser highlighting the current database. 13.1 SORT Sorts records by selected field. Highlight field on which to sort and then press ENTER. 14.1 ADD Adds record. 15.1 DEL Deletes highlighted record. 16.1 EDIT Edits highlighted record. 24.1 VAR Displays previous or first page of records. 25.1 UPARROW Highlights previous or first record. 25.3 Highlights first record. (right-shifted UPARROW) 26.1 NXT Displays next or last page of records. 34.1 LEFTARROW Displays previous field (wraps to last field). 35.1 DOWNARROW Highlights next or last record. 35.3 Highlights last record. (right-shifted DOWNARROW) 36.1 RIGHTARROW Displays next field (wraps to first field). 51.1 ENTER Views highlighted record in record-viewer mode. 61.1 ALPHA See SEARCHING RECORDS AND DATABASES NAMES. 91.1 CANCEL Exits. 93.1 Turns calculator off. RECORD VIEWER ENVIRONMENT KEYS When a record is being viewed in the full-screen mode, the keyboard is defined as follows: 11.1 FIND-> See SEARCHING RECORDS AND DATABASES NAMES. 12.1 STK-> Places fields of record onto stack. 13.1 COPY Creates duplicate of current record. 14.1 ADD Adds record. 15.1 DEL Deletes current record. 16.1 EDIT Edits current record. 25.1 UPARROW Advances to previous record. 25.3 Advances to top record. (right-shifted UPARROW) 35.1 DOWNARROW Advances to next record. 35.3 Advances to last record. (right-shifted DOWNARROW) 51.1 ENTER Starts Record Browser mode highlighting the current record. 61.1 ALPHA See SEARCHING RECORDS AND DATABASES NAMES. 91.1 CANCEL Exits. 93.1 Turns calculator off. If the current record exceeds the display boundaries, 24.1 VAR Scrolls display up 24.3 Jumps to top of display 26.1 NXT Scrolls display down 26.3 Jumps to bottom of display 34.1 LEFTARROW Scrolls display left 34.3 Jumps to left edge of display 36.1 RIGHTARROW Scrolls display right. 36.3 Jumps to right edge of display DATABASE BROWSER ENVIRONMENT KEYS When the browser is active to view the database names, the keyboard is defined as follows: 11.1 CFG Selects editor for records. See CONFIGURING DBASE FOR RECORDS EDITOR. 12.1 FLDS Add or delete fields from specified database. Pressing key displays fields of highlighted database. Menu options allow user to add or delete fields of current database. 13.1 ADD Adds database. 14.1 DEL Deletes database. 15.1 REN Renames Database. 16.1 STK-> Places current database and its name onto stack. 24.1 VAR Displays previous or first page of databases. 25.1 UPARROW Highlights previous or first database. 25.3 Highlights first database. (right-shifted UPARROW) 26.1 NXT Displays next or last page of databases. 35.1 DOWNARROW Highlights next or last database. 35.3 Highlights last database. (right-shifted DOWNARROW) 51.1 ENTER Starts record browser using highlighted database. 61.1 ALPHA See SEARCHING RECORDS AND DATABASES NAMES. 91.1 CANCEL Exits. 91.3 Turns calculator off. CREDITS * Thanks to Rick Grevelle for MDISPN and MLVARS. * Thanks to Mika Heiskanen for Sorted Entries and MLDL Version 2.0. * Thanks to Joe Horn for SORTLS. * Thanks to Detlef Mueller & Raymond Hellstern for RPL48 Toolkit. * Thanks to Scotty Thompson for SEDITR. * Thanks to Jan Brittenson for MLDL Version 1.0 and STAR. * Thanks to all the users and beta testers for their suggestions. Todd Eckrich ( mte@delphi.com ) 1428 Oaklanding Road Mount Pleasant, SC 29464 803 881-8781