From 4875a3dd9b183dcd2256e2abfc4ccf7484c233b4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=B6rg=20Frings-F=C3=BCrst?= Date: Wed, 7 Dec 2022 13:17:14 +0100 Subject: New upstream version 4.0.2 --- docs/html/index.htm | 33 +++++++ docs/html/xbase.jpg | Bin 0 -> 6421 bytes docs/html/xbbib.htm | 63 +++++++++++++ docs/html/xbc1.htm | 185 ++++++++++++++++++++++++++++++++++++ docs/html/xbc10.htm | 12 +++ docs/html/xbc11.htm | 12 +++ docs/html/xbc12.htm | 72 ++++++++++++++ docs/html/xbc13.htm | 46 +++++++++ docs/html/xbc14.htm | 12 +++ docs/html/xbc15.htm | 34 +++++++ docs/html/xbc2.htm | 267 ++++++++++++++++++++++++++++++++++++++++++++++++++++ docs/html/xbc3.htm | 73 ++++++++++++++ docs/html/xbc4.htm | 80 ++++++++++++++++ docs/html/xbc5.htm | 205 ++++++++++++++++++++++++++++++++++++++++ docs/html/xbc6.htm | 137 +++++++++++++++++++++++++++ docs/html/xbc7.htm | 153 ++++++++++++++++++++++++++++++ docs/html/xbc8.htm | 79 ++++++++++++++++ docs/html/xbc9.htm | 179 +++++++++++++++++++++++++++++++++++ 18 files changed, 1642 insertions(+) create mode 100755 docs/html/index.htm create mode 100755 docs/html/xbase.jpg create mode 100755 docs/html/xbbib.htm create mode 100755 docs/html/xbc1.htm create mode 100755 docs/html/xbc10.htm create mode 100755 docs/html/xbc11.htm create mode 100755 docs/html/xbc12.htm create mode 100755 docs/html/xbc13.htm create mode 100755 docs/html/xbc14.htm create mode 100755 docs/html/xbc15.htm create mode 100755 docs/html/xbc2.htm create mode 100755 docs/html/xbc3.htm create mode 100755 docs/html/xbc4.htm create mode 100755 docs/html/xbc5.htm create mode 100755 docs/html/xbc6.htm create mode 100755 docs/html/xbc7.htm create mode 100755 docs/html/xbc8.htm create mode 100755 docs/html/xbc9.htm (limited to 'docs/html') diff --git a/docs/html/index.htm b/docs/html/index.htm new file mode 100755 index 0000000..3c992f5 --- /dev/null +++ b/docs/html/index.htm @@ -0,0 +1,33 @@ + +Xbase DBMS Documentation Table of Contents + +

Xbase DBMS
+Last Updated 11/21/22
Version 4.x.x

Documentation Table Of Contents

Section 1 - Xbase Concepts

+Chapter 1 - Getting Started
+Chapter 2 - Database Overview
+Chapter 3 - Fields and Strings
+Chapter 4 - Date Processing
+Chapter 5 - Expression Handling
+Chapter 6 - Index Overview
+Chapter 7 - NDX (DBase) Indices
+Chapter 8 - MDX (DBase) Indices
+Chapter 9 - NTX (Clipper) Indices
+Chapter 10 - CDX (FoxPro) Indices
+Chapter 11 - IDX (FoxPro) Indices
+Chapter 12 - Record and File Locking
+Chapter 13 - Logfile Support
+Chapter 14 - SQL Support
+Chapter 15 - Utility programs
+ +

Section 3 - Appendices

+Appendix C - GPL Library License
+Appendix D - Bibliography
+

+ + diff --git a/docs/html/xbase.jpg b/docs/html/xbase.jpg new file mode 100755 index 0000000..5070fcb Binary files /dev/null and b/docs/html/xbase.jpg differ diff --git a/docs/html/xbbib.htm b/docs/html/xbbib.htm new file mode 100755 index 0000000..70e4e82 --- /dev/null +++ b/docs/html/xbbib.htm @@ -0,0 +1,63 @@ + + +Xbase DBMS Bibliography + +

Xbase DBMS Bibliography

Page Updated 2/1/99

+ +Bachman, Erik
+Xbase File Format Description / Erik Bachman, Roskilde, Denmark: Clickety +Click Software, 1996-1998, 44 pages

+ +Loomis, Mary:
+The Database Book, Macmillan Publishing Company, 1987, New York, New York: +ISBN 0-02-371760-2

+ +Dorfman, Len:
+Building C Libraries, Windcrest, 1990, Blue Ridge Summit, PA: +ISBN 0-8306-3418-5

+ +Eckel, Bruce:
+Using C++, Osborne, McGraw-Hill, 1990, Berkeley, CA: +ISBN 0-07-881522-3

+ +Aho, Alfred: Hopcroft, John: Ullman, Jeffrey:
+Data Structures and Algorithms, Addison-Wesley Publishing, 1983, +Reading Massachusetts: ISBN 0-201-00023-7

+ +Stevens, Al:
+C Database Development, MIS Press, 1991, Portland Oregon: +ISBN 1-55828-136-3

+ +Pressman, Roger:
+Software Engineering: A Practitioner's Approach, McGraw-Hill, 1982, +New York ISBN 0-07-050781-3

+ +Chou, George Tsu-der:
+2nd Edition dBase III Plus Handbook: Que Corporation, 1986, +Indianapolis, Indiana ISBN 0-88022-269-7

+ +Krumm, Rob:
+Understanding and Using dBase II & III, Brady Communications Company, Inc, +1985, Bowie MD ISBN 0-89303-917-9

+ +Hursch, Jack: Hursch, Carulyn:
+dBase IV Essentials, Windcrest, 1988, Blue Ridge Summit, PA +ISBN 0-8306-9616-4

+ +Borland:
+Turbo C++, Programmer's Guide, Borland International, 1990, +Scotts Valley CA

+ +Borland:
+Turbo C++, Library Reference, Borland International 1990, +Scotts Valley CA

+ +The Draft Standard C++ Library by P.J. Plauger, Prentice Hall, New Jersey, +1995.

+ +H.M Dietel/P.J. Deitel: C++ How To Program, Prentice Hall, Englewod Cliffs, +New Jersey 07632

+ + + diff --git a/docs/html/xbc1.htm b/docs/html/xbc1.htm new file mode 100755 index 0000000..bb04aec --- /dev/null +++ b/docs/html/xbc1.htm @@ -0,0 +1,185 @@ + + +Xbase DBMS Chapter 1 + + +

Getting Started

Chapter Updated 11/21/22

+ +

Overview

+ +Welcome to Xbase64 DBMS, a collection of specifications, programs, +utilities and a C++ class library for manipulating legacy Xbase (DBF) type +data files and indices. +

+ +The term Xbase is often used used to describe the format of the original +DBase, Clipper and Foxbase (.DBF) files. The XBase file format is well +documented and has stood the test of time. Various popular programs +still create and read xbase formatted files.

+ +The purpose of the Xbase64 library is to provide reliable and usable +programming tools for reading, writing and updating DBF databases, +indices and memo fields. Version 4.x.x has been tested for compatability +with DBase III (TM) and DBase IV (TM) version data files and indices +*.DBF (data), *.NDX (single tag index), *.MDX (multi tag index) and +*.DBT (memo).

