General Purpose String Database

Overview of the String Database

This is a general-purpose object-oriented string database, based on VBD technology. It is used to represent one unique key member, up to 7 general-purpose string members, and one comment string. All the string members can grow and shrink as needed. The C++ code is a template that can be used to create specialized database applications portable between DOS and UNIX systems. This code has been compiled and tested under DOS, Windows 95, HPUX 10.20, and Solaris 2.4.

When a database file is created the binary file itself is platform independent. Different types of machines running the same version of the application compiled for that platform can access the file. This allows a single database to be distributed across the network. For example: if the main database file resides on an UNIX server, then a PC client or another UNIX work station can NFS mount the directory where the database resides and use the same database.

All of the string objects created by the StrDB classes are managed by the Persistent Object Database manager and the Persistent base class. Files created by the POD manager are given a ".pod" extension to allow the user to identify them as POD data files. Index files created by the POD manager are given a ".btx" extension to allow the user to identify them as B-tree index files. An index file is a VBD file used to store the address where the object's data can be found in the data file. Index files were implemented to increase the speed of search operations.

Any files created directly with the VBD file manager are usually given a ".vbd" file extension. The POD manager and the Persistent base class gives persistent objects the ability to store complex types, pointers, and references. The VBD file manager used alone is not limited to object-oriented databases. It can be used to store any type of variable length binary data. However, files created using either the POD manager or the VBD file manager will maintain the same file structure and be identified by the same signature stored in the file header.

Customizing the string database for specific applications

All the components of the String Database are located in the "strdb" subdirectory. Any changes the C++ source code files or makefiles located here will effect all the String Database applications. The "template" subdirectory contains a template directory that can be used to create new applications. To create a new String Database application copy the contents of the "template" directory to another directory named after the application:

xcopy /e/s template MyDbase (for DOS or Windows)
cp -r template MyDbase (for UNIX)

The "MyDbase" directory will contain all the necessary files needed to build a new application:

bin      - Binary directory for the program executables.
config   - DB configuration used to customize before compiling.
curses   - Makefiles for the Curses version.
db_files - Default location for the data file and the index file.
wx168b    - Makefiles for the wxWindows version.

To customize the application, enter the "config" directory and modify the following files:

- Modify "dbconfig.hpp" file to customize the database
- Modify "dbvers.hpp" file to uniquely identify the database
- Modify "dbtcfg.hpp" file to customize the user interface

The "dbconfig.hpp" file is used to label the data members of the StrDB class. The key member is a unique string used to identify each item in the database. It must always be set in the "dbconfig.hpp file. The general-purpose members can represent any other information that is associated with the key member. The comment string is provided to allow the user to enter a detailed description of the key member and its associated general-purpose members. If all the general-purpose members are not used, including the comment string, then space for the unused members will still be allocated in the database. This allows them to be used in the future by modifying the "dbconfig.hpp" file and recompiling the program.

The string members, including the key member, are implemented as a concrete data type by the StrDB class (see the "strdb.hpp" and "strdb.cpp" files.) The StrDB class is used to create individual objects made up of all the sting members. These objects are then stored to disk by the methods defined in the Persistent base class. A unique class identification number is stored with each object. The class ID must be modified in the "dbvers.hpp" file to uniquely identify this version of the string database objects. This will prevent other string database applications using this template from being merged or opened with this version of the string database program.

User interfaces

wxWindows Version:
For detailed instructions on using the wxWindows program, see the wxWindows User Interface page.

A portable windows based version was developed for Windows 95 and Motif using the "wxWindows" GUI library, version 1.68B. For more information on wxWindows, visit the wxWindows Home Site at: http://web.ukonline.co.uk/julian.smart/wxwin/. The Windows 95 version was built with Microsoft Visual C/C++ version 4.2 and tested under Windows 95A, Windows 95B, and Windows NT workstation version 4.0. The Motif version was built with HPUX C++ version A.10.24 and tested under HPUX 10.20 on series 700 workstations and series 800 servers.

Curses Version:
For detailed instruction on using the Curses program, see the Curses User Interface page.

The curses version was developed for use with UNIX systems to access the database via telnet sessions. It was built with the Independent Terminal Type class and ported to DOS for testing purposes. In order for the terminal interface to work under DOS and Windows 95 the ANSI.SYS driver must be loaded.

Customizing User Interface Programs:
The "dbtcfg.hpp" is used to customize both the curses and the WxWindows user interfaces. The program name is set here, along with the default file names for the database and the program configuration file.

Compiling the applications

Curses Version:
Four makefiles are provided in the "curses" directory to compile the source code on one of four different compilers:

"msvc40.mak"  - Makefile for Microsoft visual C/C++ 4.2
"djgpp.mak"   - Makefile for DJGPP gcc 2.7.2.1 
"gnu_gcc.mak" - Makefile for GNU g++ 2.7.2.1 and egcs-2.90.29
"hpux10.mak"  - Makefile for HPUX C++ A.10.24  

wxWindows Version:
Two makefiles are provided in the "wx168b" directory to compile the source code with wxWindows version 1.68B on one of two different compilers:

"msvc40.mak"  - Makefile for Microsoft visual C/C++ 4.2
"hpux10.mak"  - Makefile for HPUX C++ A.10.24  

Building the Executable:
Before compiling the application change the PROJECT macro, in the makefile, to set the name of the executable. To compile use the "make -f" option followed by the makefile name. To compile using MSVC use the "nmake -f" option. The resulting executable will be named after the name set by the PROJECT macro in the makefile. Use the following examples to compile the curses version using the make utility:

make VBDDIR=/apps/database/vbdbase -f hpux10.mak
make VBDDIR=/apps/database/vbdbase -f gnu_gcc.mak
make VBDDIR=D:/vbdbase -f djgpp.mak
nmake VBDDIR=D:\vbdbase -f msvc40.mak

Use the following examples to compile the wxWindows version using the make utility:

make VBDDIR=/apps/database/vbdbase WXWIN=/apps/wxwin -f hpux10.mak
nmake VBDDIR=D:\vbdbase WXWIN=C:\wx -f msvc40.mak

The VBDDIR variable points the installation path of the VBD distribution and the WXWIN variable points to the wxWindows library installation path. NOTE: The DJGPP compiler requires the use of UNIX style path separators.

Installing and Configuring:
Execute a "make -f (makefile name) install" to move the executable to the "bin" directory and a "make -f (makefile name) config" to move a configuration file template to the "bin" directory. Rename the configuration file to the file name you specified in the "dbtcfg.hpp" and edit accordingly. You can set a path to the configuration file by setting the environmental variable named in the "dbtcfg.hpp" file so the executable can find it outside of the bin directory. Under UNIX a copy of the configuration file can be placed in each users directory to create a custom profile. The program uses its configuration file to find its default database, set the user access rights, and set various printing options. A command line argument can be used to specify the path to the database file by passing the file name to the program before executing it.

Removing the Object Files and the Executable:
To remove the object files and the executable use the "make -f" option followed by the makefile name, followed by "clean": make -f hpux10.mak clean

Under MSVC use the "nmake -f" option followed by the makefile name, followed by "clean": nmake -f msvc40.mak clean