C5DG-9 Terminal Drivers

Clipper 5.x – Drivers Guide

Chapter 9

Alternate Terminal Drivers

Clipper supports a driver architecture that allows Clipper- compiled applications to use alternate terminal drivers. This architecture provides support for nonstandard video hardware and ANSI output devices, allowing your applications to run in a wider variety of environments.

The following terminal drivers are supplied as part of the Clipper Development System and are discussed in this chapter:

. The ANSITERM driver provides ANSI terminal support for systems that require it

. The NOVTERM driver causes Clipper applications to execute faster when run on some nondedicated network server software

. The PCBIOS driver provides direct BIOS calls rather than direct screen writes for systems requiring this form of I/O

In This Chapter

This chapter discusses how Alternate Terminal Drivers fit into the overall Clipper architecture as well as how to install and use each of the supplied terminal drivers. The following major topics are discussed:

. The Alternate Terminal Driver Architecture

. The ANSITERM Alternate Terminal Driver

. The NOVTERM Alternate Terminal Driver

. The PCBIOS Alternate Terminal Driver

The Alternate Terminal Driver Architecture

In Clipper, communication with I/O devices is controlled by a multilayered terminal system. At the lowest level is the terminal driver which controls screen and keyboard activity. It consists of a screen and keyboard driver that communicates directly with the I/O device (operating system or hardware). It is the device specific part of the Clipper terminal system.

There is, then, a higher level system that communicates with terminal drivers. This system is known as the General Terminal (GT) system and provides general services that create Clipper screen and keyboard commands and functions. The following figure demonstrates:

                   +—————————————–+

                   | CA-Clipper screen and keyboard commands |
                   |              and functions              |
                   |-----------------------------------------|
                   |        General Terminal (GT.OBJ)        |
                   ------------------------------------------|
                   |             Terminal Driver             |
                   |-----------------------------------------|
                   |          Screen   |   Keyboard          |
                   +-----------------------------------------+

The default terminal driver, designed for IBM PC and 100% compatibles, is supplied as a library file (TERMINAL.LIB) installed into your \CLIPPER5\LIB directory. This driver links into each program automatically if you specify no alternative terminal driver provided that you do not use the /R option when you compile. An alternate terminal driver is supplied as a separate library (.LIB) file that links into an application program in place of the default terminal driver if you specify it on the link line.

All alternate terminal drivers work through the General Terminal layer as supplied in the file GT.OBJ. The Clipper installation program installs this file in the \CLIPPER5\OBJ subdirectory on the drive that you specify, so you need not install the driver manually.

The ANSITERM Alternate Terminal Driver

The ANSITERM terminal driver supports the ANSI screen mode for all screen display from Clipper programs.

This screen mode is installed by specifying ANSI.SYS in the user’s CONFIG.SYS. ANSI.SYS replaces the default DOS CON device driver for video display and keyboard input. Once installed it supports ANSI escape sequences to erase the screen, set the screen mode, and control the cursor in a hardware-independent way. Most modern DOS programs, however, do not use it and write either directly to the video hardware or use BIOS routines for enhanced screen performance.

Use the ANSI screen mode for Clipper programs that run on hardware that does not support either writing to video hardware or BIOS calls for screen display. This is the case when using alternative display hardware to support the blind.

Note: The ANSITERM terminal driver fully supports all screen and keyboard functionality of the default terminal driver. This includes the ability to save and restore screens and support for all keys on the standard 101-key keyboard.

Installing ANSITERM Terminal Files

The ANSITERM terminal driver is supplied as the file ANSITERM.LIB. The Clipper installation program installs this file in the \CLIPPER5\LIB subdirectory on the drive that you specify, so you need not install it manually.

Linking the ANSITERM Terminal Driver

To link the ANSITERM alternate terminal driver into an application program, you must specify both GT.OBJ and ANSITERM.LIB to the linker along with your application object (.OBJ) modules.

1. To link with .RTLink using positional syntax:

C>RTLINK <appObjectList> GT,,, ANSITERM

2. To link with .RTLink using freeformat syntax:

C>RTLINK FI <appObjectList>, GT LIB ANSITERM

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

C>RTLINK FI <appObjectList> /PLL:ANSITERM

Note: These link commands assume you have set the LIB, OBJ, and PLL environment variables to the standard locations. They also assume that the Clipper programs were compiled without the /R option.

Important! You cannot link the ANSITERM driver with BASE52.PLL. An application linked with both ANSITERM.LIB and BASE52.PLL may cause the computer to freeze upon execution.

The Runtime Environment

Using ANSITERM.LIB requires that ANSI.SYS be installed on the user’s computer. To accomplish this, include the following statement in the user’s CONFIG.SYS:

DEVICE=ANSI.SYS

Performance Concerns

Because the ANSITERM terminal driver uses buffered screen writes for all screen painting, some operations, especially those that scroll the screen, are slow. These include:

1. All box drawing commands and functions

2. All console commands and functions when scrolling

3. All clear screen commands and functions

4. All restore screen commands and functions

5. Standard out functions (OUTSTD() and OUTERR()) whether the screen is scrolling or not

Note: Overall performance of Clipper programs is slower since the ANSITERM terminal driver must spend more time polling for user events than the standard Clipper terminal driver.

Screen Output from C and Assembly Language

The ANSITERM terminal driver overwrites all output from C and Assembly Language when it refreshes the screen from the screen buffer. As a consequence, you should perform all screen output from Clipper.

The ANSITERM terminal driver also virtualizes the cursor. This means that BIOS functions that report the location of the hardware cursor will not always return the correct value. To obtain the cursor position, use Clipper’s ROW() and COL() functions instead.

Other Incompatibilities

1. ISCOLOR() always returns false (.F.).

2. When you load DBU, the default color mode is monochrome unless you specify DBU with the /C command line option.

3. The first time you invoke the Debugger, the default color mode is also monochrome unless you set the Options:Mono display off.

4. When an application linked with the ANSITERM terminal driver terminates, the last color set in the application becomes the DOS color. This happens since colors set with ANSITERM are global to DOS and Clipper cannot query DOS for the current screen colors as the application loads.

5. Nondisplaying ASCII characters are presented as a space by the ANSITERM terminal driver. These include BELL (CHR(7)), BS (CHR(8)), TAB (CHR(9)), LF (CHR(10)), CR (CHR(13)), and ESC (CHR(27)).

The NOVTERM Alternate Terminal Driver

The NOVTERM terminal driver is a special-purpose driver that circumvents an incompatibility between some nondedicated network server software and Clipper. This incompatibility causes printers connected to the server to slow to an unusable rate.

Clipper applications and nondedicated servers compete for resources. Clipper applications make use of the time between keystrokes to perform various system tasks. This greatly improves the application’s overall performance by limiting its idle time. Certain nondedicated servers only attempt to print within an application’s idle time. Since a Clipper application is seldom idle, this greatly slows printing.

