NTXDBE (ORDER component) Foundation

The DatabaseEngine NTXDBE manages index files in the NTX format. This is the native Clipper index file format and used as the default format for building indexes in Xbase++. The default can be changed by modifying the file DBESYS.PRG in the ..\SOURCE\SYS directory. The DbeSys() function in this file is automatically called at program start, prior to the Main procedure. A customized DBESYS.PRG must then be linked explicitly to the EXE file.

The NTX file format has undergone changes. The NTXDBE supports the NTX file format as it is defined by Clipper 5.2 and higher. An overview of its features is listed below:

Clipper compatibility issue regarding tag names

The NTXDBE uses as default value for the TAG option in the INDEX command the name of the index file without extension. As a consequence, index file names cannot differ only by extension unless the TAG option is used in the INDEX command. For example, this is illegal:

INDEX ON Lastname TO Name.nt1 
INDEX ON Firstname TO Name.nt2 
SET INDEX TO Name.nt1, Name.nt2 

In this case, "Name" is used implicitly as TAG name for two indexes which results in a runtime error. This can be solved by specifying two different tag names:

INDEX ON Lastname  TAG Last  TO Name.nt1 
INDEX ON Firstname TAG First TO Name.nt2 
SET INDEX TO Name.nt1, Name.nt2 

NTXDBE and runtime collation tables

The NTX DatabaseEngine uses the collation settings of the Xbase++ runtime to compare key-values and determine the sorting order. However, the NTX file format does not store any collation table specific information in the index header. Therefore great care must be exercised to setup the proper collation table using the SET COLLATION TO command when working with NTX files. Accessing the same NTX file using different collation tables will lead to indeterminate errors; e.g. key-values not found at seek or index corruption.

The NTX DatabaseEngine can be configured in specific ways using the function DbeInfo(). The following table gives an overview of the special #define constants that can be passed to the function DbeInfo() when the DatabaseEngine is NTXDBE:

The default values are shown in the column "Value".

DBE_LOCKMODE

This constant determines the locking mode used to manage implicit locks. Whenever an index is accessed, the NTX DatabaseEngine locks the NTX file to ensure data consistency. By default DBE_LOCKMODE is set to LOCKING_STANDARD - which ensures Clipper and/or FoxPro compatible behaviour. However this standard locking concept is not effective in modern network environments. Using LOCKING_EXTENDED does increase performance in network environments since mutual exclusion of applications accessing the same index file only is needed, whenever a write operation takes place.

NTXDBE_LOCKOFFSET

By default the offset for implicit locking is 1.000.000.000 (~1GB) which is compatible to all Clipper versions. Using the constant NTXDBE_LOCKOFFSET the offset can be changed to any value between 0 and 0xFFFFFFFF.

To handle index files larger than 1GB Clipper 5.2 and Clipper 5.3 come with a special object file NTXLOCK2.OBJ. Using this object file when linking a DOS Clipper application increases the locking offset from ~1GB to 0xFFFFFFFF (~4GB) for NTX files. To ensure compatibility with that type of Clipper NTX files the constant NTXDBE_LOCKOFFSET must be used to re-configure the offset of implicit locking of the NTX DatabaseEngine as shown in the code below:

DbeInfo( COMPONENT_ORDER, NTXDBE_LOCKOFFSET, 0xFFFFFFFF ) 

NTXDBE_LOCKRETRY

This constant determines the amount of lock retry operations before the NTX DatabaseEngine raises a runtime error when performing implicit locks. Implicit locks are set by the NTX DatabaseEngine by each navigational and update operation. The default value is 100.000.

NTXDBE_LOCKDELAY

This constant defines the delay in 1/100 seconds between each lock retry operation. The default value is 15 milliseconds. The workstations with a performance lower than the average workstation in the network, should use a delay value lesser than that of the faster workstation in the network. This will give the slower workstation a better chance to obtain a lock.