General Information About This Distribution
|
Topics |
|
The Variable Block Database is a file format used to store any type of variable-length binary data in re-sizeable blocks. This distribution is a collection of C++ classes used to build portable database applications. Several example programs are provided to demonstrate each of the concepts presented. The example programs have been built and tested under Windows 95, MSDOS, HPUX, and Solaris.
All the documentation for the distribution is provided in an HTML format. The documentation covers the VBD C++ class library, the example programs, and the utility programs provided with this distribution. Parts of the documentation may be made available in other formats upon request. See the "docs/html/index.htm" file for a complete listing of all the help documents.
The VBD C++ classes are copyright © 1997, by Douglas M. Gaer. All those who put this code or its derivatives in a commercial product MUST mention this copyright in their documentation for users of the products in which this code or its derivative classes are used. Otherwise, you have the freedom to redistribute verbatim copies of this source code, adapt it to your specific needs, or improve the code and release your improvements to the public provided that the modified files carry prominent notices stating that you changed the files and the date of any change.
THIS SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. THE ENTIRE RISK OF THE QUALITY AND PERFORMANCE OF THIS SOFTWARE IS WITH YOU. SHOULD ANY ELEMENT OF THIS SOFTWARE PROVE DEFECTIVE, YOU WILL ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.
The Variable Block Database and all of its sub-components was developed out of the need for scalable database applications that were portable between PCs running Microsoft's Windows 95 and Hewlett Packard Workstations and Servers running HPUX (HP's version of UNIX .) In order to meet these requirements the file format and the source code had to remain consistent under both operating systems. In addition to the operating system, the file format and the source code had to work using both the PC's Intel x86 family of microprocessors and Hewlett Packard's PA-RISC family of microprocessors. The VBD project started in November of 1996 and was released to the public one year later. As of November 1998, a third release was completed and placed in the public domain.
The future of the Variable Block Database is highly dependent on its acceptance in the public domain. I developed the Variable Block Database as a sideline project with the hope that other developers would contribute to its success. My goal is to develop a truly portable library of C++ classes that can be used to build scalable database applications powerful enough to meet the needs of commercial applications. If you would like to make any contributions or if you have any suggestions please contact me by at:
Doug Gaer
11691 SW 17TH ST
Miami, FL 33165-2149
Phone: 305-229-4461
FAX: 305-553-1901
ftp://ftp.nhc.noaa.gov/pub/doug
Every component of the Variable Block Database was developed entirely in C++ and applies the object-oriented programming principles of abstraction, encapsulation, inheritance, and polymorphism. All the source code was originally written using Microsoft Visual C/C++ versions 1.52, 4.0, 4.1, and 4.2 and then ported to HPUX using HP CPP version 10.24. Additionally, the code was built and tested using the DJGPP C/C++ compiler version 2.7.2.1 and the GNU C/C++ compiler version 2.7.2.1.
Every C++ compiler has its own peculiarities, especially when implementing run time type information (RTTI), templates, and exception handling. RTTI allows the type of an object to be determined during program execution and can be used to find the actual type of an object without entering it. Templates allow the creation of generic functions and generic classes in which the type of data operated on is specified as a parameter. This allows you to use several different types of data without having to re-code specific versions for different data types. C++ includes its own error-handling routines called exception handling. Using C++ exception handling, a program can automatically invoke an error-handling routine when an error occurs.
RUN TIME TYPE INFORMATION:
RTTI was implemented under version 4.2 of Microsoft Visual C/C++ in order to perform several type casting operations and obtain type information. All of the RTTI features were removed because version 10.24 of the HPUX C++ compiler did not support RTTI. Also the type information was not consistent between version 2.7.2.1 of the GNU C/C++ compiler and version 4.2 of the Microsoft Visual C/C++ compiler.
TEMPLATES:
Templates are widely used, but can be omitted in the VBD core classes and Persistent Object Database Manager classes with the use of pre-processor directives. Any code that uses the VBD core classes and the POD manager can use the template version if needed or the non-template version if portability problems arise. Two versions were originally created because version 1.52 of Microsoft Visual C/C++ did not support templates. The General Purpose Data Structures provided with this distribution are only implemented as template classes. These classes are only used in some of the example programs and compiled with no portability issues on all the C++ compilers mentioned.
EXCEPTION HANDLING:
Two forms of exception handling was originally developed because version 1.52 of Microsoft Visual C/C++ did not support C++ exception handling. A global exception handler or C++ exception handling, denoted by the key words "try", "catch", and "throw", can be selected with the use of a pre-processor directive. In this distribution C++ exception handling has been omitted from all the example programs because of certain problems that arose while debugging the code. If a program error occurs during a file operation the global exception handler will flag you with an error message and terminate the program if necessary.
Variable Block Database files are designed to be portable between DOS, Windows 95, and UNIX systems. The VBD C++ class library and the example programs have been compiled and tested using the following platforms:
Windows 95 - using MSVC version 4.2
DOS - using DJGPP version 2.7.2.1
HPUX 10.20 - using HP CPP version 10.24
Solaris 2.4 - using GNU g++ version 2.7.2.1
Four different makefiles are provided in the source code directories to build the library examples and example programs:
msvc40.mak - for Microsoft Visual C/C++
djgpp.mak - for the DJGPP compiler
hpux10.mak - for the HPUX C++ compiler
gnu_gcc.mak - for the GNU C/C++ compiler
The entire distribution requires approximately 6 MB of free disk space to unzip. Two distributions are available, one for DOS/Windows 95 and one for UNIX. It was necessary to provide two separate packages to ensure that all the text files are formatted correctly under UNIX. In DOS and Windows 95 there are two file types: a text file and a binary file. A DOS text file uses a Carriage-Return/Line-Feed sequence to represent the end of a line in a text file and a Control-Z character to represent the end of a text file. In UNIX, a single Line-Feed represents the end of a line and the end of a text file. Also directory and file names are case sensitive on UNIX systems.
DOS and Windows 95:
To unzip this distribution you will need a copy of PKZIP version 2.03 for DOS or WINZIP version 6.1 or higher for Windows 95. To unzip using PKZIP 2.03 follow these instructions:
C:\>mkdir vbdbase C:\>copy vbdbase.zip c:\vbdbase C:\>cd vbdbase C:\vbdbase>pkunzip -d vbd1027.zip
UNIX:
To unzip this distribution you need a copy GZIP/GUNZIP version 1.2.4 or higher. To unzip using GZIP and the UNIX tar utility follow these instructions:
% gzip -d vbd1027.tgz % tar xvf vbd1027.tar
To unzip using GUNZIP and the UNIX tar utility follow these instructions:
% gunzip vbd1027.tgz % tar xvf vbd1027.tar
NOTE: You can use UNZIP for UNIX version 5.12 to unzip the DOS/Windows 95 distribution:
% mkdir vbdbase % cp vbd1027.zip vbdbase\vbd1027.zip % cd vbdbase % unzip -a -L vbd1027.zip
The unzip "-a" option will auto-convert any text files and the "-L" option will make the directory and file names all lower case.
In order to compile any of the VBD C++ source code you must set a path to your install directory using one of the VBD environment files located in the "env" sub directory. Edit the appropriate files according to the operating system/compiler used:
UNIX C++ Compilers:
To set the path to the VBD class library using any version of UNIX, edit the "vbd_unix.env" file using any text editor.
% vi vbd_unix.env # My Directory path for VBD Class Library VBDDIR = /apps/dbase/vbdbase
Microsoft Visual C/C++:
To set the path to the VBD class library using any version of Microsoft Visual C/C++, edit the "vbd_msvc.env" file using any text editor.
C:\vbdbase\env>edit vbd_msvc.env # My Directory path for VBD Class Library VBDDIR = c:\vbdbase
NOTE: You can set a path in your "autoexec.bat" file and then add that path to the "vbd_msvc.env" file:
C:\>edit autoexec.bat REM Path setting for VBD Database installation directory SET VBDPATH=C:\VBDBASE C:\>cd vbdbase\env C:\vbdbase\env>edit vbd_msvc.env # My Directory path for VBD Class Library VBDDIR = $(VBDPATH)
A portable windows based version of several example programs 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 10.24 and tested under HPUX 10.20 on series 700 workstations and series 800 servers.
In order to compile any of the wxWindows examples you must set a path to your install directory using one of the wxWindows environment files located in the "env" subdirectory. Edit the appropriate files according to the operating system/compiler used:
HPUX C++ Compiler:
To set the path for the wxWindows example programs using the HPUX C++ compiler, edit the "wx_unix.env" file using any text editor.
% vi wx_unix.env # My Directory path for wxWindows GUI Library WXDIR = /apps/wxwin
Microsoft Visual C/C++:
To set the path for the wxWindows example programs using the Microsoft Visual C/C++ compiler, edit the "wx_msvc.env" file using any text editor.
C:\vbdbase\env>edit wx_msvc.env # My Directory path for wxWindows GUI Library WXDIR = c:\wxwin
NOTE: You can set a path in your "autoexec.bat" file and then add that path to the "wx_msvc.env" file:
C:\>edit autoexec.bat REM Path setting for wxWindows installation directory SET WXWIN=C:\WXWIN C:\>cd vbdbase\env C:\vbdbase\env>edit wx_msvc.env # My Directory path for wxWindows GUI Library WXDIR = $(WXWIN)
All of the DOS based example programs have been built and tested using the "DJGPP" C++ compiler. DJGPP is a complete 32-bit C/C++ development system for Intel 80386 (and higher) PCs running DOS. It includes ports of many GNU development utilities. For more information on the DJGPP compiler, visit the DJGPP home site at: http://www.delorie.com/djgpp/
In order to compile any of the DJGPP examples you must set a path to your install directory using the DJGPP environment file located in the "env" subdirectory. Edit the "vbd_dj.env" file:
C:\vbdbase\env>emacs vbd_dj.env # My Directory path for VBD Class Library # NOTE: You must use UNIX-style slashes for djgpp make utility. VBDDIR = c:/vbdbase