# String Database Curses User Interface

Help Topics
Overview | Configuration File
Access Rights | Ins/Remove Menu
Find Menu | DisplayMenu
File Menu | Print Menu

Overview

All the string database programs share the same terminal interface under DOS and UNIX. See the String Database page for more information.

The string database terminal program provides the user with an easy to use menu driven interface consisting of one main menu and several sub-menus:

     ------- STRDB DATABASE PROGRAM'S MAIN MENU -------

     (0) - Exit this program
     (1) - Add, Remove, or Change items in the database
     (2) - Find items in the database
     (3) - Display items in the database
     (4) - File Operations
     (5) - Print Menu

     Press the number of your selection ->

Press 0 to exit program.

Press 1 to go to the insertion/removal menu.
Press 2 to find objects in the database.
Press 3 to display objects in the database.
Press 4 for the file operations menu.
Press 5 for the print options menu.

When the program is executed for the first time a new database file and index file will be created. The program will automatically open its associated data file and index file every time after that. An ASCII configuration file named in the "dbtcfg.hpp" file at compile time is used to point the program to the location of the database and establish user access rights.

The path to the configuration file can be set by an environmental variable, named in the "dbtcfg.hpp", if the configuration file resides in a different directory then the executable. Under UNIX a copy of the configuration file can be placed in each users directory to create a custom profile. If you want to specify a specific database when the program starts type the program's name followed by the name of the database with no file extension. This feature is useful for starting the program from within shell scripts or batch files: MyDbase mydbfile

Configuration File

The program's configuration file is used to load configurable parameters from a text file. When a new String Database application is created it is assigned a configuration template. The template file must be renamed to the name it was given in the "dbtcfg.hpp" file at compile time. You can use any text editor to modify the configuration file.

    #######################
    #### Start of File ####
    #######################
    # ---------------------------------------------------------------
    # User configuration file
    # ---------------------------------------------------------------
    # Set the path to this file in the environment or leave this file
    # in the program's working directory.

    # ===============================================================
    # Database file to open when application starts
    # ===============================================================
    # Do not use any file extensions when creating or opening file.
    # Both data and index will share the same name with different
    # file extensions. The data file will have a .pod extension and
    # the index file will have a .btx extension.
    # ===============================================================
    DBFileName=strdbx
    # ===============================================================

    # ===============================================================
    # Enable/Disable Admin user privileges
    # ===============================================================
    # Valid entries are FALSE the disable or TRUE to enable. If
    # enabled the user will be allowed to add, change, or delete
    # entries. Will default to FALSE if no valid entry is found.
    # ===============================================================
    AdminUser=TRUE
    # ===============================================================

    # PostScript Setup
    # ===============================================================
    # Maximum string length for each cell
    CellLength=19

    # Font size for the item bar and the cells
    FontSize=7

    # Page orientation: LANDSCAPE or PORTRAIT
    Orientation=LANDSCAPE

    # Paper size: LETTER, LEGAL, TABLOID, A3, or A4
    PaperSize=LETTER

    # Font types: COURIER, COURIER_BOLD, COURIER_OBLIQUE, or COURIER_BOLD_OBLIQUE
    ItemBarFont=COURIER_BOLD_OBLIQUE
    CellFont=COURIER
    # ===============================================================

    # ---------------------------------------------------------------
    #####################
    #### End of File ####
    #####################

The program will search for its configuration file in its working directory and then search the environment. If the program cannot find its configuration file or a configuration file does not exist, it will substitute the configurable parameters with default values set within the source code.

Access Rights

There are two levels of access for the database, administrative access and a general access. Access levels are configured in the program's configuration file. If an access level is not specified the program will default to general access.

General Access

:
General access grants you read-only privileges. You do not have the capability to modify the database with an add, change, delete, import, or merge operation. General access denies you the right to create new database files. If you try to create a new database with general access the program will flag you with a file creation exception and terminate.

Administrative Rights

:
Administrative access grants you read and write privileges. You will be allowed to modify the database, assuming that you have read and write privileges to the actual database files. If you give yourself ADMIN privileges and do not have read and write access to the database the program will terminate. ADMIN privileges dose not give you exclusive rights to the database.

Exclusive Rights

:
Exclusive rights, means that your instance of this program is the only one running. If more then one version of this application is using this database, either over the network or on the same computer, you do not have exclusive access to the database. Any modifications made to the database without exclusive rights will flag the other users with an access violation. An access violation means that the database has been modified and your version is no longer valid. If you receive an access violation, exit the program and restart it.

Insertion and Removal Menu

The insertion and removal menu is used to add, change, or remove items in the database. NOTE: You must have exclusive rights to the database to perform any of these operations. See the Access Rights section.

     --------- DATABASE INSERTION/REMOVAL MENU ---------

     (0) - Return to main menu
     (1) - Add items to the database
     (2) - Change an item in the database
     (3) - Remove an item from the database

     Press the number of your selection ->

Press 0 to return to the main menu.

Press 1 to add new objects to the database. The name of the object, entered in the first entry field, must be unique and can only be entered once. If the object already exists in the database the add function will flag you with an error. The database will support duplicate objects, but this feature was not implemented in this program.

Press 2 to change an object in the database (except the key member). If the object is found, it will be displayed with its key name disabled. You are allowed to change everything except the object's key name. The key name restriction is enforced to prevent duplicate names from appearing in the database. The database will support duplicate names, but this feature was not implemented in this program.

Press 3 to remove an object. When selected, you will be prompted to enter the object's key name. Enter the key name of the object you want to delete.

Find Menu

