***********************************************************************
   
   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
 