Important! The NOVTERM terminal driver corrects the incompatibility by preventing the Clipper application from using idle time. Because this can severely hamper performance, you should only use the NOVTERM terminal driver when necessary, and then you should link it only into those applications that are physically running the nondedicated server.

Note: The NOVTERM terminal driver fully supports all screen and keyboard functionality of the default terminal driver. This includes the ability to save and restore screens and support for all keys on the standard 101-key keyboard.

Installing NOVTERM Terminal Files

The NOVTERM terminal driver is supplied as the file NOVTERM.LIB. The Clipper installation program installs the driver file in the \CLIPPER5\LIB subdirectory on the drive that you specify, so you need not install it manually.

Linking the NOVTERM Terminal Driver

To link the NOVTERM alternate terminal driver into an application, you must specify both GT.OBJ and NOVTERM.LIB to the linker with your application object (.OBJ) modules.

1. To link with .RTLink using positional syntax:

C>RTLINK <appObjectList> GT,,, NOVTERM

2. To link with .RTLink using freeformat syntax:

C>RTLINK FI <appObjectList>, GT LIB NOVTERM

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

C>RTLINK FI <appObjectList> /PLL:NOVTERM

Note: These link commands assume you have set the LIB, OBJ, and PLL environment variables to the standard locations. They also assume that the Clipper programs were compiled without the /R option.

Important! You cannot link the NOVTERM driver with BASE52.PLL. An application linked with both NOVTERM.LIB and BASE52.PLL may cause the computer to freeze upon execution.

Performance Concerns

Overall performance of Clipper programs is slower since the NOVTERM terminal driver must spend more time polling for user events than the standard Clipper terminal driver and since the program will not use its idle time for other tasks.

Screen Output from C and Assembly Language

The NOVTERM terminal driver overwrites all output from C and Assembly Language when it refreshes the screen from the screen buffer. Therefore, you should perform all screen output from Clipper.

The NOVTERM terminal driver also virtualizes the cursor. This means that BIOS functions that report the location of the hardware cursor will not always return the correct value. To obtain the cursor position, use Clipper’s ROW() and COL() functions.

The PCBIOS Alternate Terminal Driver

The PCBIOS terminal driver uses BIOS calls instead of direct screen writes. It is designedd for applications that trap BIOS calls to redirect output over telecommunication lines or to convert output to a form compatible with two-byte character sets.

Note: The PCBIOS terminal driver fully supports all screen and keyboard functionality of the default terminal driver. This includes the ability to save and restore screens and support for all keys on the standard 101-key keyboard.

Installing PCBIOS Terminal Files

The PCBIOS terminal driver is supplied as the file, PCBIOS.LIB. The Clipper installation program installs the driver file in the \CLIPPER5\LIB subdirectory on the drive that you specify, so you need not install it manually.

Linking the PCBIOS Terminal Driver

To link the PCBIOS alternate terminal driver into an application program, you must specify both GT.OBJ and PCBIOS.LIB to the linker in addition to your application object (.OBJ) modules.

1. To link with .RTLink using positional syntax:

   C>RTLINK <appObjectList> GT,,, PCBIOS;

2. To link with .RTLink using freeformat syntax:

   C>RTLINK FI <appObjectList>, GT LIB PCBIOS

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

   C>RTLINK FI <appObjectList> /PLL:PCBIOS

Note: These link commands assume you have set the LIB, OBJ, and PLL environment variables to the standard locations. They also assume that the Clipper programs were compiled without the /R option.

Important! You cannot link the PCBIOS driver with BASE52.PLL. An application linked with both PCBIOS.LIB and BASE52.PLL may cause the user’s computer to freeze when the user executes it.

Performance Concerns

Because the PCBIOS terminal driver uses buffered screen writes for all screen painting, some operations, especially those that scroll the screen, are slow. These include:

1. All box drawing commands and functions

2. All console commands and functions when scrolling

3. All clear screen commands and functions

4. All restore screen commands and functions

5. Standard out functions (OUTSTD() and OUTERR()) whether the screen is scrolling or not

Screen Output from C and Assembly Language

The PCBIOS terminal driver also overwrites all output from C and Assembly Language when it refreshes the screen from the screen buffer. Therefore, you should perform all screen output from Clipper.

The PCBIOS terminal driver also virtualizes the cursor. This means that BIOS functions that report the location of the hardware cursor do not always return the correct value. To obtain the cursor position, use Clipper’s ROW() and COL() functions.

Summary

This chapter has introduced you to the Alternate Terminal Driver concept, giving you specific information on the architecture used to implement them in Clipper. Each of the alternate terminal drivers supplied with Clipper was discussed, including how to link and use it into your application and the implications of doing so.

Advertisements

C5DG-8 DBPX Driver

Clipper 5.x – Drivers Guide

Chapter 8

DBPX Driver Installation and Usage

DBPX is the Paradox 3.5 compatible RDD for Clipper. It connects to the low-level database management subsystem in the Clipper architecture. When you use the DBPX RDD, you add a number or features, including the ability to:

. Create access to and modify Paradox tables, records, and fields

. Create, select, and activate secondary indexes on Paradox tables

. Create and modify Paradox table structures, including primary index fields

. Use explicit record and file locks with concurrent execution of other Clipper applications

. Import Paradox tables directly into Clipper arrays

In This Chapter

This chapter explains how to install DBPX and how to use it in your applications. The following major topics are discussed:

. Overview of the DBPX RDD

. Installing DBPX Driver Files

. Linking the DBPX Driver

. Using the DBPX Driver

Overview of the DBPX RDD

The DBPX driver lets you create and maintain (.db), (.px), (.x??), and (.y??) files with features different from those supplied with the original DBFNTX driver and compatible with files created under Paradox 3.5. The new features are supplied in the form of several syntactical additions to database and indexing commands and functions. Specifically you can:

. Create tables that recognize the standard Clipper data types as well as Currency ($) and Short (S) numbers between -32,767 to +32,767

. Create equally efficient keyed and unkeyed tables

. Create, select, and activate secondary indexes on Paradox tables

The DBPX driver provides simple, seamless access to the Paradox database system. The Clipper application programmer who intends to access Paradox tables with the “VIA” clause need only include the RDD header file at compile time and make the appropriate libraries available at link time.

Paradox stores data in tables (known to Xbase developers as data files (.db)’s), consisting of fields and records. Unlike Xbase databases, a Paradox database refers to a group of files that are related to each other in some way, rather than to one file.

Also, Paradox employs the concept of companion files, known as objects, that are related to the table. Some examples of object files are report forms, indexes, and data entry forms. A table and its accompanying objects are referred to as a family.

It is easy to identify objects belonging to a particular family since they all have the same base filename and are distinguished by their extensions as shown in the table below.

Paradox File Descriptions
——————–  —————————————————
Extension         Object

.DB                       Table