The Find menu is used to find objects in the database. A search can be performed on the object's key name or any of its associated fields.

     ---------- DATABASE QUERY MENU ----------

     (0) - Return to main menu

     Press the number of your selection ->

The number of selections in this menu will depend on the number of general purpose string members used, including the comment string.

Two types of searches can be performed, a plain search or a wild card search. A plain search is not case-sensitive, but requires you to enter the complete string. The plain search will find a single match if searching by key name or will find every match of the complete string if searching on any of the other entry fields. After a plain search or wildcard search, you will be given the option to display the object(s) that matched the string. If no matches are found, the program will alert you with a message stating that no matches were found.

A wildcard search is performed by entering the wildcard character "*" anywhere in the string. Wildcard searches are case sensitive, but only require you to enter a piece of the string. The wild card search will find every occurrence of the string in the specified field.

Display Menu

     ---------- DATABASE DISPLAY MENU ----------

     (0) - Return to main menu
     (1) - Display all items line by line
     (2) - Display all items one a time

     Press the number of your selection ->

Press 0 to return to the main menu.

Press 1 to display all the objects in the database on the screen line by line. The line by line display will only display the key member and the next four general-purpose members. This is done to limit the output to an 80-column display.

Press 2 to display each object in the database one by one.

File Menu

      ---------- DATABASE FILE OPERATIONS MENU ----------

     (0) - Return to main menu
     (1) - Display Variable Block Database statistics
     (2) - Export to ASCII file (delimited by tabs)
     (3) - Import ASCII file (delimited by tabs)
     (4) - Backup the database to another file
     (5) - Merge the contents of another database file
     (6) - Create a template for an import file
     (7) - Compare the index file to the data file
     (8) - Rebuild the index file

     Press the number of your selection ->

Press 0 to return to the main menu.

Press 1 to display VBD file statistics for the data file and the index file. This information is used to analyze and troubleshoot VBD files. File statistics for both the data file and the index file will be displayed

Press 2 to export the entire database to a text file delimited by tabs. Exported text files can be imported into other applications such as Microsoft Excel

Press 3 to import a text file. The import file must contain the correct number of strings per line, according to the format specified by the Export menu option or the Create Template menu option. NOTE: You must have exclusive rights to the database to perform an import operation. See the Access Rights section. The import function parses the text file line by line searching for text strings separated by tabs. If there is not enough strings on a line to complete an entry, the import function will flag you with an error and skip this entry. If an entry is already in the database, the import function will give you the option to update this entry, skip this entry, or update this entry and all others without prompting. After completion, the import function will report the number of new items that were imported and the number of items that were updated.

Press 4 to copy the entire database to another database file of the same type. NOTE: Since the index file can always be rebuilt by selecting the Rebuild Index File menu option, only the data file will be copied. Backup copies of the database should be made regularly in case of disk failures or file corruption.

Press 5 to merge the contents of another database file of the same type. Merges are used to update the database when other copies of it exist on other systems, such as laptop computers. NOTE: You must have exclusive rights to the database to perform a merge operation. See the Access Rights section. The merge function checks each variable block header for the correct class identification numbers before importing a new object. Class identification numbers vary with each version of the string database. This ensures that no objects from another VBD file will be imported into this database. If an object with correct class ID is already in the database, the merge function will give you the option to update this entry, skip this entry, or update this entry and all others without prompting. After completion, the merge function will report the number of new objects that were imported and the number of objects that were updated.

Press 6 to create a template file text files suitable for import. When the file is imported, the template information is discarded.

Press 7 to compare each object in the data file with its entry key in the index file. Index files are used to locate objects in the data file by associating each object's entry key with a file address. Each new object added to the database is assigned a unique key name. The key name and the object's file address is then stored in the index file. If all the objects in the data file do not have valid key entries in the index file, either the index file or the data file could be corrupt. If the compare index file function still fails after the index file is rebuilt and installed, the data file is corrupt. A corrupt data file can be restored from a backup copy or rebuilt with the VBD file Debug Utility.

Press 8 to rebuild the index file. Each index file is unique and can only be rebuilt by the application that created it. For more information see the POD manger and the Persistent base class.

NOTE

: The rebuild function will not allow you to overwrite the existing index file, even though it no longer contains valid entry keys. After the index file is rebuilt, you have to exit the program and copy the new index file over the existing one:

    C:>copy c:\temp\new_file.btx u:\db_files\mydbase\mydbase.btx (under Windows 95)
    % cp /tmp/new_file.btx /dbase/db_files/mydbase/mydbase.btx (under UNIX)

Print Menu

      ---------- DATABASE PRINTING MENU ----------

      (0) - Return to main menu
      (1) - Print to text file (abbreviated, 80 cols)
      (2) - Print to text file (full listing, 132 cols)
      (3) - Print a single object to a text file
      (4) - Print to PostScript file

      Press the number of your selection ->

Press 0 to return to the main menu.

Press 1 to print the entire database to a text file suitable for printing on 8 1/2 by 11 paper. Only the key member and the next four general-purpose members will be printed in order to maintain an 80-column printout.

Press 2 to print the entire database to a text file with all the data members printed except the comment string. The comment string is omitted maintain a 132 column printed.

Press 3 to print a single object to a text file.

Press 4 to print the database to a PostScript file. All the PostScript printing parameters are loaded from the program's configuration file each time a document is printed. The PostScript file must be manually sent to a PostScript printer after it is created:

    C:>type c:\temp\mydbase.ps > LPT1 (under Windows 95)
    % lp -d hplj mydbase.ps (under SYSV UNIX)

End Of Document