+ +Version 4.x.x is a major rewrite of the library to strenghen error +processing and bring consistency across modules. It includes updates +to the locking process and also includes a module to support MDX multi +tag indices.

+ +Earlier versions of the library have included NTX and CDX index formats +and that code will be re-incorporated into the latest version in the +future. + + + +

+ +

System Requirements

+ +To build the Xbase64 library, the following items are needed:

+ +A computer, a C/C++ compiler and CMAKE.

+ +The original source code was developed on a Linux platform with the GCC +public domain C/C++ compiler. +

+ +Xbase64 DBMS has been successfully ported and runs on Linux, Mac and and Windows. +

+ +

Classes and User Interface

+ +Classes and User Interface Documentation via Doxygen + +

+

Portability, Type Defs and Structures

+ +To make the Xbase64 library as portable as possible, the following things occurred: +

+

The software was developed to compile and run on either 32 or 64 bit architectures. +

The software was developed to compile and run on either big endian or little endian archtectures. +

All numeric data is stored in little endian format. +

The library is built using Cmake to provide support on a wide variety of platforms. +

Field types were defined to be consistent across various OS and CPU configurations. +Xbase64 defines the following field types:

+ + + + +

Field Types
Type	Description +
xbInt16	16 bit int +
xbUInt16	16 bit unsigned int +
xbInt32	32 bit int +
xbUInt32	32 bit unsigned int +
xbInt64	64 bit int +
xbUInt64	64 bit unsigned int +
xbDouble	double +
char	char +
void	void +
struct SCHEMA	Used for defining record structures +

+

+ +Xbase64 was designed for portability utilizing standard ANSI-C/C++ compliant +code. If you decide to write updates to the Xbase64 project, please try +to keep your work to standard C/C++ generic calls and use the above predefined field types.

+ +

Compilation Overview

+To build the xbase64 library, verify you have:
+

Xbase64 source code +

cmake 2.6 or LATER +

Compiler and linker + +

+Verify you have access rights to the target location of the library + +

+For Linux: +

+

cd xbase/Linux +

cmake . +

make +

make test +

sudo make install +

Verify the ld.so.conf file has the library target directory. For example +update file /etc/ld.so.conf to include /usr/local/lib and run ldconfig. +

+ +For Mac: +

+

Verify you have xcode installed and operational. +

cd xbase/Mac +

cmake . -DCMAKE_OSX_SYSROOT=/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.11.sdk +

make +

make test +

+ +For Windows 64 bit with Visual Studio: +

+

Open a Visual Studio 64 bit Shell +

cd xbase\Win64VS +

buildwin.bat +

nmake test +

From a VS Studio 64 bit shell in admin mode: nmake install +

+ +For Windows 32 bit with Visual Studio: +

+

Open a Visual Studio 32 bit Shell +

cd xbase\Win32VS +

buildwin.bat +

nmake test +

From a VS Studio 32 bit shell in admin mode: nmake install +

+ +For Windows 32 bit with Borland 5.5 free compiler +

+

cd xbase\Win32Borland +

BuildBorland.bat +

make test +

+ +For other platforms: +

+Here is something to start with... +

cd xbase +

md MyPlatform +

cd MyPlatform +

cp ../Cmake/CmakeLists.txt. +

Enter the appropriate make command for your environment. Check the cmake web site for help.
+ On Linux, it is .cmake, then make + your mileage may vary + + Send your results to the library maintainer so it can be added to this library + + + +To use the Xbase classes, include the following header file in the program: +

+ +#include <xbase.h>

+ +For more information on getting started, check out the sample programs in the src/examples folder. +

+ +

System Limitations

+
+Maximum size of a database file is the size of LONG - 2,147,483,647 bytes
+Total number of fields in a database - 255
+Total number of characters in all fields - 32767
+Maximum number of characters in a field - 254
+Total number of records in a file - 1 billion
+Maximum index key length - 100 bytes
+Maximum .DBT file memo block size - 32256
+Maximum expression result length - 100 bytes
+Maximum NDX index key length - 100 bytes

+

+ +

+ + diff --git a/docs/html/xbc10.htm b/docs/html/xbc10.htm new file mode 100755 index 0000000..04f5158 --- /dev/null +++ b/docs/html/xbc10.htm @@ -0,0 +1,12 @@ + + +Xbase DBMS Chapter 10 + +

CDX Indices

Chapter Updated 11/28/22

+ +

Pending CDX index module development.

+ +

+ + diff --git a/docs/html/xbc11.htm b/docs/html/xbc11.htm new file mode 100755 index 0000000..4230f3f --- /dev/null +++ b/docs/html/xbc11.htm @@ -0,0 +1,12 @@ + + +Xbase DBMS Chapter 10 + +

CDX Indices

Chapter Updated 11/28/22

+ +

Pending IDX index module development.

+ +

+ + diff --git a/docs/html/xbc12.htm b/docs/html/xbc12.htm new file mode 100755 index 0000000..f9fe114 --- /dev/null +++ b/docs/html/xbc12.htm @@ -0,0 +1,72 @@ + + +Xbase DBMS Chapter 8 + +

Record and File Locking

Chapter Updated 11/29/22

+ +

Locking Overview

+ +Xbase64 supports multi-user processing through file and record locks. +Record locking restricts multiple cooperating programs from simultaneously +accessing the same data and corrupting it. Without record and file locking +in a multi-user environment, simultaneous access to the data and index files +can cause the files to become inaccurate and unusable.

+ +Automatic record locking is on by default in the Xbase64 library. To disable it, +use method xbXBase::DisableDefaultAutoLock() and to enable it, use method xbXBase::EnableDefaultAutoLock(). + +Locking can also be enabled / disabled at the table level with with xbDbf::SetAutoLock(). + + +

+The current Xbase64 record locking logic is modeled after DBase (tm) V7 locking. +

+ +The locking methods return either XB_LOCK_FAILED or XB_NO_ERROR. If they return +XB_LOCK_FAILED the actual reason can be found in the global variable +errno or function perror() can be executed to view the +results. +

+ +The errno field may contain one of the following values if the lock was not +successful.

+ + +

Error Code	Description +
EBADF	Invalid file descriptor +
EINVAL	Invalid lock information or file does not support locks +
EACCESS EAGAIN	Lock can not be set because it is blocked by an existing lock on the file. +
ENOLCK	The system is out of lock resources, too many file locks in place. +
EDEADLK	Deadlock condition +
EINTR	Process was interrupted by a signal while it was waiting +

+

+ +

Linux/Windows File Locking Compatibility Issue

+ +There is a compatibility locking issue to be aware of. Windows environments allow for the exclusive +opening of file handles and Linux/Unix platforms do not. If you are writing an application that will be +using a tool like Dbase on a Windows machine, accessing a file on a Linux/Samba configure machine, +be aware that the file could be opened in exclusive mode by DBase on the Windows system, and the same file could +be simultaneously opened with a program on the Unix box. That could cause some issues. + +

+In Unix, a program can not lock a file so another process can not access it.
+In Windows, a program can lock a file so another process can not access it.
+DBase(tm) supports routines to open files exclusively, preventing other users from opening a file.
+ +

Samba settings

+ +If you will be using Samba on Linux/Unix and sharing files between Linux and Windows machines, +you will need to disable oplocks. In the smb.conf file, set:
+