.PX          Primary Index 
.X?? or Y??  Secondary Index
.F or F??    Data Entry Forms
.R or R??    Report Formats
.G or G??    Graph Specifications
.SET         Image Settings
.VAL         Field Validity Specifications
------------ ------------------------------------------------------------

The DBPX driver only deals with the table and index files (.db, .px, .x?? and y??) so only these files are discussed here.

Though Paradox tables are limited to 8 character filenames, each table can contain an unlimited number of records in files up to 256M in size. Paradox records in nonkeyed tables can be up to 4000 bytes each while keyed tables have a 1350 byte limitation. Each record can contain up to 255 fields of up to 255 characters each.

There are some field naming restrictions you must observe. Field names may:

. Although the Paradox file structure allows fields to be up to 25 characters long, since Clipper symbols can only be 10 characters, DBPX truncates the field name to 10 characters.

. The Paradox file structure allows embedded spaces in field names. Since this is illegal in Clipper, the DBPX driver converts spaces into underscores (_).

. Not be duplicated in the same table.

Also, most Paradox data types directly match data types in standard Xbase data files, with these differences:

. Paradox tables support both the Numeric (N) data type as well as a more specific Currency ($) data type. Both the N and $ data types can have 15 significant digits. Numeric types that exceed this length are rounded and stored as scientific notation. Also, DBPX supports the Short (S) data type to represent numbers between -32,767 and +32,767.

. The Alphanumeric field type allows all ASCII characters except embedded nulls (ASCII 0). The Alphanumeric type is identical to the Character (C) data type in Xbase. Paradox limits this field type to 255 characters.

. Paradox also supports a Date (D) field type, stored as a long integer. It can contain any value between January 1, 100 A.D. and December 31, 9999.

Installing DBPX Driver Files

The DBPX RDD is supplied as the file, DBPX.LIB:

The Clipper installation program installs this driver in the \CLIPPER5\LIB subdirectory on the drive that you specify, so you need not install the driver manually.

Linking the DBPX Database Driver

To link the DBPX driver, you must specify DBPX.LIB to the linker along with your application object (.OBJ) modules.

1. To link with .RTLink using positional syntax:

C>RTLINK <appObjectList> ,,,DBPX

2. To link with .RTLink using freeformat syntax:

C>RTLINK FI <appObjectList> LIB DBPX

Note: These link commands all assume the LIB, OBJ, and PLL environment variables are set to the standard locations. They also assume that the Clipper programs were compiled without the /R option.

Using the DBPX Database Driver

To use Paradox files in a Clipper program:

1. Place REQUEST DBPX at the top of each program file (.prg) that opens a database file using the DBPX driver.

2. Specify the VIA “DBPX” clause if you open the database file with the USE command.

-OR-

3. Specify “DBPX” for the <cDriver> argument if you open the database file with the DBUSEAREA() function.

-OR-

4. Use RDDSETDEFAULT( “DBPX” ) to set the default driver to DBPX.

Except in the case of REQUEST, the RDD name must be a literal character string or a variable. In all cases it is important that the driver name be spelled correctly using uppercase letters.

The following program fragments illustrate:

REQUEST DBPX 
. 
. 
. 
USE Customers INDEX Name, Address NEW VIA "DBPX"
-OR-
REQUEST DBPX RDDSETDEFAULT( "DBPX" )
.
. 
. 
. 
USE Customers INDEX Name, Address NEW

Index Management 

The greatest variation from the standard Xbase database design in Paradox tables is index management. As in other systems, Paradox indexes are an efficient method of dynamically sorting or locating specific data within a table without forcing a search of all data in that table. Paradox tables take two forms: unkeyed and keyed.

An unkeyed table has no fields in its structure that have been identified as specific index keys. Therefore, records are maintained in natural order. New records are added to the end of an existing table, and the unique identity for each record is a record number.

Unlike Xbase data files, unkeyed tables are not more efficient in design or faster to traverse than keyed tables. This is because Paradox tables are built as linked lists rather than fixed-length, sequential tables. Therefore, it is actually less efficient to SKIP through a unkeyed table than it is through a keyed table.

A keyed table, on the other hand, can be lightning fast as long as the data you seek is part of the key. Otherwise, just as in an unkeyed table, you are forced to do a sequential search through the table’s data fields.

Paradox tables support two types of keys or indexes.

. Primary

. Secondary

Primary Indexes

Primary indexes are directly tied to keyed tables because a primary index indicates the table is keyed. Simply, it is impossible to have a keyed table without a primary index. If you remove the primary index from a keyed table it becomes an unkeyed table.

When you identify one or more of the table’s fields as a key field (by placing an asterisk (*) at the end of the field name) during table creation/restructuring, these fields are used to create a primary index. (Note that all key fields must be together as the first fields in a table). This invisibly rebuilds the table’s structure, though in operation it only seems to change or create the key index.

Once you identify this primary key, the table is automatically maintained in the key field order and all new records are checked to make sure that no duplicate keys are added to the table. This type of index is called a unique key index. You may have only one primary key per table, but this key can be a composite of many fields in the table. You may only modify by restructuring the table.

If it is necessary to change a primary key and restructure a table, all data in the table will still be bound to the unique key restriction. This is important if you change the primary key by adding a new field to it and there is already data in the table where this new composite key would have duplicates.

DBPX handles this situation by generating a runtime error and removing every record that violates this unique key and moving it to another table named KEYVIOL.db which has the identical structure of the offending table.

The KEYVIOL.db is automatically generated whenever this situation occurs. If there is already a KEYVIOL table, it is overwritten. Because of this you should always check for the existence of a KEYVIOL.db table immediately after any type of table restructuring.

Secondary Indexes

Secondary indexes are more like common Xbase-type indexes because they can be generated or modified on the fly without having any effect on the data or table structure and aren’t restricted to unique key data.

Unlike Xbase indexes, secondary indexes can only contain a single field as their key. As mentioned earlier, primary indexes are automatically maintained so that they are always up to date. Secondary indexes are created in two different types.

. Incremental (for keyed tables)

. Independent (for unkeyed tables)

Independent indexes are created only for unkeyed tables and are not dynamically maintained in any way. Because of this they can only be considered accurate at the time of their creation. If data changes inside the table that affects the index, the index must be completely regenerated before it can be considered useful again.

Alternately, incremental indexes are created only for keyed tables and are automatically maintained similarly to primary indexes except that instead of a complete rebuild at every change, only the portion of the index affected is updated. Incremental indexes are preferable when you are handling large tables since they take considerably less time and energy to keep accurate.

Temporary Indexes

ALL, NEXT, RECORD, and REST are all supported in the scoping expressions. The syntax of these keywords is identical to that used in Clipper. Note that you can only use one scope keyword at a time. If more than one of these keywords is encountered in a scoping expression, then the last keyword in the expression is the option used.

The ALL keyword (default) specifies that all records in the table should be included in the operation, starting at the first record.

NEXT processes the specified number of records, starting with the current record. For example, NEXT 5 would process the current record and the four records following it.

