Category : C Source Code
Archive   : TC-DBF.ZIP
Filename : DBF.DOC

dBASE III interface routines for C.
Author Mark Sadler June 19, 1987

The routines included here provide some tools for access to dBASE III
database files by Turbo C, version 1.0, programs. These routines are very
rudimentary. There is no support for index files, no buffering of data
(other than what TC provides), no support for memo files, etc. The
functions included in this package are:

D_ADDREC - function to append record to dbf file
D_BLANK - function to blank a record
D_CLOSE - function to close a dbf file
D_CPYSTR - function to copy an existing dbf structure to a new file
D_GETFLD - function to fill a buffer with the contents of field N
D_GETREC - function to get the contents of record N
D_OPEN - function to open a dbf file
D_PUTFLD - function to fill a field with the contents of a buffer
D_PUTREC - function to write a record to a dbf file
DBF.H - header file that must be included in programs calling
above functions
DBF.LIB - library file of above functions (Small Model)

A skeletal program might look like this:

#include "dbf.h"

main()
{
struct DBF *d; /* define DBF pointer */
long record = 1L; /* define record number */
d = (struct DBF *)malloc(sizeof(struct DBF)); /* allocate memory for struct*/
strcpy(d->filename,"filename.dbf"); /* fill filename */
d_open(d); /* open filename */
d_getrec(d,record); /* get record */
... modify record or use information, or whatever ...
d_putrec(d,record); /* rewrite changed record */
d_close(d); /* close file */
free(d); /* release memory allocation */
}

The d_open function takes a pointer to a DBF structure as an argument, with
the filename field filled in. The function then opens the file for
read/write and fills the DBF structure with information about the file such
as number of records, length of records, number of fields, etc. d_open
also allocates space for and fills an array of information about each
field: size, name, type, etc. Finally, d_open allocates space in memory for
a record to be held in memory and places memory location information for
each field into the field array. The pointers to the field array and
record are included in the DBF structure.

The d_getrec function gets a record from the dbf file and places it in
memory. while the record is in memory it may be accessed with the
DBF.record_ptr. If changes are made they may be written back to the dbf
file with the d_putrec function.

The d_getfld function fills a buffer with the data within a field from a
record that has been loaded into memory with d_getrec. In other words this
function extracts the data from a record in memory and converts it from
dBASE III format to one that may be more easily accessed with a C
program(i.e. zero terminated ascii). d_putfld moves data from a buffer
back into a record field. Note that these functions do not get the record
that contains the field. This must be done with d_getrec. If you know the
structure of the dbf records at compile time, it would be more efficient to
create a pointer to a structure which matches the content of the record.
This pointer could then be pointed to the record in memory.

dBASE III stores all records in ascii format. Character fields are stored
padded with spaces ('\x20' rather than nulls). Numbers are right justified
within their field and again padded with spaces. Logical fields are single
bytes containing T,t,y,F,f,n.

The d_blank function fills the record in memory with blanks. This is
usefull for appending blank records and making sure the record is blank
before filling with new data.

d_addrec writes the data contained in the memory record to the end of the dbf
file. d_close updates the "date of last update" and number of records
information contained in the dbf file header, and appends a end of file marker
to the end of the file. Any file which has been changed with d_putrec or
d_addrec should always be closed with d_close. d_close also deallocates memory
which was allocated by d_open. You must deallocate space for the DBF structure.

The structure of dBASE III files is as follows:

dBASE III DATABASE FILE HEADER:
+---------+-------------------+---------------------------------+
| BYTE | CONTENTS | MEANING |
+---------+-------------------+---------------------------------+
| 0 | 1 byte | dBASE III version number |
| | | (03H without a .DBT file) |
| | | (83H with a .DBT file) |
+---------+-------------------+---------------------------------+
| 1-3 | 3 bytes | date of last update |
| | | (YY MM DD) in binary format |
+---------+-------------------+---------------------------------+
| 4-7 | 32 bit number | number of records in data file |
+---------+-------------------+---------------------------------+
| 8-9 | 16 bit number | length of header structure |
+---------+-------------------+---------------------------------+
| 10-11 | 16 bit number | length of the record |
+---------+-------------------+---------------------------------+
| 12-31 | 20 bytes | reserved bytes (version 1.00) |
+---------+-------------------+---------------------------------+
| 32-n | 32 bytes each | field descriptor array |
| | | (see below) | --+
+---------+-------------------+---------------------------------+ |
| n+1 | 1 byte | 0DH as the field terminator | |
+---------+-------------------+---------------------------------+ |
| |
| |
A FIELD DESCRIPTOR: <------------------------------------------+
+---------+-------------------+---------------------------------+
| BYTE | CONTENTS | MEANING |
+---------+-------------------+---------------------------------+
| 0-10 | 11 bytes | field name in ASCII zero-filled |
+---------+-------------------+---------------------------------+
| 11 | 1 byte | field type in ASCII |
| | | (C N L D or M) |
+---------+-------------------+---------------------------------+
| 12-15 | 32 bit number | field data address |
| | | (address is set in memory) |
+---------+-------------------+---------------------------------+
| 16 | 1 byte | field length in binary |
+---------+-------------------+---------------------------------+
| 17 | 1 byte | field decimal count in binary |
+---------+-------------------+--------------------------------
| 18-31 | 14 bytes | reserved bytes (version 1.00) |
+---------+-------------------+---------------------------------+
The data records are layed out as follows:
1. Data records are preceeded by one byte that is a
space (20H) if the record is not deleted and an
asterisk (2AH) if it is deleted.
2. Data fields are packed into records with no field
separators or record terminators.
3. Data types are stored in ASCII format as follows:
DATA TYPE DATA RECORD STORAGE
--------- --------------------------------------------
Character (ASCII characters)
Numeric - . 0 1 2 3 4 5 6 7 8 9
Logical ? Y y N n T t F f (? when not initialized)
Memo (10 digits representing a .DBT block number)
Date (8 digits in YYYYMMDD format, such as
19840704 for July 4, 1984)

This information came directly from the Ashton-Tate Forum. It can also be
found in the Advanced Programmer's Guide available from Ashton-Tate.

One slight difference occurs between files created by dBASE III and those
created by dBASE III Plus. In the earlier files, there is an ASCII NUL
character between the $0D end of header indicator and the start of the
data. This NUL is no longer present in Plus, making a Plus header one byte
smaller than an identically structured III file. The functions included
here will work with either version of dBASE III and writes files which may
be used by either.

The field record array which is created by d_open is a memory image of the
field description array contained in the dbf file. The "field data
address" is evidently filled in by dBASE when the file is opened with a use
command and points to the memory location where the field is stored in
memory. d_open does the same thing.

The field description array and portions of the DBF structure is filled by
d_open with the fread function. The portion of the DBF structure which is
filled this way is marked, do not change. Also do not change the
FIELD_RECORD structure. Finally do not use the -a switch to compile any
program which includes dbf.h so that these structures will be filled
correctly.

Two programs are included as examples:

dbstat - prints statistics about a dbf file
listdb - prints the contents of a dbf file
dbcopy - copies a dbf file