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

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

OVERVIEW:
---------
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.

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. As of November
1998, a third release was completed and placed in the public
domain. 

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 

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

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. 

INSTALLATION INSTRUCTIONS:
--------------------------
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)

wxWINDOWS INTERFACE:
--------------------
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)

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/ 

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

 