The RECORD keyword identifies a specific record to process. The desired record number should follow the keyword RECORD. To process record number 3, you would include “RECORD 3” in the expression.

The REST keyword causes processing to begin with the current record, instead of starting at the beginning of the table.

Sorting

In the event that you want to reorder a table based on field data but don’t need or want to have an index attached to it, you have the option of sorting the table based on the current index. This entails a simple copy from a keyed table to an unkeyed table using the table sort function.

Passwords and Security

Although the Paradox DBMS cannot be considered a data dictionary system, it does have some special characteristics that make it more suitable to networks than the standard Xbase tables. One of these features is the level of security available.

There are two methods to make sure that your data is secure: master passwords and auxiliary passwords. As the owner of a table, you can limit access by attaching a master password to it. Auxiliary passwords can also be identified to establish access to the table and its family.

Once any type of password is identified for a table, its is encrypted. This protects it not only from unauthorized Paradox users but also from anyone trying to dissect it at the DOS file level. The encryption method used by Paradox is literally unbreakable and if you (or your users) forget a table password, there is no way to recover that information.

Auxiliary passwords allow access control at the table and field levels. Access to tables can be restricted to:

. ReadOnly: No changes to the table can be made

. Update: Changes to nonkey fields are allowed, no records can be added or deleted

. Entry: Same as update except that new records can be added

. InsertDelete: Same as Entry except that records can be inserted and deleted

. All: Full access including restructuring and table deletion

Access to the fields can be identified as:

. None: This field data cannot be displayed to the user

. ReadOnly: User can see the field value, but cannot change it

. All: Full access

With DBPX, you may perform basic database operations on Paradox tables without code changes.

Note that because Paradox tables can have primary indexes which are actually part of the table structure specification, when you open a Paradox table, its associated primary index (if applicable) is also opened and activated. The only exception to this rule is if you indicate that you want a secondary index to be activated at the time you open the table. If no primary index is available and no secondary index is specified, the table is opened in natural sequence order.

You can have up to twenty-four Paradox tables open simultaneously. These may be separate tables or the same table repeatedly or any variation in between. This might be important if you want to have more than one secondary index active for a single table, allowing you to move from one work area to another with the only change being the index order of the data in the table. Be careful with this type of multiviewed approach, however, since you will be eating up memory for each work area, despite the fact that they refer to the same table.

Sharing Data in Networks

The DBPX driver supports the native Clipper single-lock locking scheme. Therefore, in a shared environment, your application and Paradox will not see each other’s record locks. This may result in some concurrency corruption and errors.

In a shared environment, DBPX performs no record buffering; immediately writing all changes to disk.

Concurrency is an issue whenever your application is running either on a network or in some other shared environment. One example of a non- network shared environment is when your application is called from another program (like Paradox, Quatro Pro, etc.) that also has access to the Paradox tables. Even if you don’t have any plans to use your program on a network, you should design it to be smart enough not to become a problem if faced with this type of shared example.

Also be aware that many networks have different rights and privilege restrictions and you should know what they are and how to handle them.

Using (.px) and (.ntx) Files Concurrently

You can use both (.px), as well as (.x), (.y) and (.ntx) files concurrently in a Clipper program like this:

REQUEST DBPX
// (.ntx) file using default DBFNTX driver
USE File1 INDEX File1 NEW
// (.idx) files using DBPX driver
USE File2 VIA "DBPX" INDEX File2 NEW

Note, however, that you cannot use (.px) and (.ntx) files in the same work area. For example, the following does not work:

USE File1 VIA "DBFNTX" INDEX File1.ntx, File2.px

Summary

In this chapter, you were given an overview of the features and benefits of the DBPX RDD. You also learned how to link this driver and how to use it in your applications.

C5DG-7 DBFNTX Driver

Clipper 5.x – Drivers Guide

Chapter 7

DBFNTX Driver Installation and Usage

DBFNTX is the default RDD for Clipper. This new database driver replaces the DBFNTX database driver supplied with earlier versions of Clipper and adds a number of new indexing features. With DBFNTX, you can:

. Create conditional indexes by specifying a FOR condition

. Create indexes using a record scope or WHILE condition, allowing you to INDEX based on the order of another index

. Create both ascending and descending order indexes

. Specify an expression that is evaluated periodically during indexing in order to display an index progress indicator

In This Chapter 

This chapter explains how to install DBFNTX and how to use it in your applications. The following major topics are discussed:

. Overview of the DBFNTX RDD

. New Locking Scheme

. Conditional Indexing

. Installing DBFNTX Driver Files

. Linking the DBFNTX Driver

. Using the DBFNTX Driver

. Compatibility with dBASE III

Overview of the DBFNTX RDD

As an update of the default database driver, DBFNTX is linked into and used automatically by your application unless you compile using the /R option.

New Features

The replaceable driver lets you create and maintain (.ntx) files using features above and beyond those supplied with the previous DBFNTX driver. The new indexing features are supplied in the form of several syntactical additions to the INDEX and REINDEX commands. Specifically you can:

. Specify full record scoping and conditional filtering using the standard ALL, FOR, WHILE, NEXT, REST, and RECORD clauses

. Create an index while another controlling index is still active

. Monitor indexing as each record (or a specified record number interval) is processed using the EVAL and EVERY clauses

. Eliminate separate coding for descending order keys using the DESCENDING clause

Compatibility

Index files (.ntx) created with the original DBFNTX driver are compatible with DBFNTX and can be used in new applications without reindexing. Index files (.ntx) created with this version of DBFNTX will also work with previous Clipper applications provided that you use no FOR, WHILE, <scope>, or DESCENDING clauses.

Important! Indexes produced with DBFNTX using FOR or DESCENDING are incompatible with earlier version (.ntx) files. If you attempt to access them with the original DBFNTX database driver or programs compiled with versions earlier than Clipper 5.2, you will get an unrecoverable runtime error. In Clipper, this generates an “index corrupted” error message, causing the application to terminate.

New Locking Scheme

The DBFNTX database driver implements a new locking scheme to resolve several problems identified in previous versions of Clipper and to prevent potential problems that might arise when running Clipper applications in a network environment. This section discusses these changes and their implications, including compatibility issues.

Lock Time-outs

Problem: Index locking in previous versions of Clipper was handled automatically by the database driver, and had no time-out provision. This created the potential for problems in network environments if a workstation died while holding a lock. If this situation occurred all other workstations waiting for an index lock would appear to freeze while waiting to obtain their lock. This could also happen if a user placed a Clipper application in the background on a multitasking system without sufficient processing time allocated to it. Eventually, most network operation systems would clear a connection that had no activity for a specified period of time. This would free the lock and everything would resume as normal, but frustrated users may have rebooted their machines possibly causing file corruption.

