Category : Dbase (Clipper, FoxBase, etc) Languages Source Code
Archive   : DBFNDX.ZIP
Filename : DBFNDX.DOC

DBFNDX version 1.0
dBASE III PLUS Compatible Replaceable Database Driver for Clipper 5.01

Copyright (c) 1991 Nantucket Corporation. All rights reserved.


The Clipper 5.01 database system supports a driver
architecture allowing Clipper-compiled applications data
format independence. This architecture is supplied to allow
you to create programs to allow Clipper programs access to
other file and database systems. The DBFNDX driver uses this
architecture to allow access to dBASE III PLUS compatible
index files within a Clipper 5.01 program.


========================================================================
1 Contents

The following topics are covered in this documentation file:

* Contents
* The Clipper 5.01 Replaceable Database Driver Architecture
* Overview of the DBFNDX RDD
* Installing DBFNDX Driver Files
* Creating a .PLL Including DBFNDX
* Linking the DBFNDX Database Driver
* Using the DBFNDX Database Driver
- Memory Usage
- Error Handling
- Using (.ntx) and (.ndx) Files Concurrently
* Compatibility with dBASE III PLUS
- Supported Data Types
- Supported Key Expressions
- FIND vs SEEK
- Logical Key Expressions
- Sharing Access on a Network
* Compatibility with dBASE IV


========================================================================
2 The Clipper 5.01 Replaceable Database Driver Architecture

The database system in Clipper 5.01 has been changed to
allow concurrent access to multiple data formats in a single
application program. This is accomplished with a
multi-layered system that provides a high-level database
independent interface that talks to a low-level data format
specific driver.

Each work area is a high-level interface to a database table
or file. All Clipper database commands and functions
operated on a work area which, in turn, operates on a
database driver which actually performs the physical access
to the stored database information. The layering of the
system looks like this:

+------------------------------------+
| Database commands and functions |
+====================================+
| Work area |
+------------------------------------+
| Database driver |
+------------------------------------+
| Stored Data |
+------------------------------------+

In this system, each work area has a single database driver
associated with it. Each database driver is supplied as a
separate library (.LIB) file to link into application
programs. Within the application program, the name of the
database driver is specified when the database file or table
is opened or accessed with the USE command or DBUSE()
function.

The default database driver, DBFNTX, which supports the
traditional (.dbf), (.ntx), and (.dbt) files is installed
into your \CLIPPER5\LIB directory. This driver is linked
into each program automatically if a USE command or DBUSE()
function is specified without an explicit request for an
alternate database driver.


========================================================================
3 Overview of the DBFNDX RDD

The DBFNDX database driver is supplied to allow creation,
access, and updating of dBASE III and dBASE III PLUS
compatible index (.ndx) files. Index (.ndx) files created
with Clipper 5.01 are completely the same as those created
by dBASE III PLUS. All operations that can be performed on
standard Clipper index (.ntx) files can be performed on
(.ndx) files with the DBFNDX database driver.

In a network environment, the DBFNDX driver supports the
Clipper file and record locking scheme. The multiuser
behavior is the same as the default DBFNTX driver. This
means that the DBFNDX database driver supports concurrent
access to (.ndx) files between Clipper applications only.
Concurrent access to (.ndx) files between dBASE III PLUS and
Clipper 5.01 programs is NOT supported.

Warning: Updating database (.dbf) and index (.ndx) files
shared between dBASE III PLUS and Clipper 5.01 programs MAY
corrupt both the (.dbf) and any of its associated (.ndx)
files.


========================================================================
4 Installing DBFNDX Driver Files

The DBFNDX database driver is supplied with the following
three files:

-------------------------------------------------------------
File Description
-------------------------------------------------------------
DBFNDX.LIB DBFNDX Database Driver
DBFNDX.CH Header file containing support declarations

and command definitions
DBFNDX.DOC The current README file
-------------------------------------------------------------

To install the DBFNDX database driver files into the
standard Clipper 5.01 development system directory
structure:

1. Copy DBFNDX.LIB into your \CLIPPER5\LIB directory

2. Copy DBFNDX.CH into your \CLIPPER5\INCLUDE directory


========================================================================
5 Linking the DBFNDX Database Driver

In order to link the DBFNDX database driver into an
application program, you must specify DBFNDX.LIB to the
linker in addition to your application object (.OBJ) files.
Note, in order to make the DBFNDX work concurrently with the
DBFNTX driver, it necessary to specify DBFNDX.LIB in the
object file portion of the link line as follows:

1. To link with .RTLink using the default freeformat
syntax:

C>RTLINK FI , DBFNDX.LIB

2. To link with .RTLink using positional syntax:

C>RTLINK DBFNDX.LIB;


3. To link with .RTLink using BASE50.PLL and freeformat
syntax:

C>RTLINK FI , DBFNDX.LIB /PLL:BASE50

This command line may generate warning messages regarding
duplicate symbols in /PLL. These messages may safely be ignored.

4. To link using MS-Link version 3.65 and above:

C>LINK DBFNDX.LIB /NOD /NOE /SE:512;

Note: These link commands all assume the LIB, OBJ, and PLL
environment variables are set to the standard locations.


