#######################
#### Start of File ####
#######################
----------------------------------------------------------------- 
File Name: readme.txt 
Contents: General information about this distribution.
----------------------------------------------------------------- 

TOPICS:
------- 
Overview
Copyright
History
Future
C++ Issues
Supported Platforms
Unzipping
DJGPP Compiler

OVERVIEW:
---------
The Variable Block Database (VBD) is a collection of C++ classes
used to build portable database applications.

Features:
 
- Built-in support for multi-user and single user access for both 
traditional and client/server applications. 

- Uses a 32-bit CRC checksum to ensure 99.9999% data integrity    
and offers both best-fit and first-fit allocation methods to
prevent fragmentation. 

- Database access methods include a B-tree with iterator and
memory caching, navigational access, fixed and variable-length
records. 

- Includes general-purpose data structures such as linked lists,
stacks, queues, balanced binary trees and others as well as a
variable length string class, a postscript driver, and HTML
driver.

- Ships with an advanced database recovery utility plus other
text and binary utilities.

- Built-in GUI support for wxWindows: versions 1.68B and 2.0.1
For more information about wxWindows, visit the wxWindows home 
site at: http://web.ukonline.co.uk/julian.smart/wxwin/ 

Example Programs:

Several example programs with makefiles for MSVC, HPUX C++,
DJGPP, and the GNU C++ compiler are provided to demonstrate each
of the concepts presented. Release 1031 has been built and tested
under Windows 95/98, MSDOS, HPUX 10.20, Solaris 2.4, and RedHat
Linux 5.2.

Documentation:

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. 

COPYRIGHT AND WARRANTY INFORMATION:
-----------------------------------
The VBD C++ classes are copyright (c) 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. 

HISTORY:
--------
The Variable Block Database and all of its sub-components were
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. Version 1031 
was completed and released in April of 1999.

FUTURE OF THE VARIABLE BLOCK DATABASE:
--------------------------------------
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
at:

Doug Gaer
11691 SW 17TH ST
Miami, FL 33165-2149

Phone: 305-229-4461
FAX: 305-553-1901

dgaer@email.com

ftp://ftp.nhc.noaa.gov/pub/doug 

http://www.webpost.net/dg/dgaer/

C++ ISSUES:
-----------
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 Microsoft Visual
C/C++. 

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 were 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. 

SUPPORTED PLATFORMS:
--------------------
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 and 5.0
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
RedHat Linux 5.2 - using GNU g++ version egcs-2.90.29

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

UNZIPPING THE DISTRIBUTION:
---------------------------
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. 

DJGPP COMPILER:
---------------
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/ 
----------------------------------------------------------------- 
#####################
#### End of File ####
#####################

 