Solution: In Clipper 5.2 the NTX driver will generate a recoverable runtime error if it fails to lock the index after a predetermined number of retries. The default error handler for this system simply returns (.T.) to retry the operation. This emulates the behavior of previous Clipper versions.

Error Handling

Time out handling: The handling of this error is problematic because the lock is issued from various internal index routines. Therefore the only safe recoveries are to retry or quit. Choosing to default from the error or issuing a break will more than likely leave the index in a corrupted state. If either of the options is employed, the application should immediately recreate the index. The preferred way to handle a time out such as this is to alert the user of the situation so they don’t think their machine has hung, and then have the network administrator determine what workstation is causing the problem. When the problem workstation is cleared, the users that have timed out can select retry and continue processing.

NTXERR.PRG: The file NTXERR.PRG contains the source code for the default error handler INIT procedure. This error handler can be modified to allow user-defined error handling for index lock time-outs. Care should be exercised when modifying the error handler as detailed above.

Compatibility: The lock time-out capability when used in conjunction with the default error handler is totally compatibility with previous versions of Clipper. No changes are made to the NTX file structure and no action is required by the developer to activate the time-out functionality.

New Lock Offset

Problem: Index locking, which is transparent to the developer, uses a single-byte semaphore locking system. This semaphore was placed at a virtual offset (beyond the physical end of file) in the index file. In previous versions of Clipper, this offset was located at one billion (1,000,000,000) which was adequate at the time. But many systems today are capable of producing indexes that are large enough to cause the actual data present at the lock offset to become physically locked. This leads to problems when trying to read or write to the data at that offset.

Solution: The solution is to move the offset where locking occurs to a location at a greater offset. We have chosen FFFFFFFF hex, which is the largest offset possible under the DOS operating system. The problem with this solution is that new applications using the index will be locking this new byte while old applications using the same index will lock the old position. Clearly this would cause both applications to fail because each could have a lock on the file at the same time.

To avoid this, the signature of the index (in the index header) is modified to prevent pre-Clipper 5.2 applications from being able to open the index. Clipper 5.2 applications can detect the correct offset to use by the flag in the header and will automatically use the correct one. In Figure 7-1 below, each bit represents a flag:

BIT  7 6 5 4 3 2 1 0
FLAG R R R O P I I C
R Reserved
I Index type - both bits set (NTX)
C Index created with a Condition, condition in header
T Created as a Temporary index
O New Offset for exclusive (semaphore) lock
Figure 7-1: Bit Field for the Signature Byte of a -Clipper 5.2 NTX File

Activation

If Clipper 5.2 automatically modified the signature in the header when it created indexes, programs with automatic reindexing routines would be creating indexes that appeared corrupt to pre-Clipper 5.2 applications. This has an obvious problem with backward compatibility. Therefore, in order to create indexes with the new signature, the developer must link in the module NTXLOCK2.OBJ with the full knowledge that this will create indexes that older applications will not be able to access.

Header Changes

The signature byte of a .NTX file is 6 for an unenhanced NTX index. The inclusion of the NTXLOCK2.OBJ will cause the signature to become 26 hex. (6 hex ORed with 20 hex). See Figure 7-1 for an illustration of all the possible values for the signature byte.

Error Handling

Clipper 5.2 applications will automatically recognize the signature byte of the header, and depending on the signature value, will use the correct index lock location. Applications built with previous versions of Clipper, however, do not have the capability to detect the optional new information in the signature byte. Therefore, when an order application tries to open a file that has been created with the NTXLOCK2.OBJ linked in it will produce a Corruption Detected error.

Compatibility

The new locking location, if used, is not backward compatible with applications compiled with previous versions of Clipper.

Indexes created by applications built with a previous version of Clipper can be used by Clipper 5.2 using the new location and will not be modified unless the index is recreated in application.

Since older applications have no knowledge of the new index locking scheme nor of the significance of the header signature, these applications will assume the index is corrupt and will produce an Index Corrupted error.

Conditional Indexing

Conditional indexes are a feature of the DBFNTX driver. This section discusses this feature of the DBFNTX driver in some detail, giving you specific information about the implementation of conditional indexes. Compatibility issues are also discussed.

Conditional Indexes

Conditional indexes are produced by using a FOR condition in the index creation process. These indexes are made fully maintainable by storing the FOR condition in the index header. This condition is subsequently retrieved and compiled each time the index in opened. During updates, items are added to the index only if they meet the criteria of the condition.

Since older applications do not have the ability to recognize and use the condition stored in the header, they must be prevented from opening the index since they corrupt the index. This is accomplished by modifying the signature of the index (in the index header) preventing pre-Clipper 5.2 applications from being able to open the index. Clipper 5.2 applications can detect the flag in the header and will automatically use the stored FOR condition correctly.

Temporary Indexes

Temporary indexes are produced by using any scoping clause other than the FOR condition in the index creation process. These indexes are not automatically maintainable because the condition is not stored for later use. These indexes can be made maintainable if the condition can be expressed as a FOR condition and is added using the FOR clause. But the main use of temporary indexes is for fast creation of indexes for read- only browses or reports that operate on a subset of the database.

Since older applications would not operate properly with indexes that do not contain all the keys in a given database, they must be prevented from using them. This is accomplished by modifying the index signature to prevent pre-Clipper 5.2 applications from being able to open the index.

Activation

Conditional Indexes

The developer need only specify the FOR condition when creating the index. In doing so he must be fully aware the index will no longer be accessible to pre–Clipper 5.2 applications.

Temporary Indexes

The developer need only specify a scope other than FOR when creating the index. In doing so he must be fully aware the index will no longer be accessible to pre-Clipper 5.2 applications and that the index created is not maintainable.

Header Changes

The signature byte of a .NTX file is 6 for a unenhanced NTX index. If the index is created as a conditional index it will have a signature of 7 hex (6 hex ORed with 1 hex). If the index is created as a temporary index it will have a signature of E hex. (6 hex ORed with 8 hex). See Figure 7-1 for an illustration of all the possible values for the signature byte.

Error Handling

Corruption Detected

Since older applications have no knowledge of the new index features nor how to interpret the additional flags in the header signature, these applications will assume the index is corrupt and will produce an Index Corrupted error.

EOF()

If an index is created with a FOR condition and an attempt is made to update the index with a key that does not match the condition, the update is suppressed and the index is placed at EOF(). This is consistent with the current behavior for indexes created with the unique flag when an update is attempted with a non-unique key.

Also if a navigational action is attempted (SKIP) and the current record is not found in the index, the index will place the record pointer at EOF(). This is true for both conditional and temporary indexes.

Compatibility

Backward Compatibility

If the conditional or temporary indexing features are used the index produced will not be backward compatible with applications compiled with previous versions of Clipper. Indexes that do not use the features, however, will be 100% compatible.

Forward Compatibility

Indexes created by applications built with a previous version of Clipper can be used by Clipper 5.2 and will not be modified unless the index is recreated using either the conditional or temporary index features.

Error Message Produced by Old Applications