oplocks = no

+ + + + +
+

+ + diff --git a/docs/html/xbc13.htm b/docs/html/xbc13.htm new file mode 100755 index 0000000..9f51a85 --- /dev/null +++ b/docs/html/xbc13.htm @@ -0,0 +1,46 @@ + + + +Xbase DBMS Chapter 13 + +

Logfiles

Chapter Updated 11/29/22

+ + +

Logging

+ +The Xbase library includes a logging module that can be turned on or off for auditing purposes. + +See example code below for how to use the logging routines. + +

+ +#include "xbase.h"
+using namespace xb;
+
+int main( int argCnt, char **av ){
+ + #ifdef XB_LOGGING_SUPPORT
+ xbString sMsg;
+ xbString sLogFileName;
+ xbXBase x;
+ sLogFileName = "/home/xbase/logfiles/LogFile.txt";
+ x.SetLogFileName( sLogFileName );
+ x.EnableMsgLogging();

+ + + std::cout << "Logfile is [" << x.GetLogFqFileName().Str() << "]" << std::endl;
+ sMsg.Sprintf( "Program [%s] initializing...", av[0] );
+ x.WriteLogMessage( sMsg );
+ std::cout << "Logging status is " << x.GetLogStatus() << std::endl;
+ sMsg = "A logfile message";
+ x.WriteLogMessage( sMsg );
+ x.DisableMsgLogging();
+ #endif /* XB_LOGGING_SUPPORT */
+ return 0;
+}
+ +

+ + diff --git a/docs/html/xbc14.htm b/docs/html/xbc14.htm new file mode 100755 index 0000000..fdcf949 --- /dev/null +++ b/docs/html/xbc14.htm @@ -0,0 +1,12 @@ + + +Xbase DBMS Chapter 14 + +

CDX Indices

Chapter Updated 11/30/22

+ +

Pending SQL module development.

+ +

+ + diff --git a/docs/html/xbc15.htm b/docs/html/xbc15.htm new file mode 100755 index 0000000..89bab09 --- /dev/null +++ b/docs/html/xbc15.htm @@ -0,0 +1,34 @@ + + +Xbase DBMS Chapter 15 + +

Sample Programs

Page Updated 11/30/22

+Sample Xbase DBMS programs include in the library.

+ + + + +

XBase Sample Programs
Program	Program Description +
xb_cfg_check	This program prints the compile settings and options in use +
xb_copydbf	This program copies a DBF file structure +
xb_dbfutil1	Menu program for executing Xbase functions +
xb_deletall	This program marks all records in a DBF file for deletion +
xb_dumpdbt	Debug memo files +
xb_dumphdr	This program opens an Xbase file and prints its header +
xb_dumprecs	This program dumps records for an X-Base file +
xb_ex_string	Example string program +
xb_ex_v3_create_dbf	Example program to create V3 DBF file +
xb_ex_v3_upd_dbf	Example program to update V3 DBF file +
xb_ex_v4_create_dbf	Example Program to create V4 DBF file +
xb_ex_v4_upd_dbf	Example program to update V4 DBF file +
xb_execsql	This program executes SQL statements +
xb_pack	This program packs (removes deleted records) from a DBF database file +
xb_undelall	This program undeletes all deleted records in a dbf file +
xb_zap	This program removes all records from a DBF file +

+

+

+ + diff --git a/docs/html/xbc2.htm b/docs/html/xbc2.htm new file mode 100755 index 0000000..72a6009 --- /dev/null +++ b/docs/html/xbc2.htm @@ -0,0 +1,267 @@ + + +Xbase DBMS Chapter 2 + +

Database Overview

Chapter Updated 11/21/22

+ +The objective of this chapter is to provide information regarding how +the database files are utilized and document the various record structures. +With the exception of the brief section on the record buffer, the +information presented in this chapter is not required to use the +Xbase library. It is mainly information describing internal file +structures utilized by the Xbase routines.

+ +Xbase DBF files are comprised of a variable length header record which stores +information about the file and describes +the fixed length record format, followed by a series of fixed length +data records. +

+ +Each fixed length data record is preceded by a one byte indicator +which identifiies if the record has been deleted. If the record is +not deleted, the indicator is a space (0x20). If deleted, the +indicator contains an asterisk (0x2A). Data fields are stored in records +without field separators or record terminators.

+ +In earlier releases of dBASE, there is an ASCII NULL character +between the $0D end of header indicator and the start of the data. +This NULL was removed starting with dBASE III Plus, making a Plus +header one byte shorter than an identically structured III file. +The methods documented in the Xbase software and documentation follow +the more recent version where the NULL character is not included. +

+ +Each database file is comprised of zero, one or many records. A record is +comprised of fields. Only one record is accessed at a time.

+ +Zero, one or many database files can be open simultaneously.

+ +

+ +

The Record Buffer

+ +When using the Xbase routines, each open data file has a record buffer +which is manipulated by calling the database, index and field routines. +

+ +If AutoCommit is turned on (Default), updates are committed from +the record buffer to the database when a write, or append is performed. +The library automatically writes updates to the database if the buffer has +been updated and the record is repositioned or the database is closed. +

+ +If AutoCommit is turned off, updates will need to be explicity +committed to the database file with one of dbf->Put(), dbf->Append() +or dbf->Commit() command depending on context.. +Updates can be cancelled with the Abort() command. +

+The record buffer is not used for handling the actual data portion of +memo fields. When working with memo fields, the application program must +allocate enough buffer space for reading and writing memo fields or use +the xbString class for handling memo data.

+ +Internal to the library, there is an additional record buffer which +stores the original value of the data record before any changes are made. +This is used by the index routines for finding and deleting original key +values from any open indices before adding the new keys. If the key values +are not changed, no index updates occur. Additionally, calling the Abort() +method will back out any updates to the record buffer. + + +

+ +

+
+

Xbase Database File Header - DBF Version III and Version IV

+ +The Xbase file header, located at the beginning of the database, describes +the .DBF database. Knowledge of this structure is not necessary to +effectively utilize the Xbase64 libraries.

+ + + +

Position	Length	Description +
0	1 byte	file 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 +
32-n	32 bytes each	field descriptor record (see below) +
n+1	1 byte	0DH as the field terminator +

+

+ +

+
+

Xbase Field Descriptor Record

+The Xbase field descriptor record stores information about each field in the +database. Each database has from 1 to 1024 fields. +Knowledge of this structure is not necessary to +effectively utilize the Xbase libraries.

+ + + +

Position	Length	Description +
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 +
16	1 byte	field length in binary +
17	1 byte	field decimal count in binary +
18-31	14 bytes	reserved bytes (version 1.00) +

+

+

+
+

Field Data Format

+Data are stored in ASCII format in the database as follows:

+ + +

DATA TYPE	DATA RECORD STORAGE +
Character	ASCII characters, left justified, right blank filled +
Date	(8 digits in YYYYMMDD format, such as + 19601007 for October 7, 1960) +
Logical	? Y y N n T t F f (? when not initialized) +
Memo	10 digits representing a .DBT block number +
Numeric	. 0 1 2 3 4 5 6 7 8 9 + -, right justified, left blank filled +
Float (Version IV only)	. 0 1 2 3 4 5 6 7 8 9 + -, right justified, left blank filled +

