===============================================================================
  Objective C database library - classes to provide access to DBase III files
===============================================================================

1. Introduction:
===============

This document describes a very simple database library to provide access to
DBase III files. At the moment only methods to read and write records are
provided.

Don't use this library at all. It has been only included with the OS/2 PM
library for demonstration purpose. All classes and methods are subject to
change.

Here only the classes and methods used in one of the demonstration programs
for the PM library are described.

Future releases will accompany the PM library and provide a better support for
all existing DBase III data types. Index files (BTree and maybe Hash) will
be supported.

The version number of this library is 0.3

2. Classes:
==========

The following classes are documented:

	*	DBFile		class for access to DBase data files
	*	DBField		record data is stored in one or more fields
	*	DBList		a list of records
	*	DBRecord	a storage buffer to a record used in DBList

Before using any of the classes include <db/db.h>. This file includes all
necessary Objective C Interface Files for the database classes.

2.1 DBFile:
----------

Every DBase data file used is represented by an instance of DBFile.


Methods:
	- init: (char *) fileName
		This function opens an existing DBase III data file and
		generates the field structure in memory.

	- free
		'free' closes the file and frees the field structure allocated
		by 'init:'.

	- field: (int) fieldNumber
		'field:' returns a pointer to an object of type DBField
		(or one of its subclasses) associated with the data field
		'fieldNumber'. The first data field has number 0.

	- readRecord: (long) offset
		Read the record specified by 'offset'. The first record
		has number 0.

	- append
		Append a record to the data file. Data to store can be set
		via the methods of DBField.

	- replace
		Replace the current record with the information stored in
		the instances of DBField.

	- delete
		Delete the current record.

	- clear
		Clear the data stored in the DBFields. This should always
		be done before storing new data in the DBFields.

2.2 DBField:
-----------

Each of the data fields is represented by an instance of DBField or one
of its subclasses. These objects are created by 'init:' of DBFile.


Methods:
	- setString: (char *) aString
		This method stores 'aString' as the data of the DBField.
		This method does not change the data file on disk.

	- (char *) string
		'string' returns a pointer to the stored data of the DBField.

2.3 DBList:
----------

A DBList can store a list of records retrieved from a DBFile.


Methods:
	- initForDatabase: (DBFile *) aDatabase
		This method creates a new instance of DBList for a DBFile
		previously created. 'aDatabase' is a pointer to this DBFile
		object.

	- fetchAllRecords
		Read all records which are not marked as deleted and insert
		them into the DBList. Before fetching all records of the
		DBList are deleted.

	- (int) count
		'count' returns the number of records stored in the DBList
		object.

	- findRecordAt: (int) index
		'findRecordAt:' returns a pointer to the DBRecord object
		at index 'index', or nil if 'index' is out of range.

	- insertRecord: (DBRecord *) aRecord
		By calling this method, the DBRecord object 'aRecord' is
		inserted at the end of the list.

	- deleteRecordAt: (int) index
		This method deletes the DBRecord at index 'index'.


2.4 DBRecord:
------------

An instance of this class can store exactly one record of a DBase data file.


Methods:
	- initForDatabase: (DBFile *) aDatabase
		This methods initializes a new DBRecord object for DBFile
		'aDatabase'. The current record of this data file is copied
		to the DBRecord data buffer.

	- copyToDB
		This method copies the information stored in the DBRecord
		object to the DBFile data buffer. There it can be modified
		using DBFields.

	- copyFromDB
		This method copies the data in the DBFile data buffer to
		the DBRecord data buffer.

	- replace
		This method writes the data buffer of the DBRecord to the
		data file. The data buffer is stored to the record position
		active at creation of the DBRecord object.


3. Future perspectives:
======================

	*	better support for all DBase III data types
	*	indexing (BTree, maybe Hash)
	*	more flexible DBList
	*	PM classes supporting this library (fetch and display via a
		multi-column listbox, simple storing of data, entryfields
		directly communicating with database,...)
	*	Database Creator to create empty data files.
	*	much better documentation, sample programs
	*	maybe a DLL version of the library.
	*	...


4. Licensing:
============

This library is distributed as a part of the accompanying OS/2 PM class
library. Just register the PM class library to be allowed to use the DBase
class library.

After registration you are automatically registered for all following versions
of the library until the major version number increases. That means by
registering this version of the library together with the PM class library
(PM library: version 0.5; DB library: version 0.3) you are automatically
registered for all future versions of the DB library including version
1.0.

Starting at version 1.1 of the DB library you have to register newly at a
special update price.

Support the Shareware distribution concept and register if you like this
library and want to use it in your own applications. Future Shareware
releases of this library depend heavily on the will of users to register.
So, if no one registers this library, surely no further effort will be made
in adding functionality to the library.


5. Warranty:
===========

Well, as you might have thought, there's ABSOLUTELY NO WARRANTY for this
library package.


6. Pricing:
==========

The registration fee for the OS/2 PM class library together with the Database
library is 250ATS (250 Austrian Schillings), that's about 25US$, per copy
for individuals or 500ATS for companies. Don't forget to check with your bank,
how much you should pay, so that I will get the whole registration fee as
mentioned above.

Don't forget to fill in the registration form and send it to me (address
below).

-------------------------------------------------------------------------------

Send the money directly to my local bank account:

	NAME OF BANK: 		RAIFFEISENBANK KREMS
	ID Nr. OF BANK:		32397
	ACCOUNT NR.:		12.195

For information about 10+ licenses of this libraries feel free to contact
me via Internet E-Mail (baier@ci.tuwien.ac.at) or via Snail Mail at:

Thomas Baier
Ufergasse 68
A-3500 Krems
Austria

Internet: baier@ci.tuwien.ac.at