Since older applications have no knowledge of the new index locking scheme nor of the significance of the header signature, these applications will assume the index is corrupt and will produce an Index Corrupted error.

Installing DBFNTX Driver Files

DBFNTX is supplied as the file DBFNTX.LIB.

The Clipper installation program installs this driver as the default in the \CLIPPER5\LIB subdirectory on the drive that you specify, so you need not install the driver manually.

Important! Before installing Clipper, you may want to rename the DBFNTX.LIB that currently resides in your \CLIPPER5\LIB directory to DBFNTX.001. The new version, when installed, will overwrite DBFNTX.LIB. If you do not rename or otherwise protect the old version of DBFNTX.LIB, you will lose it.

Linking the DBFNTX Database Driver

Since DBFNTX is the default database driver for Clipper, there are no special instructions for linking. Unless you specify the /R option when you compile, the new driver will be linked into each program automatically if you specify a USE command or DBUSEAREA() function without an explicit request for another database driver. The driver is also linked if you specify an INDEX or REINDEX command with any of the new features.

Using the DBFNTX Database Driver

In applications written for the new DBFNTX driver, you can use the INDEX and REINDEX commands exactly as you have used them in the past. The index files (.ntx) you create and maintain in this way are completely compatible with those created using previous versions of the driver.

Changes to existing code are necessary only if you use the new indexing features. The (.ntx) files you create using the new features will have a slightly different header file and cannot be used by programs linked with a previous version of the driver.

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

You can use (.ntx) and (.ndx) files concurrently in a Clipper program 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, that you cannot use (.ntx) and (.ndx) files in the same work area. For example, the following does not work:

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

Compatibility with dBASE III PLUS

The default DBFNTX driver makes Clipper programs behave differently than traditional dBASE programs. Some of these differences are discussed below.

Supported Data Types

The DBFNTX database driver supports the following dBASE III PLUS- compatible data types for key expressions:

. Character

. Numeric

. Date

. Logical

Supported Key Expressions

When you create (.ntx) files using the DBFNTX driver, you can use all Clipper or user-defined functions compatible with dBASE III PLUS as well as other functions accepted by the extended Clipper functionality.

Error Handling

The indexing behavior of DBFNTX and DBFNDX in a Clipper application is identical unless otherwise noted. With the default DBFNTX driver, you can handle most errors using BEGIN SEQUENCE…END SEQUENCE as illustrated in the next section.

FIND vs SEEK

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

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

The DBFNTX driver lets you recover from data type errors raised during a FIND or SEEK. However, since Error:canDefault, Error:canRetry or Error:canSubstitute are set to false (.F.), you should use BEGIN SEQUENCE…END to handle such SEEK or FIND data type errors. Within the error block for the current operation, issue a BREAK() using the error object that the DBFNTX database driver generates, like this:

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

There is an extensive discussion of the effective use of the Clipper error system in the Error Handling Strategies chapter of the Programming and Utilities guide.

Sharing Data on a Network

The DBFNTX driver provides file and record locking schemes that are different from dBASE III PLUS schemes. This means that if the same database and index files are open in Clipper and in dBASE III PLUS, Clipper program locks are not visible to dBASE III PLUS and vice versa.

Warning! Database integrity is not guaranteed and index corruption will occur if Clipper and dBASE III PLUS programs attempt to write to a database or index file at the same time. Therefore, concurrent use of the same database (.dbf) and index (.ndx) files by dBASE III PLUS and Clipper programs is strongly discouraged and not supported by Computer Associates.

Summary

In this chapter, you were given an overview of the new features of the default DBFNTX RDD. You learned how to this driver is automatically linked and how to use it in your applications, and were given an overview of the compatiblity issues.

C5DG-6 DBFNDX Driver

Clipper 5.x – Drivers Guide

Chapter 6

DBFNDX Driver Installation and Usage

DBFNDX is the dBASE III PLUS compatible RDD for Clipper. The DBFNDX driver uses the Clipper driver architecture to access dBASE III PLUS compatible index files within a Clipper program.

In This Chapter

This chapter explains how to install DBFNDX and how to use it in your applications. The following major topics are discussed:

. Overview of the DBFNDX RDD

. Installing DBFNDX Driver Files

. Linking the DBFNDX Driver

. Using the DBFNDX Driver

. Compatibility with dBASE III PLUS

Overview of the DBFNDX RDD

The DBFNDX database driver allows creation, access, and updating of dBASE III and dBASE III PLUS compatible index (.ndx) files. Index files (.ndx) created with Clipper are exactly 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 using 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 programs is not supported.

Important! Updating database (.dbf) and index (.ndx) files shared between dBASE III PLUS and Clipper programs may corrupt the (.dbf) and any of its associated (.ndx) files.

Installing DBFNDX Driver Files

The DBFNDX database driver is supplied as the file, DBFNDX.LIB.

The Clipper installation program installs this driver in the \CLIPPER5\LIB subdirectory on the drive that you specify, so you need not install the driver manually.

Linking the DBFNDX Database Driver

To link the DBFNDX database driver into an application program, you must specify DBFNDX.LIB to the linker in addition to your application object files (.OBJ).

1. To link with .RTLink using positional syntax:

C>RTLINK <appObjectList> ,,, DBFNDX

2. To link with .RTLink using freeformat syntax:

C>RTLINK FI <appObjectList> LIB DBFNDX

Note: These link commands all assume the LIB, OBJ, and PLL environment variables are set to the standard locations. They also assume that the Clipper programs were compiled without the /R option.

Using the DBFNDX Database Driver

To use (.ndx) files in a Clipper program:

1. Place a REQUEST DBFNDX at the beginning of your application or at the top of the first program file (.prg) that opens a database file using the DBFNDX driver.

2. Specify the VIA “DBFNDX” clause if you open the database file with the USE command.

-OR-

3. Specify “DBFNDX” for the <cDriver> argument if you open the database file with the DBUSEAREA() function.

-OR-

4. Use RDDSETDEFAULT(“DBFNDX”) to set the default driver to DBFNDX.

Except in the case of REQUEST, the RDD name must be a literal character string or a variable. In all cases it is important that the driver name be spelled correctly.

The following program fragments illustrate:

REQUEST DBFNDX 
. 
. 
. 
USE Customers INDEX Name, Address NEW VIA "DBFNDX"

-OR-

REQUEST DBFNDX RDDSETDEFAULT( "DBFNDX" ) 
.
.
. 
USE Customers INDEX Name, Address NEW

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

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

REQUEST DBFNDX

// (.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, that you cannot use (.ndx) and (.ntx) files in the same work area. For example, the following does not work:

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

Compatibility with dBASE III PLUS

When accessing dBASE III PLUS (.ndx) files, there are several compatibility issues of which you must be aware. These issues are discussed below.

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.

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

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

INDEX ON IIF(<lExp>, "T", "F") TO <logicalIndex>

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.

FIND vs SEEK