+

+ +

Memo Fields

+ +Memo fields store variable length data elements in a seperate .DBT file. +The main .DBF file maintains a ten byte field which is used by the Xbase +routines for determining the location of the data in the .DBT file. +

+ +Xbase DBMS supports both dBASE III+ and dBASE IV version memo files. +The version IV files are somewhat more efficient in that they reuse +unused memo space when data are deleted or freed from use. With version +III files, all new updates are appended to the end of the file and the +unused space is not reclaimed until the datafiles are packed. +

+ +Memo fields can be used for storing a variety of date type. However, +type 3 files are limited to storing textual data because most internal +memo field processing in a type 3 file relies on two contiguous 0x1a +charaters.

+ +Type 4 memo fields can be used for storing BLOB (binary large object) +data reliably, as the internal file structure does not rely on any +special characters embedded in the data.

+ +A special note on storing string data in a memo field. For those users +that are new to C/C++ programming, string fields typically end with +a null (0x00) terminator character. As a general rule of thumb when using +the library, add one to the length of any string when +specifying the length of the data. This stores the null terminating byte +with the data. For example, when storing string "This is a string" +specified size should be 17, not 16. + + +

Technical memo file information

+ +The following info on memo fields is for the curious. +It is not required +reading if you don't need to know the internals.

+ +

Memo files are made up of one or more blocks +

For version III files, the block size is 512 +

For version IV files, the block size is a multiple of 512 +

The minimum amout of space necessary to store one memo field is +one block or 512 bytes. +

The default block size can be adjusted by manipulating the +XB_DBT_BLOCK_SIZE macro in the options.h file. + + +

The main .DBF file maintains a ten byte numeric field which is blank if +no memo data exists for a given field. Otherwise it contains a number, which +when multiplied by the block size, points to the offset in the file of the head +block in the file/ +

+ +For version 3 memo field files, there are two fields in the head block of +the file, NextBlockNo and Version. Depending on the +Xbase software, some vendors products update these two fields, some do not. +The Xbase library keeps the fields updated, but does not rely on them to +be valued with correct data. This helps to support maximum compatibility +amoungst all Xbase tools available.

+ +For version 4 memo field files, +the first block in the .DBT file is a header block which is comprised of +8 bytes of data which maintain the file's block size and the next free +block available in the file. Blocks two through n contain the actual +memo data. A chain of empty blocks is maintained within the file for +potential future use. When an add or update routine executes, it first +attempts to find a spot in a set of blocks which were earlier allocated, +but not currently in use for the data. If no free spot is found, data are +appended to the end of the file. + +The free block chain is sorted in block number order. When blocks of +data are freed and added to the free block chain, the routines will attempt +to concatonate free block chains togethor where possible. When a delete +occurs, or an update which requires less space occurs, the new free space +is added to the free block chain. + +

+ +

Various Memo File Block Types

+ + + +

Valid Block Types +
Head Block +
Only data block for memo field +
First of several contiguous data block set +
2-n of contiguous data block set +
Only data block in free chain (version IV only) +
First of several contiguous free block set (version IV only) +
2-n of contiguous free block set (type 4 only) +

+

+ +

Head Block Structure

+ + +

1-4	LONG	Next Block ID +
5-8	LONG	Not used all 0x00's +
9-16	CHAR(8)	Filename (Version IV Only) +
17	CHAR	Version (0x03 = Version III, 0x00 = Version IV) +
18-20	CHAR(3)	Not used all 0x00's +
21-22	SHORT	Block Size (Version IV only ) +
23-Remainder of block	CHAR	Not used +

+

+ + +

Version IV Head Data Block Structure

+ + +

xbShort	0-1	-1 +
xbShort	2-3	Starting position of data (always 8 ?) +
xbLong	4-7	Length of data includes first 8 bytes +
char (9) - Blocksize	8-15	Data +

+

+ +

Version IV Head Free Block Structure

+ + +

xbLong	0-3	Next free block in the free block chain +
xbLong	4-7	Number of free blocks in this contiguous free + block set +

+

+Version 3 and 4 memo fields are terminated with two contiguous 0x1A bytes of data. +

+

+ + + diff --git a/docs/html/xbc3.htm b/docs/html/xbc3.htm new file mode 100755 index 0000000..f2f4a1d --- /dev/null +++ b/docs/html/xbc3.htm @@ -0,0 +1,73 @@ + + +Xbase DBMS Chapter 3 + +

Fields and Strings

Chapter Updated 11/21/22

+ +

+The main objective of this chapter is to provide basic information regarding +various field types supported by the library.

+ +Field names can be up to ten bytes in length and can contain characters, numbers +or special characters in the name. The field methods are used to manipulate +the data in a record of a data file. There are several types of fields.

+ + + + + +

