#######################
#### Start of File ####
#######################
----------------------------------------------------------------- 
File Name: strdb.txt 
Contents: Information about the general-purpose string database.
----------------------------------------------------------------- 

TOPICS:
-------
Overview
Customizing
User Interfaces
Compiling

OVERVIEW:
--------- 
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, Solaris 2.4, and RedHat Linux 5.2.

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:
------------
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:
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:
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
purposed. In order for the terminal interface to work under DOS
and Windows 95 the ANSI.SYS driver must be loaded. 

CUSTOMIZING THE 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:
----------
 
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
----------------------------------------------------------------- 
#####################
#### End of File ####
#####################
 
