TBinaryDataSet Documentation
============================
The tBinaryDataSet component was created out of the need to have a tDataSet
decendant which accessed a data file without requiring numerous DLL's or
the Borland Database Engine.  With the new features in Borland Delphi 3.0,
creating a tDataSet descendant has proven to be much easier than first imagined.
The unit BinData.pas contains the implementation of just such a component.

LEGAL DISCLAMER
---------------
Copyright (C) 1998 by Steven R. Kamradt (skamradt@mediaone.net)

This software is provided 'as-is', without any express or implied warranty.
In no event will the author be held liable for any damages arising from the use
of this software.

Permission is granted to anyone to use this software for any purpose, including
commercial applications, and to alter it and redistribute it freely, subject to
the following restrictions:

1. The origin of this software must not be misrepresented, you must not claim
that you wrote the original software. If you use this software in a product, an
acknowledgment in the product documentation would be appreciated but is not
required.

2. Altered source versions must be plainly marked as such, and must not be
misrepresented as being the original software.

3. This notice may not be removed or altered from any source distribution.

FILES
-----
BINDATA.TXT          This document
BINDATA.PAS          Source code for the tBinaryDataSet component
BINDATA.DCR          the component toolbar icon resource


BINDATAEX.DPR       \
BINDATAEX.RES       |An example program which shows how to dynamically create
EXMAIN.PAS          |a tBinaryDataSet at runtime.
EXMAIN.DFM          /

INSTALLATION
------------
Installation of the component is as simple as extracting the source files into a
directory of the users choice and then selecting the "Component" | "Install
Component" menu option from the Borland Delphi IDE.  Locate the file BINDATA.PAS
and select OK.

USAGE
-----
Using the tBinaryDataSet component is quite simple.  Just drop the component on
a form or datamodule.  Right click on the component and select Field Editor to
add fields to your datafile.   Just about any data aware control will work with
a tBinaryDataSet component (minus any controls which work with yet unsupported
field types such as memos and blobs).

To create a new datafile, you must call the CreateTable method.  An example of
creation follows:

Procedure MakeMyTable;
BEGIN
  tBinaryDataSet1.TableName := 'MYTABLE.DAT';
  tBinaryDataSet1.CreateTable;
END;

A method which I have used in several of my test applications is as follows:

Procedure OpenMyTable;
// Open MYTABLE.DAT, create the table if it doesn't exist.
BEGIN
  tBinaryDataSet1.TableName := 'MYTABLE.DAT';
  TRY
    tBinaryDataSet1.Open;
  EXCEPT
    tBinaryDataSet1.CreateTable;
    tBinaryDataSet1.Open;
  END;
END;

The component will mark records as deleted as deletes are made.  At this time,
these marked records are NOT re-used.  To clean up the data file, the programmer
must call the PackTable method.  This routine will eliminate all records which
have been deleted.  For example:

Procedure Form1.PackMyTable;
BEGIN
  // the table must be closed first
  if tBinaryDataSet1.Active then
    tBInaryDataSet1.Close;
  tBinaryDataSet1.PackTable;
END;

The ability to sort records was a requirement for one of my applications.  This
task can be done easily by calling the SortTable method.  The sort table method
accepts a parameter list of the field names of which to sort by.  For example,
to sort a table by lastname-firstname, the following code would be used:

Procedure Form1.SortLastnameFirstname;
BEGIN
  tBinaryDataSet1.SortTable(['Lastname','Firstname']);
END;

To test the SortTable method, a method UnsortTable was added.  This method does
nothing more than randomly distribute the records within a table.

HISTORY
-------
 version 0.9 - 01/19/98 : Initial version, merged Danie Gavarin's code with
                          the Marco's code from tDdhObjectDataSet.
                        : Modified header to support a record deletion
                          chain. It does not reuse deleted records, yet. :)
               01/20/98 : Corrected bug which disallowed the use of tDbCheckbox
                          components.
                        : Added PackTable method to remove deleted records
                          from the dataset datafile.
               02/03/98 : ReadOnly property now available which will open
                          the table in readonly mode.
               02/26/98 : Added SortTable method to sort the table. Also
                          added an UnSortTable method to randomly distribute
                          records to test/benchmark the sorting algorithms.
               02/27/98 : Changed SortTable method to use QuickSort sorting
                          algorithm for increased performance.
               03/09/98 : Added documentation file BINDATA.TXT and prepared
                          for public release.
 version 0.91- 04/20/98 : Thanks to Shin Yang, and Tom White who pointed out a 
                          bug in the CreateTable method.  A working fix has been 
                          made, however it is important to note that when 
                          dynamicaly creating tables, you MUST use a fresh 
                          instance of tBinaryDataSet.  The reasons for this are 
                          not clear, but it seems to be a bug in the tDataSet 
                          object. See the example in Exmain.pas.


WISH LIST
---------
The following features are planed for future versions of this component to be
added as time allows:

      * Add the ability to perform a Locate and Lookup on a SORTED dataset.
      * When adding new records, re-use the deleted records first.
      * CloneStructure method to create an empty table based on an existing
        table.
      * ZapTable method to remove all records, but maintain the existing
        structure.

SUPPORT
-------
This component has been released as FREEWARE with source.  If you encounter any
bugs or limitations with this component, I would like to hear from you. Bug
fixes will be released based on their severity and impact on my existing work
schedule.  I can be contacted at skamradt@mediaone.net and the latest versions
of this component will be posted at:

      http://www.geocities.com/SiliconValley/Way/3604/index.html

Many thanks to the following delphi programmers who have made this control
possible:

      Marco Cantu [Author of "Delphi Developers Handbook"]
      Tony BenBrahim [http://www.neosoft.com/~startech/week1/customds1.htm]
      Daniel Gavarin [news:borland.public.delphi.vcl.components.writing]
      Peter Szymiczek [UNDU #8, QSort algorithm]

Many thanks to the following Delphi programmers who have assisted in the beta
test phase of this component:

      Shin Yang [mailto:Shin_Yang@notes.ymp.gov]
      Tom White [mailto:twhite@perfectdesign.com]