In Clipper, you can use the FIND command only 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 programs, always use the SEEK command or the DBSEEK() function to search an index for a key value.

The DBFNDX driver lets you recover from a data type error raised during a FIND or SEEK. However, since Error:canDefault, Error:canRetry, or Error:canSubstitute are set to false (.F.), 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)

There is an extensive discussion of the effective use of the Clipper error system in the Error Handling Strategies chapter of the Programming and Utilities guide.

Sharing Data 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 and dBASE III PLUS, Clipper program locks are not visible to dBASE III PLUS and vice versa.

Warning! Database integrity is not guaranteed and index corruption will occur if Clipper and dBASE III PLUS programs attempt to write to a database or index file at the same time. For this reason, concurrent use of the same database (.dbf) and index (.ndx) files by dBASE III PLUS and Clipper programs is strongly discouraged and not supported.

Compatibility with dBASE IV

Specific compatibility with dBASE IV is provided through the DBFMDX driver. It includes (.dbf), (.mdx), and (.dbt) file format compatibility and is described in detail in the previous chapter.

Summary

In this chapter, you were given an overview of the features and benefits of the DBFNDX RDD. You learned how to link this driver and how to use it in your applications, and were given an overview of the compatibility issues.

C5DG-5 DBFMDX Driver

Clipper 5.x – Drivers Guide

Chapter 5

DBFMDX Driver Installation and Usage

DBFMDX is the dBASE IV compatible RDD for Clipper. This driver provides (.dbf), (.dbt), and (.mdx) file format compatibility.

In This Chapter

This chapter explains how to install DBFMDX and how to use it in your applications. The following major topics are discussed:

. Overview of the DBFMDX RDD

. Installing DBFMDX Driver Files

. Linking the DBFMDX Driver

. Using the DBFMDX Driver

Overview of the DBFMDX RDD

The DBFMDX database driver provides dBASE IV compatibility, including access to (.dbf), (.mdx), and (.dbt) file formats. The driver also supports dBASE IV compatible file and record locking schemes, allowing shared access between Clipper and dBASE IV programs.

Installing DBFMDX Driver Files

The DBFMDX database driver is supplied as the file, DBFMDX.LIB.

The Clipper installation program installs this driver in the \CLIPPER5\LIB subdirectory on the drive that you specify, so you need not install the driver manually.

Linking the DBFMDX Database Driver

To link the DBFMDX database driver into an application program, you must specify DBFMDX.LIB to the linker in addition to your application object files (.OBJ).

1. To link with .RTLink using positional syntax:

     C>RTLINK <appObjectList> ,,,DBFMDX

2. To link with .RTLink using freeformat syntax:

         C>RTLINK FI <appObjectList> LIB DBFMDX

Note: These link commands all assume the LIB, OBJ, and PLL environment variables are set to the standard locations. They also assume that the Clipper programs were compiled without the /R option.

Using the DBFMDX Database Driver

To use (.mdx) files in a Clipper program:

1. Place REQUEST DBFMDX at the beginning of your application or at top of the first program file (.prg) that opens a database file using the DBFMDX driver.

2. Specify the VIA “DBFMDX” clause if you open the database file with the USE command.

-OR-

3. Specify “DBFMDX” for the <cDriver> argument if you open the database file with the DBUSEAREA() function.

-OR-

4. Use RDDSETDEFAULT(“DBFMDX”) to set the default driver to DBFMDX.

Except in the case of REQUEST, the RDD name must be a literal character string or a variable. In all cases it is important that the driver name be spelled correctly using uppercase letters.

Though the DBFMDX driver supports numbered indexes, you should avoid using them (e.g., in operations like SET ORDER and INDEXKEY()). In a multiple-index system you do not have the absolute control of the numeric position of an open index that you have in a single-index system. As you add, delete, and rebuild index TAGs, their numeric position may change. You should make all command references by name. For example:

SET ORDER TO [<nOrder> | [TAG <cOrderName>] [IN <xcOrderBagName>]]

Summary

In this chapter, you were given an overview of the features and benefits of the DBFMDX RDD. You also learned how to link this driver and how to use it in your applications.

C5DG-4 DBFCDX Driver

Clipper 5.x – Drivers Guide

Chapter 4

DBFCDX Driver Installation and Usage

DBFCDX is the FoxPro 2 compatible RDD for Clipper. As such, it connects to the low-level database management subsystem in the Clipper architecture. When you use the DBFCDX RDD, you add a number of new features including:

. FoxPro 2 file format compatibility

. Compact indexes

. Compound indexes

. Conditional indexes

. Memo files smaller than DBFNTX format

In This Chapter

This chapter explains how to install DBFCDX and how to use it in your applications. The following major topics are discussed:

. Overview of the DBFCDX RDD

. Installing DBFCDX Driver Files

. Linking the DBFCDX Driver

. Using the DBFCDX Driver

Overview of the DBFCDX RDD

The DBFCDX driver lets you create and maintain (.cdx) and (.idx) files with features different from those supplied with the original DBFNTX driver and is compatible with files created under FoxPro 2. The new features are supplied in the form of several syntactical additions to the INDEX and REINDEX commands. Specifically, you can:

. Create indexes smaller than those created with the DBFNTX
driver. The key data is stored in a compressed format that
substantially reduces the size of the index file.

. Create a compound index file that contains multiple indexes
(TAGs), making it possible to open several indexes under one file
handle. A single (.cdx) file may contain up to 99 index keys.

. Create conditional indexes (FOR / WHILE / REST / NEXT).

. Create files with FoxPro 2 file format compatibility.

Compact Indexes

Like FoxPro 2, The DBFCDX driver creates compact indexes. This means that the key data is stored in a compressed format, resulting in a substantial size reduction in the index file. Compact indexes store only the actual data for the index keys. Trailing blanks and duplicate bytes between keys are stored in one or two bytes. This allows considerable space savings in indexes with much empty space and similar keys. Since the amount of compression is dependent on many variables, including the number of unique keys in an index, the exact amount of compression is impossible to predetermine.

Compound Indexes

A compound index is an index file that contains multiple indexes (called tags). Compound indexes (.cdx)’s make several indexes available to your application while only using one file handle. Therefore, you can overcome the Clipper index file limit of 15. A compound index can have as many as 99 tags, but the practical limit is around 50. Once you open a compound index, all the tags in the file are automatically updated as the records are changed.

Once you open a compound index, all the tags contained in the file are automatically updated as the records are changed. A tag in a compound index is essentially identical to an individual index (.idx) and supports all the same features. The first tag (in order of creation) in the compound index is, by default, the controlling index.

Conditional Indexes

The DBFCDX driver can create indexes with a built-in FOR clause. These are conditional indexes in which the condition can be any expression, including a user-defined function. As the database is updated, only records that match the index condition are added to the index, and records that satisfied the condition before, but don’t any longer, are automatically removed.