Field Types
Type	Size	Allowable Values	Schema Value +
Numeric	0 - 17(include sign and decimal point	+ - . 0 through 9	XB_NUMERIC_FLD +
Character	0 - 254	Anything	XB_CHAR_FLD +
Date	8	CCYYMMDD	XB_DATE_FLD +
Floating Point	0 - 17 (includes sign and decimal point	+ - . 0 through 9	XB_FLOAT_FLD +
Logical	1	? Y y N n T t F f (? - uninitialized)	XB_LOGICAL_FLD +
Memo	Fixed length portion - 10 Variable length 0 - 32760 +	Type III - Text Type IV - Anything	XB_MEMO_FLD +

+ +

+Field names, types and lengths are defined when a data file is created. +After the file is created, the field characteristics can not be changed. To +change field characteristics, a new database table must be defined with the new +field requirements.

+ +

Memo Fields

+ +Memo fields are variable length data fields which are stored in two parts. +This first part is a ten byte field which is stored +in the fixed length record of the .DBF file. The variable data is stored in +a seperate .DBT file in 512 byte blocks. The ten byte field in the fixed +length portion of the record points to a .DBT block number.

+ +There are two versions of memo data files type III and type IV. Type IV +is more advanced in that released space can be reused and it also +supports BLOB data. The type III file is older technology, does not +support dynamic space reclamation and only supports string data. +See method xbDbf::SetVersion for controlling which version type you are +using. + +

+To utilize memo fields, the application program must allocate a buffer +which is large enough to handle the memo data.

+ +

Fields and Field Numbers

+ +The Xbase routines can access field data via using field names or field +numbers. Field numbers are numbered 0-n where the first field in a datafile +is field 0 going through the last field n. Accessing fields by number is +slightly more efficient than accessing by name.

+ +

Strings

+ +Xbase64 includes support for a string class xbString. +The xbString class interface was originally derived from the +Draft Standard C++ Library by P.J. Plauger and modified. +If you are familiar with other string classes, this one should be similar. +Strings can be used to manage strings of character data. +

+

+ + diff --git a/docs/html/xbc4.htm b/docs/html/xbc4.htm new file mode 100755 index 0000000..f494629 --- /dev/null +++ b/docs/html/xbc4.htm @@ -0,0 +1,80 @@ + + +Xbase DBMS Chapter 4 + +

Date Processing

Chapter Updated 2/12/99

+ +The objective of this chapter is to provide information regarding +the basic concepts of date arithmetic and supply generic +C/C++ date methods.

+ +

Leap Years

+ +Due to the fact that it actually takes about 365 1/4 days for +the earth to circle the sun, every fourth year and every fourth +century have an extra day added to the end of February and the year +is called a leap year. Leap years have 366 days, non leap years +have 365 days. The following code segment describes how to +determine if a given year is a leap year. + +A leap year is a year having 366 days, which can be evenly +divisible by 4 and not by 100 or divisible by 400. + +There are also leap centuries. Leap centuries are years which +are evenly divisible by 400. + +To calculate a leap year, the following code segment can be used + + + int year; + + if(( year % 4 == 0 && year % 100 != 0 ) || year % 400 = 0 ) + LEAP_YEAR = TRUE; + else + LEAP_YEAR = FALSE + + + +

Julian Dates

+ +Around the time of Jesus Christ, a fellow with the name of Julias Ceasar +established the Julian calendar. The Julian calendar established every +fourth year as a leap year with 366 days and all other years having 365 days. +The months were set up the same as they are with a Gregorian calendar, which +is what we use today. A Julian date is defined as as the number of days from the +first day of the year; February 1 would have a Julian day of 32.

+ +From a programmer's perspective, Julian dates are useful for doing date +arithmetic, determining the difference between two dates or calculating +a future or past date.

+ +To determine the difference between two dates, convert both dates to a +Julian date and subtract one from the other.

+ +To calculate a future or past date, convert the base date to a Julian date, +add (or subtract) the number of days necessary to (from) it and convert the +julian date back to a Gregorian date.

+ +The Julian date routines use a base date of 01/01/0001.

+ +

Gregorian Dates

+ +In 1582, Pope Gregor XIII introduced a corrected form of the Julian calendar. +Every 4th year still has 366 days except for century years. Century years +were added as leap years if evenly divisible by 400. The year 2000 is a leap century. +

+ +The methods supplied with this software are based on gregorian dates with +the format of CCYYMMDD for century, year, month and day.

+ + +

Date Formats

+ +All dates are stored in the .DBF files with format CCYYMMDD.

+All date routines work with dates formated with the same CCYYMMDD format.

+ +

+ + diff --git a/docs/html/xbc5.htm b/docs/html/xbc5.htm new file mode 100755 index 0000000..f798125 --- /dev/null +++ b/docs/html/xbc5.htm @@ -0,0 +1,205 @@ + + +Xbase DBMS Chapter 5 + +

Expression Handling

Chapter Updated 11/27/22

+ +

Overview

+ +The main objective of this chapter is to provide information regarding the +basic concepts of using the Xbase64 Expression module.

+ +The Xbase64 library includes an expression parsing routine which assists +application programmers by providing a high level data manipulation tool and +also allows for building complex index keys. + +The functions included were derived from dBASE III Plus, dBASE IV and Clipper. +

+Expressions are primarily used for index key definitions and filter criteria, but +can also be used for other tasks as well. +

+ +

Internal fuctioning

+The expression module works in two phases. Firstly, method +ParseExpression is called and builds an expression tree from +all the components of the expression. The tree is made up of individual +nodes. The expression is checked for valid field names, literals, +operands and functions. Any field references are resolved. If fields +are used in an expression and the database name for the field is not +included in the name with the -> operand, the routines assume the +associated database has been successfully opened. +

+Secondly, method ProcessExpression is called to process the +expression tree created by ParseExpression(). The routine parses each +node in the expression tree, executing functions, processing operands +and manipulating data to produce the desired result.

+ +If an expression will be processed repeatedly, it is best to pre-parse the +tree using ParseExpression, then for each new call to the expression, +execute method ProcessExpression which processes the tree. + + +

Expression Return Types

+Expressions will return a type of CHAR, NUMERIC, DATE or LOGICAL.

+ +An expression return type can be determined with method +GetExpressionResultType after parsing it.

+ +Expressions returning a return type of CHAR are limited to a 200 byte internal +buffer. There is also a 100 byte limit for NDX and MDX index key support. If +the 200 byte limit is not large enough for your application, adjust field +enum { WorkBufMaxLen = 200 }; in file exp.h. + +

+ + + + + + +

Return Type	XBase Type
CHAR	xbString
NUMERIC	xbDouble
DATE	xbDate
LOGICAL	xbBool

+ +

+Date routines return an xbDate result. In addition, the date value can be +extracted using GetStringResult() which returns YYYYMMDD or GetDoubleResult() +which returns a julian value. + +

+

Expression Functions

+Each expression function also has a corresponding C++ function. It is +slightly more efficient to call the C++ functions directly, rather than +execute the expression parsing routines.

+ +To add a new function, find a function that is similar to what you need, copy +the code and modify xbxbase.h, xbfuncs.cpp, xbexp.cpp and xb_test_expression.cpp. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Function Name	Return Type	Description
ABS	N	Calculate absolute value of numeric expression
ALLTRIM	C	Trim leading andtrailing whitespace from a string
ASC	N	Return ASCII code for first character in a string
AT	N	Return starting position of a string within a string
CDOW	C	Retun character weekday name for a date
CHR	C	Convert numeric expression to a character
CMONTH	C	Return month name for a date
CTOD	D	Return date from a character date input
DATE	D	Return system date
DAY	N	Return the day of the month from a date
DEL	C	Return record deletion status for a record
DELETED	L	Return record deletion status for a record<
DESCEND	1	Clipper DESCEND function
DOW	N	Return number of day of week
DTOC	C	Return character date from input date
DTOS	C	Return character CCYYMMDD date from input date
EXP	N	Return exponent value
IIF	C	Immediate If
INT	N	Convert number to integer, truncate any decimals
ISALPHA	L	Check if string begins with alpha character
ISLOWER	L	Check if string begins with lower case alpha character
ISUPPER	L	Check if string begins with upper case character
LEFT	C	Return left characters from a string
LEN	N	Return lenght of string
LOG	N	Calculate logarithm
LOWER	C	Convert upper case to lower case
LTRIM	C	Trim left side of a string
MAX	N	Return higher of two values
MIN	N	Return lesser of two values
MONTH	N	Return number of month for a given date
RECNO	N	Return current rec number for a given table
RECCOUNT	N	Return number of records in a given table
REPLICATE	C	Repeat character expression N times
RIGHT	C	Return right characters from as tring
RTRIM	C	Trim right side of string
SPACE	C	Generate a string of N spaces
SQRT	N	Calculate square root
STOD	D	Convert 8 byte CCYYMMDD date to date
STR	C	Convert number to character string
STRZERO	C	Convert number to character string with leading zeroes
SUBSTR	C	Extract portion oif one string from another string
TRIM	C	Trim left and right sides of a string
UPPER	C	Conver lower case to upper case
VAL	N	Convert numeric characters to number
YEAR	N	Return year for a given date

+ +

+

Expression Components

+Expressions are made up of one or more tokens. A token is one of literal, +database field, operand or function. Literals are either numeric or character. +Character literals are enclosed in 'single' or "double" quotes. numeric +literals are a series of one or more contiguous numerals, ".", "+" or "-'". +

+A field is simply a field name in the default database, or is in the form +of database->fieldname. + + +

+

Expression Literals

+ + + + + + +

Type	Example
CHAR	"literal" or 'literal'
NUMERIC	+99999.99
DATE	{10/07/60} or {02/09/1989}

+ + + +

+

Expression Operators

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Type	Operator	Precedence	Result	Notes
Parens	()	12
Numeric Operator	+ (unary)	11	N
Numeric Operator	- (unary)	11	N
Numeric Operator	--X	10	N
Numeric Operator	++X	10	N
Numeric Operator	**	9	N
Numeric Operator	^	9	N
Numeric Operator	%	8	N
Numeric Operator	*	8	N
Numeric Operator	/	8	N
Numeric Operator	+ Addition	7	N
Numeric Operator	- Subtraction	7	N
Numeric Operator	X--	6	N
Numeric Operator	X++	6	N
String Operator	+	5	C	Concatonate 1
String Operator	-	5	C	Concatonate 2
Relational Operator	=	4	L	N,C,D
Relational Operator	#, <>, !=	4	N,C,D
Relational Operator	<	4	L	N,C,D
Relational Operator	>	4	L	N,C,D
Relational Operator	<=	4	L	N,C,D
Relational Operator	>=	4	L	N,C,D
Relational Operator	$	4	L	N,C,D
Relational Operator	==			Clipper operator, not implemented yet
Logical Operator	NOT	3	L	Evaluated after all math and relational operators
Logical Operator	.NOT.	3	L	Evaluated after all math and relational operators
Logical Operator	AND	2	L	Evaluated after all math and relational operators
Logical Operator	.AND.	2	L	Evaluated after all math and relational operators
Logical Operator	OR	1	L	Evaluated after all math and relational operators
Logical Operator	.OR.	1	L	Evaluated after all math and relational operators

+ +

+

Examples

CUSTOMERS->LNAME + ", " + CUSTOMERS->FNAME +

LNAME + ", " + FNAME +

STARTDT + 90 +

YEAR( TODAY() ) +

IIF( "A" = "N", "true result", "false result" ) +

IIF( "A" = "N" .OR. 2 > 1 , "true result", "false result" ) +

IIF( .NOT. "A" = "N", "true result", "false result" ) +

.NOT. DELETED() +

+ + +

+ + diff --git a/docs/html/xbc6.htm b/docs/html/xbc6.htm new file mode 100755 index 0000000..a7e1746 --- /dev/null +++ b/docs/html/xbc6.htm @@ -0,0 +1,137 @@ + + +Xbase DBMS Chapter 6 + +

Index Overview

Chapter Updated 11/27/222

+ +The objective of this chapter is to provide information regarding +the basic concepts of index processing for the Xbase library.

+ + +

Overview

+ +The Xbase library is designed to support multiple index types simultaneously. +Dbase, Clipper and Foxbase each had their own index formats and ultimately the +goal is to provide support for all the legacy index file formats. + +

+The 4.0.x rewrite includes the NDX and MDX formats. Earlier versions of the +library included NTX and CDX formats which will be brought forward into the +library rewrite at some point in the future. + + +

Index updates

+ +The library automatically updates all tags in all open index files. + + +

+

Index File Types

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

File Type	Source	Max Tags Per File	Auto Opened	Sort Order	Unique Keys	Reclaimed Nodes	Filter Support	Status
NDX	dBase	1	Optional	ASC only	Y	N	N	Available in 4.0.1
MDX	dBase	47	Yes	ASC or DESC	Y	Y	Y	Available in 4.0.1
NTX	Clipper	1	Optional	?	?	?	?	Pending upgrades
CDX	Fox Pro	?	?	?	?	?	?	Pending upgrades
IDX	Fox Pro							Undeveloped

+ +

+

Index/Tag Methods

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Method	Description
xbDbf::CheckTagIntegrity	Checks a tag for missing or duplicate entries. Available if XB_DEBUG_SUPPORT is on.
xbDbf::CreateTag	Create a new tag.
xbDbf::DeleteTag	Delete existing tag.
xbDbf::Find	Find key value for the active tag.
xbDbf::GetFirsKey	Retrieve the first key for the active tag.
xbDbf::GetLastKey	Retrieve the last key for the active tag.
xbDbf::GetNextKey	Retrieve the next key for the active tag.
xbDbf::GetPrevKey	Retrieve the previous key for the active tag.
xbDbf::GetCurTag	Retrieve the tag name key for the active tag.
xbDbf::OpenIndex	Open an index file. Only used for index files that aren't automatically opened.
xbDbf::Reindex	Rebuild a tag. Available if XB_DEBUG_SUPPORT is on.
xbDbf::SetCurTag	Set current tag.

+ +

+

+ + diff --git a/docs/html/xbc7.htm b/docs/html/xbc7.htm new file mode 100755 index 0000000..20a60de --- /dev/null +++ b/docs/html/xbc7.htm @@ -0,0 +1,153 @@ + + +Xbase DBMS Chapter 7 + +

NDX Indices

Chapter Updated 11/27/22

+ +The objective of this chapter is to provide information regarding the +basic concepts of how .NDX index files work in the Xbase environment.

+ +The information in this chapter has been gathered by searching the internet +and by examining the structure of known good NDX indexes.

+ +

NDX Index File Characteristics

+ +

NDX indices maintain keys in ascending sort order only.

+

NDX indices support unique or non unique keys.

+ +Unique keys must be unique if the UniqueKeyOption is not set to XB_EMULATE_DBASE. +If the UniqueKeyOption is set to XB_EMULATE_DBASE, then the database update routines will +add a record to the table, but not add a corresponding duplicate key to the index tag. +The UniqueKeyOption is off (don't allow duplicates) by default. +

+ +Non-unique Keys are not required to be unique, duplicate +keys are allowed if the index is created with the XB_NOT_UNIQUE +setting. Duplicate keys are stored in record number order.

+ +

NDX indexes are automatically updated by the Xbase library after the +indices are opened.

+ +

Character keys are left justified and padded on the right with spaces.

+ +

Numeric keys are stored as eight byte double values.

+ +

NDX File Internals

+ +NDX files are comprised of two or more 512 byte blocks or nodes of +information. There are three types of nodes: Head Nodes, Interior +Nodes and Leaf Nodes.

+ +

The Head Node is the first node in the file starting at +position zero (0) and contains information about the NDX file. There +is only one Head Node in each index and it always starts at the +beginning of the file.

+ + + + + +

NDX Header Node
Type	Size	Field Name	Description +
xbLong	4	StartNode	This identifies the root node of + the index. The Header node is node 0. +
xbLong	4	Total Nodes	This is the count of the total + nodes in the index. The count includes the header node. +
xbLong	4	NoOfKeys	Total number of keys in the index +1 +
xbUShort	2	KeyLen	The index key length +
xbUShort	2	KeysPerNode	The maximum number of keys per node +
xbUShort	2	KeyType	Type of key +00 - Character 01 - Numeric +
xbLong	4	Keysize	Key record size + 8 +
char	1	Unknown	Reserved +
char	1	Unique	Unique indicator +00 - Not Unique - XB_NON_UNIQUE 01 - Unique - XB_UNIQUE +
char	488	KeyExpression	Key expression string +
	512		Total bytes in node +

+

+The following structure is used by the Xbase NDX routines: + + struct NdxHeadNode{ + xbLong StartNode; /* header node is node 0 */ + xbLong TotalNodes; /* includes header node */ + xbLong NoOfKeys; /* actual count + 1 */ + xbUShort KeyLen; /* length of key data */ + xbUShort KeysPerNode; /* max number of keys per node */ + xbUShort KeyType; /* 00 = Char, 01 = Numeric */ + xbLong KeySize; /* KeyLen + 8 */ + char Reserved1; /* Not sure about this one */ + char Unique; /* 00 = not unique, 01 = unique*/ + char KeyExpression[488]; /* key definition */ + } + +

+ +

Interior and Leaf Nodes

+ +Interior Nodes and Leaf Nodes share the same structure in an NDX file. +The difference between the two types is that interior nodes point to +other interior nodes or leaf nodes and leaf nodes point to records in +a DBF file. Interior nodes are optional nodes in an NDX file, +however if there are more than a few keys in the index there will +certainly be one or more interior nodes in the file. There will +always be at least one leaf node in the file. Leaf nodes contain DBF +record numbers which point to the location of the record in the +DBF file.

+ +Interior nodes have field LeftNodeNo valued which points to the node +which points to the keys which are less than the key value in the KeyVal +field. There is one more LeftNodeNo value in the node than there are keys. +The Last LeftNodeNo points to the node which is greater than the highest +key value in the node. Interior nodes have 0 in the value for the +DbfRecNo field.

+ +Leaf nodes have 0 in the LeftNodeNo field but do have a value in the +DbfRecNo field which points to a DFB record.

+ + + + + +

NDX Interior Node and Leaf Node Structure
Type	Size	Field Name	Description +
xbLong	4	NoOfKeysThisNode	The number of key values in this node. +
char	508	KeyRec	A repeating structure of + pointers and keys. See the next table for the KeyRec structure. +

+

+ + + +

KeyRec Structure
Type	Size	Field Name	Description +
xbLong	4	LeftNodeNo	The node number of the lower node + for this key. 0 in Leaf Nodes. +
xbLong	4	DbfRecNo	The DBF record number for this key. + 0 in Interior Nodes. +
char	KeyLen	KeyValue	The key value. +

+ +

+For those interested in knowing how the Xbase DBMS manipulates and +navigates index files, the following discussion may be helpfull.

+ +Xbase DBMS navigates through NDX files by using an in-memory chain +of nodes of the current location / key in use. It starts by reading the +Head Node of the index, which points to the first node of the file. The +first node of the file will be a leaf node if the index is small or will +be an interior node if the index has more than one leaf node. The first +interior node is loaded into memory, added to the node chain and points +to the next node to read. The node is made up of one or more keys. If +it is a leaf node, the logic looks for a matching key on the node. +Otherwise, if it is an interior node, the logic looks at the keys until the +search key is greater than or equal to the key in the node and then +traverses down the tree to the next node. It continues down the tree, +adding the nodes to the in-memory node chain until it reaches the correct +leaf node. If it finds a matching key in the leaf node, it returns a +XB_FOUND condition. If it doesn't find an exact match in the leaf node, it +returns a XB_NOT_FOUND condition and stops on the key which is greater than +the search key given. + +

+ + diff --git a/docs/html/xbc8.htm b/docs/html/xbc8.htm new file mode 100755 index 0000000..cb47657 --- /dev/null +++ b/docs/html/xbc8.htm @@ -0,0 +1,79 @@ + + +Xbase DBMS Chapter 8 + +

MDX Indices

Chapter Updated 11/28/22

+ +The objective of this chapter is to provide information regarding the +basic concepts of how .MDX index files work in the Xbase environment.

+ +The information in this chapter has been gathered by searching the internet +and by examining the structure of known good
+ +

MDX Index File Characteristics

+ +

MDX files are the same name as the corresponding DBF file with an MDX extension. +

MDX files are automatically opened by the library when the DBF file is opened. +

MDX index files (aka prod indices) contain from one to 47 tags, where each tag has it's own key characteristics. +

MDX indices maintain keys in either ascending or descending sort order. +

MDX indices support filtered keys. For example, a filter of .NOT. DELETED() will keep deleted records out +of the index tag. +

MDX indices are automatically updated by the Xbase library after the +indices are opened. + +

MDX indices support unique or non unique keys.

+ +Unique keys must be unique if the UniqueKeyOption is not set to XB_EMULATE_DBASE. +If the UniqueKeyOption is set to XB_EMULATE_DBASE, then the database update routines will +add a record to the table, but not add a corresponding duplicate key to the index tag. +The UniqueKeyOption is off (don't allow duplicates) by default. +

+ +Non-unique Keys are not required to be unique, duplicate +keys are allowed if the index is created with the XB_NOT_UNIQUE +setting. Duplicate keys are stored in record number order.

+ + +

Character keys are left justified and padded on the right with spaces. +

Numeric keys are stored as twelve byte BCD values. +

Date keys are stored as eight byte double julian values. + +

MDX File Internals

+ +The following information is not needed to use the library, it is just included +for general information.

+ +MDX files are comprised of 512 pages where multiple pages make a block. The default +setting is 1024 blocks, each block containing two pages.

+ +The first four pages contain: +

Bytes 0 - 543 contain general file information. +

Bytes 544 - 2047 is a 47 item table containing specific tag information. +

+ +Pages five and beyound: +

Bytes 2048 and beyond contain tag header blocks, interior nodes and leaf nodes. + +

+ +

Interior and Leaf Nodes

+ +Interior Nodes and Leaf Nodes share the same structure in an NDX file with +the exception that interior nodes have a non zero number immediately +after the rightmost key on the node. + +Interior nodes point to other interior nodes or leaf nodes and leaf nodes point +to records in a DBF file. Interior nodes are optional nodes in an MDX file, +however if there are more than a few keys in the index there will +certainly be one or more interior nodes in the file. There will +always be at least one leaf node per tag in the file. Leaf nodes +contain DBF record numbers which point to the location of the record +in the DBF file.

+ +

+ +

+ + diff --git a/docs/html/xbc9.htm b/docs/html/xbc9.htm new file mode 100755 index 0000000..297a702 --- /dev/null +++ b/docs/html/xbc9.htm @@ -0,0 +1,179 @@ + + +Xbase DBMS Chapter 9 + +

NTX Indices

Chapter Updated 11/28/22

+ + +

This chapter might be out of date. The NTX module is pending review and updates for release 4.x.x

+ +The objective of this chapter is to provide information regarding the +basic concepts of how .NTX index files work in the Xbase environment.

+ +The information in this chapter has been gathered by searching the internet +and by examining the structure of known good NTX indexes.

+ +

NTX Index File Characteristics

+ +

NTX indices maintain keys in ascending sort order only.

+
NTX indices support unique or non unique keys.

+ +Unique keys must be unique. The database update routines will +fail if an attempt to add a non-unique key is performed.

+ +Non-unique Keys are not required to be unique, duplicate +keys are allowed if the index is created with the XB_NOT_UNIQUE +setting. Duplicate keys are stored in record number order.

+ +
NTX indexes are automatically updated by the Xbase library after the +indices are opened.

+ +
Character keys are left justified and padded on the right with spaces.

+ +
Numeric keys are stored as eight byte double values.

+ +The numeric key processing logic performs floating point numeric +calculations on eight byte double values. This logic may be compute intensive +and slow on older machines, especially the older intel processors without a +math coprocessor chip. + +

+ + +

NTX File Internals

+ +NTX files are comprised of two or more 1024 byte blocks or nodes of +information. There are three types of nodes: Head Nodes, Interior +Nodes and Leaf Nodes.

+ +The Head Node is the first node in the file starting at +position zero (0) and contains information about the NTX file. There +is only one Head Node in each index and it always starts at the +beginning of the file.

+ + + + + +

NTX Header Node
Type	Size	Field Name	Description +
xbShort	2	Signature Byte	The Clipper signature byte. 0x003h indicates Clipper 87. 0x006h indicates Clipper 5.x +
xbShort	2	Indexing Version Number	Documented as the "Compiler Version" but I have observed an increasing number. Incremented whenever the index is changed. +
xbLong	4	First Node Offset	The offset to the first node. +
xbLong	4	First Unused Page Offset	The offset to the first unused node. +
xbShort	2	Key Size + 8	The Key Size plus 8 bytes. +
xbShort	2	Key Size	The size (length) of the key. +
xbShort	2	Number of Decimals	Number of decimal places in key. +
xbShort	2	Max Items Per Node	The maximum number of key per node. +
xbShort	2	1/2 The Max Items Per Node	Half the maximum number of key per node. Important in a B-tree system, as this is the minimum number of keys that must be on a page. +
char	256	KeyExpression	Key expression string +
char	1	Unique	Unique indicator + 00 - Not Unique - XB_NON_UNIQUE + 01 - Unique - XB_UNIQUE +
char	745	Unused	Unused + + +
	1024		Total bytes in node +

+

+The following structure is used by the Xbase NTX routines: + + +struct NtxHeadNode { /* ntx header on disk */ + xbUShort Signature; /* Clipper 5.x or Clipper 87 */ + xbUShort Version; /* Compiler Version */ + /* Also turns out to be */ + /* a last modified counter */ + xbULong StartNode; /* Offset in file for first node */ + xbULong UnusedOffset; /* First free node offset */ + xbUShort KeySize; /* Size of items (KeyLen + 8) */ + xbUShort KeyLen; /* Size of the Key */ + xbUShort DecimalCount; /* Number of decimal positions */ + xbUShort KeysPerNode; /* Max number of keys per node */ + xbUShort HalfKeysPerNode; /* Min number of keys per node */ + char KeyExpression[256]; /* Null terminated key expression */ + unsigned Unique; /* Unique Flag */ + char NotUsed[745]; +}; + + + +

+ +

Interior and Leaf Nodes

+ +NTX files use a B-tree system to store keys. A B-tree is a balanced, +on disk tree who's design minimizes disk access. Interior Nodes and +Leaf Nodes share the same structure in an NTX file. The difference is +that interior nodes point to other nodes. Leaf nodes point to +nothing. Keys in both interior nodes and leaf nodes point to records +in a DBF file. + +Interior nodes have field LeftNodeNo valued which points to the node +which points to the keys which are less than the key value in the KeyVal +field. There is one more LeftNodeNo value in the node than there are keys. The +Last LeftNodeNo points to the node which is greater than the highest +key value in the node.

+ +Leaf nodes have 0 in the LeftNodeNo field.

+ + + + + +

NTX Interior Node and Leaf Node Structure
Type	Size	Field Name	Description +
xbShort	2	NoOfKeysThisNode	The number of key values in this node. (N) +
Array of xbUShort	2	offsets[]	Array of + HeadNode.KeysPerNode +1 unsigned longs. + These values are the offsets (in bytes) of each key + in this node, from the beginning of the node. +
char	variable	KeyRecs	A repeating structure of + pointers and keys. See the next table for the KeyRec structure. +

+

+ +One primary difference between NDX files and NTX files is that NTX +files uses an array of offsets on all interior and leaf nodes. Each +offset is the byte count from the beginning of the node where each +KeyRec will be found. The order of the array of offsets determines +the order of keys on a given node. When keys are added or deleted, +thus changing the order of the keys on a node, only the order of the +offset array is changed. All other key data is not moved. This results +in slightly better index performance. + +
+ + + +

KeyRec Structure
Type	Size	Field Name	Description +
xbLong	4	LeftNodeNo	The node number (offset from beginning of file) of the lower node + for this key. 0 in Leaf Nodes. +
xbLong	4	DbfRecNo	The DBF record number for this key. + 0 in Interior Nodes. +
char	KeyLen	KeyValue	The key value. +

+ +

+For those interested in knowing how the Xbase DBMS manipulates and +navigates index files, the following discussion may be helpfull.

+ +Xbase DBMS navigates through NTX files by using an in-memory chain of +nodes of the current location / key in use. It starts by reading the +Head Node of the index, which points to the first node of the +file. The first node of the file will be a leaf node if the index is +small or will be an interior node if the index has more than one leaf +node. The first interior node is loaded into memory, added to the +node chain and points to the next node to read. The node is made up +of one or more keys. If it is a leaf node, the logic looks for a +matching key on the node. It continues down the tree, adding the +nodes to the in-memory node chain until it reaches the correct +node. If it finds a matching key in the leaf node, it returns a XB_FOUND +condition. If it doesn't find an exact match in the leaf node, it +returns a XB_NOT_FOUND condition and stops on the key which is greater +than the search key given. + +

+ +Author: Bob Cotton - bob@synxis.com
+ + -- cgit v1.2.3

Xbase DBMS +Last Updated 11/21/22Version 4.x.x

Documentation Table Of Contents

Section 1 - Xbase Concepts

Section 3 - Appendices

+Appendix C - GPL Library License +Appendix D - Bibliography +

Xbase DBMS Bibliography

Getting Started

Overview

System Requirements

Classes and User Interface

Portability, Type Defs and Structures

Field Types

Compilation Overview

System Limitations

CDX Indices

Pending CDX index module development.

CDX Indices

Pending IDX index module development.

Record and File Locking

Locking Overview

Linux/Windows File Locking Compatibility Issue

Samba settings

oplocks = no

Logfiles

Logging

CDX Indices

Pending SQL module development.

Sample Programs

XBase Sample Programs

Database Overview

The Record Buffer

Xbase Database File Header - DBF Version III and Version IV

Xbase Field Descriptor Record

Field Data Format

Memo Fields

Technical memo file information

Various Memo File Block Types

Head Block Structure

Version IV Head Data Block Structure

Version IV Head Free Block Structure

Fields and Strings

Field Types

Memo Fields

Fields and Field Numbers

Strings

Date Processing

Leap Years

Julian Dates

Gregorian Dates

Date Formats

Expression Handling

Overview

Internal fuctioning

Expression Return Types

Expression Functions

Expression Components

Expression Literals

Expression Operators

Examples

Index Overview

Overview

Tags

Index updates

Index File Types

Index/Tag Methods

NDX Indices

NDX Index File Characteristics

NDX File Internals

NDX Header Node

Interior and Leaf Nodes

NDX Interior Node and Leaf Node Structure

KeyRec Structure

MDX Indices

MDX Index File Characteristics

MDX File Internals

Interior and Leaf Nodes

NTX Indices

This chapter might be out of date. The NTX module is pending review and updates for release 4.x.x

NTX Index File Characteristics

NTX File Internals

Xbase DBMS
+Last Updated 11/21/22
Version 4.x.x

+Appendix C - GPL Library License
+Appendix D - Bibliography
+