========================================================================
6 Using the DBFNDX Database Driver

To use (.ndx) files there are two steps:

1. Place a #include "dbfndx.ch" at the top of each program
(.prg) file that opens a database using the DBFNDX
database driver.

2. Specify the USE command with a VIA "DBFNDX" clause.

Note: The database driver name must be specified as a
literal character string and not an expression.

For example, the following shows a general program fragment
exemplifying these steps:

/***
* Sample.prg
* Program fragment to demonstrate use of DBFNDX driver
*
*/

#include "dbfndx.ch"
.
.
.
USE Customers INDEX Name, Address NEW VIA "DBFNDX"


-----------------------------------------------------------------
6.1 Memory Usage

The added code overhead of the DBFNDX database driver is
about 10K bytes of conventional memory. DBFNDX uses the
(.dbf) portion of the default DBFNTX driver so only the
(.ndx) index code and data are included in the resident
portion of the program. Memory usage for each (.ndx) file
is the same as for each (.ntx) file open since the (.ndx)
system shares the page buffering system and internal
structures with (.ntx) system.


-----------------------------------------------------------------
6.2 Error Handling

The indexing behaviors of DBFNTX and DBFNDX in a Clipper
application are identical unless otherwise noted. The error
behavior has been made identical to Clipper 5.01 DBFNTX
behaviors. That means that most errors can be handled using
BEGIN SEQUENCE...END SEQUENCE.


-----------------------------------------------------------------
6.3 Using (.ntx) and (.ndx) Files Concurrently

You can use both (.ndx) and (.ntx) files concurrently in a
Clipper 5.01 program by like this:

// (.ntx) file using default DBFNTX driver
USE File1 INDEX File1 NEW

// (.ndx) files using DBFNDX driver
USE File2 VIA "DBFNDX" INDEX File2 NEW

Note however, (.ndx) and (.ntx) files cannot be used in the
same workarea. For example, the following does not work:

USE File1 VIA "DBFNDX" INDEX File1.ntx File1.ndx


========================================================================
7 Compatibility with dBASE III PLUS

When accessing (.ndx) files in combination with dBASE III
PLUS, there are several issues:


-----------------------------------------------------------------
7.1 Supported Data Types

The DBFNDX database driver supports the following data types
for key expressions:

Character
Numeric
Date

This is consistent with dBASE III PLUS.


-----------------------------------------------------------------
7.2 Supported Key Expressions

When you create (.ndx) files using the DBFNDX driver, you
must use only Clipper or user-defined functions compatible
with dBASE III PLUS. Use of the other functions will render
the (.ndx) file unreadable in dBASE III PLUS.


-----------------------------------------------------------------
7.3 FIND vs SEEK

In Clipper 5.01, the FIND command can only be used to locate
keys in indexes where the index key expression is character
type. This differs from dBASE III PLUS where FIND supports
character and numeric key values.

Note: In Clipper 5.01 programs, always use the SEEK command
or the DBSEEK() function to search an index for a key value.

When using FIND or SEEK, the DBFNDX driver allows you to
recover from a data type error. However Error:canDefault,
Error:canRetry or Error:canSubstitute are set to false
(.F.), and therefore you should use BEGIN SEQUENCE...END to
handle a SEEK or FIND data type error. Within the error
block for the current operation, issue a BREAK() using the
error object the DBFNDX database driver generates, like
this:

bOld := ERRORBLOCK({|oError| BREAK(oError)})
.
.
.
BEGIN SEQUENCE
SEEK xVar
RECOVER USING oError
// Recovery code
END
.
.
.
ERRORBLOCK(bOld)


-----------------------------------------------------------------
7.4 Logical Key Expressions

The DBFNDX database driver does not support indexing with
logical key expression as does the default DBFNTX database
driver. This is actually a dBASE III PLUS limitation, but
not supported by the DBFNDX driver in order to enforce
compatibility with dBASE III PLUS.

To workaround this limitation, index logical values by
converting them to character values like this:

INDEX ON IIF(, "T", "F") TO

Note: Be sure to index using IIF() compatibility function
and not the Clipper IF() function.


-----------------------------------------------------------------
7.5 Sharing on a Network

As mentioned above, the DBFNDX driver does not support dBASE
III PLUS file and record locking schemes. Instead, the
DBFNDX driver supports the DBFNTX file and record locking
scheme. This means that if the same database and index
files are open in Clipper 5.01 and dBASE III PLUS, locks
made in the Clipper program are not visible to dBASE III
PLUS and vice-versa.

Warning: Database integrity is NOT guaranteed and index
corruption will occur if a Clipper and dBASE III PLUS
program attempt to write to the database and index file at
the same time.

For this reason, concurrent use of the same database (.dbf)
and indexc (.ndx) files by dBASE III PLUS and a Clipper 5.01
program is strongly discouraged and NOT supported by
Nantucket Coporation.


========================================================================
8 Compatibility with dBASE IV

Specific compatibility with dBASE IV is not known at this
time. However, the compatibility rules for (.dbf), (.dbf),
and (.ndx) files with dBASE IV are the same with the DBFNDX
driver as with dBASE III PLUS itself.


* * *