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:
|File size||Limited to the offset for record locks, the default is 1 GB (10^9 Bytes)|
|Data types||C, D, L, N, no memo|
|Max. length for:|
|- index expression||255 characters|
|- FOR expression||255 characters|
|- TAG name||10 characters|
|Indexes per file||One|
|WHILE expression||Supported *)|
|SET CHARSET||Index is based on the OEM character set|
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:
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:
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:
|DBE_LOCKMODE||a||LOCKING_STANDARD||#define||specifies implicit lock mode|
|NTXDBE_LOCKOFFSET||a||1 * 10^9||N||offset for implicit locking|
|NTXDBE_LOCKRETRY||a||100000||N||amount of implicit lock retries|
|NTXDBE_LOCKDELAY||a||15||N||delay between each lock retry|
The default values are shown in the column "Value".
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.
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:
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.
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.
If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please use this form to report a documentation issue.