Expanded control over conditional indexing is supported with the revised INDEX and REINDEX command options as in the new DBFNTX driver.

Installing DBFCDX Driver Files

The DBFCDX driver is supplied as the file, DBFCDX.LIB.

The Clipper installation program installs this driver in the \CLIPPER5\LIB subdirectory on the drive that you specify, so you need not install the driver manually.

Linking the DBFCDX Database Driver

To link the DBFCDX database driver into an application program, you must specify DBFCDX.LIB to the linker in addition to your application object files (.OBJ).

1. To link with .RTLink using positional syntax:

C>RTLINK <appObjectList> ,,,DBFCDX

2. To link with .RTLink using freeformat syntax:

C>RTLINK FI <appObjectList> LIB DBFCDX

Note: These link commands all assume the LIB, OBJ, and PLL environment variables are set to the standard locations. They also assume that the Clipper programs were compiled without the /R option.

Using the DBFCDX Database Driver

To use FoxPro 2 files in a Clipper program:

1. Place REQUEST DBFCDX at the beginning of your application or at the top of the first program file       (.prg) that opens a database file using the DBFCDX driver.

2. Specify the VIA “DBFCDX” clause if you open the database file with the USE command.

    -OR-

3. Specify “DBFCDX” for the <cDriver> argument if you open the database file with the DBUSEAREA()       function.

   -OR-

4. Use ( “DBFCDX” ) to set the default driver to DBFCDX.

    Except in the case of REQUEST, the RDD name must be a literal character string or a variable. In all       cases it is important that the driver name be spelled correctly.

The following program fragments illustrate:

  REQUEST DBFCDX
  .
  .
  .
  USE Customers INDEX Name, Address NEW VIA "DBFCDX"

     -OR-

  REQUEST DBFCDX
  RDDSETDEFAULT( "DBFCDX" ) .
  . 
  .
  USE Customers INDEX Name, Address NEW

Using (.idx) and (.ntx) Files Concurrently

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

// (.ntx) file using default DBFNTX driver
 USE File1 INDEX File1 NEW
// (.idx) files using DBFCDX driver
 USE File2 VIA "DBFCDX" INDEX File2 NEW

Note, however, that you cannot use (.idx) and (.ntx) files in the same work area. For example, the following does not work:

USE File1 VIA "DBFNTX" INDEX File1.ntx, File2.idx

Using (.cdx) and (.idx) Files Concurrently

You may use (.cdx) with (.idx) files concurrently (even in the same work area); however, in most cases it is easier to use a single (.cdx) index for each database file or separate (.idx) files. When using both types of index at the same time, attempting to select an Order based on its Order Number can be confusing and will become difficult to maintain.

File Maintenance under DBFCDX

When an existing tag in a compound index (.cdx) is rebuilt using INDEX ON…TAG… the space used by the original tag is not automatically reclaimed. Instead, the new tag is added to the end of the file, increasing file size.

You can use the REINDEX command to “pack” the index file. REINDEX rebuilds each tag, eliminating any unused space in the file.

If you rebuild your indexes on a regular basis, you should either delete your (.cdx) files before rebuilding the tags or use the REINDEX command to rebuild them instead.

DBFCDX and Memo Files

The DBFCDX driver uses FoxPro compatible memo (.fpt) files to store data for memo fields. These memo files have a default block size of 64 bytes rather than the 512 byte default for (.dbt) files.

DBFCDX memo files can store any type of data. While (.dbt) files use an end of file marker (ASCII 26) at the end of a memo entry, (.fpt) files store the length of the entry. This not only eliminates the problems normally encountered with storing binary data in a memo field but also speeds up memo field access since the data need not be scanned to determine the length.

Tips For Using DBFCDX

1. Make sure index extensions aren’t hard-coded in your application. The default extension for DBFCDX indexes is (.idx), not (.ntx). You can still use (.ntx) as the extension as long as you specify the extension when you create your indexes. The best way to determine index extensions in an application is to call ORDBAGEXT().

For example, if you currently use the following code to determine the existence of an index file:

IF .NOT. FILE("index.ntx")
    INDEX ON field TO index
ENDIF

Change the code to include the INDEXEXT() function, as follows:

IF .NOT. FILE("index"+ORDBAGEXT())
   INDEX ON field TO index
ENDIF

2. If your application uses memo fields, you should convert your (.dbt) files to (.fpt) files.

There are some good reasons for using (.fpt) files. Most important is the smaller block size (64 bytes). Clipper’s (.dbt) files use a fixed block size of 512 bytes which means that every time you store even 1 byte in a memo field Clipper uses 512 bytes to store it. If the data in a memo field grows to 513 bytes, then two blocks are required.

When creating (.fpt) files, the block size is set at 64 bytes to optimize it for your needs. A simple conversion from (.dbt) files to (.fpt) files will generally shrink your memo files by approximately 30%.

3. Add DBFCDX.LIB as a library to your link command or link script.

Summary

In this chapter, you were given an overview of the features and benefits of the DBFCDX RDD. You also learned how to link this driver and how to use it in your applications.

C5DG-3 RDD Reference

Clipper 5.x – Drivers Guide

Chapter 3

RDD Reference

 

APPEND FROM     Import records from a (.dbf) or ASCII file                  
COPY TO         Export records to a new (.dbf) or ASCII file                
DBAPPEND()      Append a new record to the database in the current work area
DBGOTO()        Position record pointer to a specific identity              
DBRLOCK()       Lock the record at the current or specified identity        
DBRLOCKLIST()   Return an array of the current Lock List                    
DBRUNLOCK()     Release all or specified record locks                       
DBSETINDEX()*   Empty Orders from an Order Bag into the Order List          
DELETE TAG      Delete a Tag                                                
GO              Move the pointer to the specified identity                  
INDEX           Create an index file                                        
ORDBAGEXT()     Return the default Order Bag RDD extension                  
ORDBAGNAME()    Return the Order Bag name of a specific Order               
ORDCREATE()     Create an Order in an Order Bag                             
ORDDESTROY()    Remove a specified Order from an Order Bag                  
ORDFOR()        Return the FOR expression of an Order                       
ORDKEY()        Return the key expression of an Order                       
ORDLISTADD()    Add Orders to the Order List                                
ORDLISTCLEAR()  Clear the current Order List                                
ORDLISTREBUI()  Rebuild all Orders in Order List of the current work area   
ORDNAME()       Return the name of an Order in the Order List               
ORDNUMBER()     Return the position of an Order in the current Order List   
ORDSETFOCUS()   Set focus to an Order in an Order List                      
RDDLIST()       Return an array of available Replaceable Database Drivers   
RDDNAME()       Return name of RDD active in current or specified work area 
RDDSETDEFAULT() Set or return the default RDD for the application           
RECNO()         Return the identity at the position of the record pointer   
SEEK            Search an Order for a specified key value                   
SET INDEX       Open one or more Order Bags in the current work area        
SET ORDER       Select the controlling Order