diff options
Diffstat (limited to 'docs/html')
| -rwxr-xr-x | docs/html/Xbase64ClassDiagramV2.jpeg | bin | 0 -> 291478 bytes | |||
| -rwxr-xr-x | docs/html/Xbase64ClassDiagramV2.jpeg.jpeg | bin | 0 -> 299517 bytes | |||
| -rwxr-xr-x | docs/html/index.html | 34 | ||||
| -rwxr-xr-x | docs/html/ntx.index.html | 180 | ||||
| -rwxr-xr-x | docs/html/xbae.html | 5 | ||||
| -rwxr-xr-x | docs/html/xbaf.html | 37 | ||||
| -rwxr-xr-x | docs/html/xbc1.html | 39 | ||||
| -rwxr-xr-x | docs/html/xbc10.html | 932 | ||||
| -rwxr-xr-x | docs/html/xbc11.html | 142 | ||||
| -rwxr-xr-x | docs/html/xbc12.html | 319 | ||||
| -rwxr-xr-x | docs/html/xbc13.html | 46 | ||||
| -rwxr-xr-x | docs/html/xbc14.html | 113 | ||||
| -rwxr-xr-x | docs/html/xbc15.html | 96 | ||||
| -rwxr-xr-x | docs/html/xbc16.html | 52 | ||||
| -rwxr-xr-x | docs/html/xbc17.html | 219 | ||||
| -rwxr-xr-x | docs/html/xbc18.html | 252 | ||||
| -rwxr-xr-x | docs/html/xbc2.html | 151 | ||||
| -rwxr-xr-x | docs/html/xbc3.html | 42 | ||||
| -rwxr-xr-x | docs/html/xbc4.html | 261 | ||||
| -rwxr-xr-x | docs/html/xbc5.html | 553 | ||||
| -rwxr-xr-x | docs/html/xbc6.html | 220 | ||||
| -rwxr-xr-x | docs/html/xbc7.html | 182 | ||||
| -rwxr-xr-x | docs/html/xbc8.html | 245 | ||||
| -rwxr-xr-x | docs/html/xbc9.html | 393 |
24 files changed, 2872 insertions, 1641 deletions
diff --git a/docs/html/Xbase64ClassDiagramV2.jpeg b/docs/html/Xbase64ClassDiagramV2.jpeg Binary files differnew file mode 100755 index 0000000..191b061 --- /dev/null +++ b/docs/html/Xbase64ClassDiagramV2.jpeg diff --git a/docs/html/Xbase64ClassDiagramV2.jpeg.jpeg b/docs/html/Xbase64ClassDiagramV2.jpeg.jpeg Binary files differnew file mode 100755 index 0000000..6aa0a82 --- /dev/null +++ b/docs/html/Xbase64ClassDiagramV2.jpeg.jpeg diff --git a/docs/html/index.html b/docs/html/index.html index 0e8db33..f1e9590 100755 --- a/docs/html/index.html +++ b/docs/html/index.html @@ -2,32 +2,28 @@ <HTML><TITLE>Xbase DBMS Documentation Table of Contents</TITLE> <BODY BGCOLOR=#FFFFFF> <H1><p align="center">Xbase DBMS<br> -Last Updated 2/11/23<br>Version 4.1.0</p></H1> +Last Updated 04/17/23<br>Version 4.1.4</p></H1> <h2>Documentation Table Of Contents</h2> -<h3>Section 1 - Xbase Concepts</h3> +<h3>Section 1 - Xbase64 Concepts</h3> <h4> <A HREF="xbc1.html">Chapter 1 - Getting Started</A><br> -<A HREF="xbc2.html">Chapter 2 - Database Overview</A><br> -<A HREF="xbc3.html">Chapter 3 - Fields and Strings</A><br> -<A HREF="xbc4.html">Chapter 4 - Date Processing</A><br> -<A HREF="xbc5.html">Chapter 5 - Expression Handling</A><br> -<A HREF="xbc6.html">Chapter 6 - Index Overview</A><br> -<A HREF="xbc7.html">Chapter 7 - NDX (DBase) Indices</A><br> -<A HREF="xbc8.html">Chapter 8 - MDX (DBase) Indices</A><br> -<A HREF="xbc9.html">Chapter 9 - NTX (Clipper) Indices</A><br> -<A HREF="xbc10.html">Chapter 10 - CDX (FoxPro) Indices</A><br> -<A HREF="xbc11.html">Chapter 11 - IDX (FoxPro) Indices</A><br> -<A HREF="xbc12.html">Chapter 12 - Record and File Locking</A><br> -<A HREF="xbc13.html">Chapter 13 - Logfile Support</A><br> -<A HREF="xbc14.html">Chapter 14 - SQL Support</A><br> -<A HREF="xbc15.html">Chapter 15 - Sequential Block Read</A><br> +<A HREF="xbc2.html">Chapter 2 - System Overview</A><br> +<A HREF="xbc3.html">Chapter 3 - Fields, Strings and Dates</A><br> +<A HREF="xbc4.html">Chapter 4 - Expression Handling</A><br> +<A HREF="xbc5.html">Chapter 5 - Index Overview</A><br> + + +<A HREF="xbc6.html">Chapter 6 - SQL Support</A><br> </h4> <h3>Section 2 - Classes and Objects</h3> <h4> -<A HREF="xbc16.html">Chapter 16 - General Class Information</A><br> -<A HREF="xbc17.html">Chapter 17 - Class xbSsv - Shared System Values</A><br> -<A HREF="xbc18.html">Chapter 18 - Class xbXBase - The class that links it all together</A><br> +<A HREF="xbc7.html">Chapter 7 - General Class Information</A><br> +<A HREF="xbc8.html">Chapter 8 - Class xbSsv - Shared System Values</A><br> +<A HREF="xbc9.html">Chapter 9 - Class xbXBase - The class that links it all together</A><br> +<A HREF="xbc10.html">Chapter 10 - Class xbDbf - The DBF Table class</A><br> +<A HREF="xbc11.html">Chapter 11 - Class xbLog - Class to support error logging and informational messaging.</A><br> +<A HREF="xbc12.html">Chapter 12 - Class xbDate - Class to support dates and date fields.</A><br> </h4> <h3>Section 3 - Appendices</h3> diff --git a/docs/html/ntx.index.html b/docs/html/ntx.index.html new file mode 100755 index 0000000..82d6dd5 --- /dev/null +++ b/docs/html/ntx.index.html @@ -0,0 +1,180 @@ +<!DOCTYPE HTML PUBLIC> +<HTML> +<TITLE>Xbase DBMS Chapter 10</TITLE> +<BODY BGCOLOR=#FFFFFF> +<H2><p align="center">NTX Indices</p></H2> +<p align="center">Chapter Updated 04/13/23</p><hr> + + +<h3>This chapter might be out of date. The NTX module is pending review and updates for release 4.x.x</h3> + +The objective of this chapter is to provide information regarding the +basic concepts of how .NTX index files work in the Xbase environment.<br><br> + +The information in this chapter has been gathered by searching the internet +and by examining the structure of known good NTX indexes.<br><br> + +<h4>NTX Index File Characteristics</h4> + +<ul><li>NTX indices maintain keys in ascending sort order only.<br><br> +<li>NTX indices support <em>unique</em> or <em>non unique</em> keys.<br><br> + +<em>Unique</em> keys must be unique. The database update routines will +fail if an attempt to add a non-unique key is performed.<br><br> + +<em>Non-unique</em> 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.<br><br> + +<li>NTX indexes are automatically updated by the Xbase library after the +indices are opened.<br><br> + +<li>Character keys are left justified and padded on the right with spaces.<br><br> + +<li>Numeric keys are stored as eight byte double values.<br><br> + +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. + +</ul> + + +<h4>NTX File Internals</h4> + +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.<br><br> + +The <em>Head Node</em> 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.<br><br> + + +<TABLE BORDER> +<CAPTION ALIGN="TOP"><h3>NTX Header Node</H3></CAPTION> +<TR VALIGN="BASELINE"> +<TR><TH ALIGN="LEFT">Type<TD>Size<TD>Field Name<TD>Description +<TR><TH ALIGN="LEFT">xbShort<TD>2<TD>Signature Byte<TD>The Clipper signature byte. 0x003h indicates Clipper 87. 0x006h indicates Clipper 5.x +<TR><TH ALIGN="LEFT">xbShort<TD>2<TD>Indexing Version Number<TD>Documented as the "Compiler Version" but I have observed an increasing number. Incremented whenever the index is changed. +<TR><TH ALIGN="LEFT">xbLong<TD>4<TD>First Node Offset<TD>The offset to the first node. +<TR><TH ALIGN="LEFT">xbLong<TD>4<TD>First Unused Page Offset<TD>The offset to the first unused node. +<TR><TH ALIGN="LEFT">xbShort<TD>2<TD>Key Size + 8<TD>The Key Size plus 8 bytes. +<TR><TH ALIGN="LEFT">xbShort<TD>2<TD>Key Size<TD>The size (length) of the key. +<TR><TH ALIGN="LEFT">xbShort<TD>2<TD>Number of Decimals<TD>Number of decimal places in key. +<TR><TH ALIGN="LEFT">xbShort<TD>2<TD>Max Items Per Node<TD>The maximum number of key per node. +<TR><TH ALIGN="LEFT">xbShort<TD>2<TD>1/2 The Max Items Per Node<TD>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. +<TR><TH ALIGN="LEFT">char<TD>256<TD>KeyExpression<TD>Key expression string +<TR><TH ALIGN="LEFT">char<TD>1<TD>Unique<TD>Unique indicator<br> + 00 - Not Unique - XB_NON_UNIQUE<br> + 01 - Unique - XB_UNIQUE +<TR><TH ALIGN="LEFT">char<TD>745<TD>Unused<TD>Unused + + +<TR><TH ALIGN="LEFT"><TD>1024<TD><TD>Total bytes in node +</TABLE> +<br><br> +The following structure is used by the Xbase NTX routines: +<xmp> + +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]; +}; + +</xmp> + +<br><br> + +<h4>Interior and Leaf Nodes</h4> + +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. <br><br> + +Leaf nodes have 0 in the LeftNodeNo field.<br><br> + + +<TABLE BORDER> +<CAPTION ALIGN="TOP"><h3>NTX Interior Node and Leaf Node Structure</H3></CAPTION> +<TR VALIGN="BASELINE"> +<TR><TH ALIGN="LEFT">Type<TD>Size<TD>Field Name<TD>Description +<TR><TH ALIGN="LEFT">xbShort<TD>2<TD>NoOfKeysThisNode<TD>The number of key values in this node. (N) +<TR><TH ALIGN="LEFT">Array of xbUShort<TD>2<TD>offsets[]<TD>Array of + <pre>HeadNode.KeysPerNode +1</pre> unsigned longs. + These values are the offsets (in bytes) of each key + in this node, from the beginning of the node. +<TR><TH ALIGN="LEFT">char<TD>variable<TD>KeyRecs<TD>A repeating structure of + pointers and keys. See the next table for the KeyRec structure. +</TABLE> +<br><br> + +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. + +<BR> +<TABLE BORDER> +<CAPTION ALIGN="TOP"><h3>KeyRec Structure</H3></CAPTION> +<TR VALIGN="BASELINE"> +<TR><TH ALIGN="LEFT">Type<TD>Size<TD>Field Name<TD>Description +<TR><TH ALIGN="LEFT">xbLong<TD>4<TD>LeftNodeNo<TD>The node number (offset from beginning of file) of the lower node + for this key. 0 in Leaf Nodes. +<TR><TH ALIGN="LEFT">xbLong<TD>4<TD>DbfRecNo<TD>The DBF record number for this key. + 0 in Interior Nodes. +<TR><TH ALIGN="LEFT">char<TD>KeyLen<TD>KeyValue<TD>The key value. +</TABLE> + +<br><br> +For those interested in knowing how the Xbase DBMS manipulates and +navigates index files, the following discussion may be helpfull.<br><br> + +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. + +<hr> +<A HREF="mailto:bob@#synxis.com"> +Author: Bob Cotton - bob@synxis.com</A><br> +<p><img src="xbase.jpg"><br><hr> +</BODY> +</HTML> diff --git a/docs/html/xbae.html b/docs/html/xbae.html index e860911..3de3fb5 100755 --- a/docs/html/xbae.html +++ b/docs/html/xbae.html @@ -2,8 +2,8 @@ <HTML> <TITLE>Xbase DBMS Appendix E</TITLE> <BODY BGCOLOR=#FFFFFF> -<H2><p align="center">Eror Codes</p></H2> -<p align="center">Chapter Updated 1/31/23</p><hr> +<H2><p align="center">Error Codes</p></H2> +<p align="center">Chapter Updated 04/07/23</p><hr> <h3>Error Codes and Error Processing</h3> @@ -34,6 +34,7 @@ Error codes are defined in the xbretcod.h file.<br><br><br> <TR><TD> XB_NO_ERROR </TD><TD> 0 </TD><TD> general </TD></TR> <TR><TD> XB_NO_MEMORY </TD><TD> -100 </TD><TD> general </TD></TR> <TR><TD> XB_INVALID_OPTION </TD><TD> -101 </TD><TD> general </TD></TR> +<TR><TD> XB_INVALID_PARAMETER </TD><TD> -102 </TD><TD> general </TD></TR> <TR><TD> XB_DUP_TABLE_OR_ALIAS </TD><TD> -110 </TD><TD> table manager </TD></TR> <TR><TD> XB_INVALID_NODELINK </TD><TD> -120 </TD><TD> linklist </TD></TR> <TR><TD> XB_KEY_NOT_UNIQUE </TD><TD> -121 </TD><TD> linklist </TD></TR> diff --git a/docs/html/xbaf.html b/docs/html/xbaf.html index 110db7b..3ef171c 100755 --- a/docs/html/xbaf.html +++ b/docs/html/xbaf.html @@ -3,42 +3,41 @@ <TITLE>Xbase DBMS Chapter 15</TITLE> <BODY BGCOLOR=#FFFFFF> <H1><p align=center>Sample Programs</p></H1> -<p align=center>Page Updated 12/20/22</p><hr><br><br> +<p align=center>Page Updated 05/12/23</p><hr><br><br> <CENTER> <TABLE BORDER> <CAPTION ALIGN=TOP><H3>XBase Example Programs</H3></CAPTION> <TR ALIGN=BASELINE> <TR><TH ALIGN=LEFT>Program<TD>Program Description -<TR><TH ALIGN=LEFT>xb_ex_string<TD>Example program to demonstrate xbString class usage -<TR><TH ALIGN=LEFT>xb_ex_v3_create_dbf<TD>Example program to create V3 DBF file -<TR><TH ALIGN=LEFT>xb_ex_v3_upd_dbf<TD>Example program to update V3 DBF file -<TR><TH ALIGN=LEFT>xb_ex_v4_create_dbf<TD>Example Program to create V4 DBF file -<TR><TH ALIGN=LEFT>xb_ex_v4_upd_dbf<TD>Example program to update V4 DBF file +<TR><TH ALIGN=LEFT>xb_ex_string<TD>Example program to demonstrate xbString class usage. +<TR><TH ALIGN=LEFT>xb_ex_v3_create_dbf<TD>Example program to create V3 DBF file. +<TR><TH ALIGN=LEFT>xb_ex_v3_upd_dbf<TD>Example program to update V3 DBF file. +<TR><TH ALIGN=LEFT>xb_ex_v4_create_dbf<TD>Example Program to create V4 DBF file. +<TR><TH ALIGN=LEFT>xb_ex_v4_upd_dbf<TD>Example program to update V4 DBF file. </TABLE></CENTER> <br><br> - <CENTER> <TABLE BORDER> <CAPTION ALIGN=TOP><H3>XBase Utility Programs</H3></CAPTION> <TR ALIGN=BASELINE> <TR><TH ALIGN=LEFT>Program<TD>Program Description -<TR><TH ALIGN=LEFT>xb_cfg_check<TD>This program prints the compile settings and options in use -<TR><TH ALIGN=LEFT>xb_copydbf<TD>This program copies a DBF file structure -<TR><TH ALIGN=LEFT>xb_dbfutil1<TD>Menu program for executing Xbase functions -<TR><TH ALIGN=LEFT>xb_deletall<TD>This program marks all records in a DBF file for deletion -<TR><TH ALIGN=LEFT>xb_dumpdbt<TD>Debug memo files -<TR><TH ALIGN=LEFT>xb_dumphdr<TD>This program opens an Xbase file and prints its header -<TR><TH ALIGN=LEFT>xb_dumprecs<TD>This program dumps records for an XBase file -<TR><TH ALIGN=LEFT>xb_execsql<TD>This program executes SQL statements -<TR><TH ALIGN=LEFT>xb_pack<TD>This program packs (removes deleted records) from a DBF database file -<TR><TH ALIGN=LEFT>xb_undelall<TD>This program undeletes all deleted records in a dbf file -<TR><TH ALIGN=LEFT>xb_zap<TD>This program removes all records from a DBF file +<TR><TH ALIGN=LEFT>xb_cfg_check<TD>This program prints the compile settings and options in use. +<TR><TH ALIGN=LEFT>xb_copydbf<TD>This program copies a DBF file structure. +<TR><TH ALIGN=LEFT>xb_dbfutil1<TD>Menu program for executing Xbase functions. +<TR><TH ALIGN=LEFT>xb_deletall<TD>This program marks all records in a DBF file for deletion. +<TR><TH ALIGN=LEFT>xb_dumpdbt<TD>Debug memo files. +<TR><TH ALIGN=LEFT>xb_dumphdr<TD>This program opens an Xbase file and prints its header. +<TR><TH ALIGN=LEFT>xb_dumprecs<TD>This program dumps records for an XBase file. +<TR><TH ALIGN=LEFT>xb_execsql<TD>This program executes SQL statements. +<TR><TH ALIGN=LEFT>xb_import<TD>This program is used to import delimited data into a DBF file/table. +<TR><TH ALIGN=LEFT>xb_pack<TD>This program packs (removes deleted records) from a DBF database file. +<TR><TH ALIGN=LEFT>xb_undelall<TD>This program undeletes all deleted records in a dbf file. +<TR><TH ALIGN=LEFT>xb_zap<TD>This program removes all records from a DBF file. </TABLE></CENTER> <br><br> - <hr> <p><img src="xbase.jpg"><br><hr> </BODY> diff --git a/docs/html/xbc1.html b/docs/html/xbc1.html index c07e5f6..d042048 100755 --- a/docs/html/xbc1.html +++ b/docs/html/xbc1.html @@ -1,10 +1,10 @@ <!DOCTYPE HTML PUBLIC> -<HTML> -<TITLE>Xbase DBMS Chapter 1</TITLE> -<BODY BGCOLOR=#FFFFFF> +<html> +<title>Xbase DBMS Chapter 1</title> +<body BGCOLOR=#FFFFFF> <h1><p align="center">Getting Started</p></h1> -<p align="center">Chapter Updated 12/09/22</p> +<p align="center">Chapter Updated 4/28/23</p> <hr><h2>Overview</h2> @@ -50,6 +50,16 @@ The Xbase library is designed to be flexible in which options can be compiled into or out fo the library and also which environments it can be run on. +<br><br> +<h3>Library Features</h3> +<li>Supports 32 and 64 bit architectures +<li>Supports big endian and little endian architectures +<li>Compatible code, same API across multiple platforms / archtiectures +<li>Supports single and multi user configurations with record and file locking +<li>Includes support for logfiles + + + <br><br><br> <hr><h2>System Requirements</h2> @@ -62,7 +72,7 @@ The original source code was developed on a Linux platform with the GCC public domain C/C++ compiler. <br><br> -Xbase64 DBMS has been successfully ported and runs on Linux, Mac and and Windows. +Xbase64 DBMS has been successfully ported and runs on Linux, Mac and Windows. <br><br> <hr><h2>Classes and User Interface</h2> @@ -110,12 +120,12 @@ To build the xbase64 library, verify you have:<br> <li>Compiler and linker <br><br> -Verify you have access rights to the target location of the library +If you run into issues, verify you have access rights to the target location of the library. <br><br> For Linux: <br><br> -<li>cd xbase/Linux +<li>cd build/linux64 or cd build/linux32 <li>cmake . <li>make <li>make test @@ -127,7 +137,7 @@ update file /etc/ld.so.conf to include /usr/local/lib and run ldconfig. For Mac: <br><br> <li>Verify you have xcode installed and operational. -<li>cd xbase/Mac +<li>cd build/mac64 <li>cmake . -DCMAKE_OSX_SYSROOT=/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.11.sdk <li>make <li>make test @@ -136,7 +146,7 @@ For Mac: For Windows 64 bit with Visual Studio: <br><br> <li>Open a Visual Studio 64 bit Shell -<li>cd xbase\Win64VS +<li>cd build\win64vs <li>buildwin.bat <li>nmake test <li>From a VS Studio 64 bit shell in admin mode: nmake install @@ -145,7 +155,7 @@ For Windows 64 bit with Visual Studio: For Windows 32 bit with Visual Studio: <br><br> <li>Open a Visual Studio 32 bit Shell -<li>cd xbase\Win32VS +<li>cd build\win32vs <li>buildwin.bat <li>nmake test <li>From a VS Studio 32 bit shell in admin mode: nmake install @@ -153,9 +163,12 @@ For Windows 32 bit with Visual Studio: For Windows 32 bit with Borland 5.5 free compiler <br><br> -<li>cd xbase\Win32Borland +<li>cd build\borland5.5 <li>BuildBorland.bat <li>make test +<li>make install (if errors, run in administrator mode) +<li>xb_cfg_check (if errors, add path c:\Program Files\xbase64\bin) + <br><br> For other platforms: @@ -195,5 +208,5 @@ Maximum expression result length - 100 bytes<br> Maximum NDX index key length - 100 bytes<br><br> <hr><br> <p><img src=xbase.jpg><br><hr> -</BODY> -</HTML> +</body> +</html> diff --git a/docs/html/xbc10.html b/docs/html/xbc10.html index 04f5158..2889e6d 100755 --- a/docs/html/xbc10.html +++ b/docs/html/xbc10.html @@ -2,11 +2,937 @@ <HTML> <TITLE>Xbase DBMS Chapter 10</TITLE> <BODY BGCOLOR=#FFFFFF> -<H2><p align="center">CDX Indices</p></H2> -<p align="center">Chapter Updated 11/28/22</p><hr> +<H2><p align="center">Class xbDbf, xbDbf3, xbDbf4</p></H2> +<p align="center">Chapter Updated 04/28/23</p><hr> -<h3>Pending CDX index module development.</h3> +<h4>This chapter documents the following classes:</h4><br><br> +<li>Class xbDbf - Base class for handling DBF files. +<li>Class xbDbf3 - Derived class for handling DBF version III files. +<li>Class xbDbf4 - Derived class for handling DBF version IV files. + + +<br><br><br> +<h4>Highlights</h4> + +<li>The xbDbf3 and xbDbf4 classes are used for accessing DBF data files. + +<li>In line with relational theory, a each DBF file can be considered as a table. +The documentation uses the terms DBF and table interchangeably.<br> + +<li>These classes contain methods for accessing and updating DBF files. + +<li>The class structure is designed to support additional database file layouts. +To modify the library to support a new file type not currently supported, +create a derived class using xbDbf as a base class and create/modify methods needed +to support the new dbf file version.<br> + +<li>Each open DBF file would have an associated instance of the approprate class. +Each instance maintains a record buffer, an original record buffer (if changes applied) +current reccord number, selected tag, lock status, record updated flag and other +misc info. + +<li>The record updated flag tells the software to commit any updates to the data base +automatically if the auto commit option is turned on (default setting is on). + +<li>To use a DBF data file, first open it or create it. When done, close it. + +<li>The first byte of each record is a deletion flag. Deleted records are marked for deletion +and not physically removed from the DBF file. They and can be undeleted with xbDbf::UndeleteRecord(). +To physically remove deleted records from the DBF file, use xbDbf::Pack(). + + +<li>The library will automatically post any updates if Auto Commit is turned on (default setting). +If Auto Commit is not on, the application program will need to issue xbDbf::Commit() or +xbDbf::Abort() commands to post updates. + +<li> +The library automatically updates any open indices. MDX indices are opened automatically. +For NDX style indices, early versions of DBase required the NDX files be explicitly opened in the +application. More current versions of available DBase ODBC drivers automatically open NDX indices +with the addition of an <em>tablename.INF</em> file. Xbase64 supports both scenarios. + +<li>Xbase64 handles all record and file locking automatically and is programmed to work the same as the +original DBase products as far as locking goes. If auto locking is be turned off, the application +is responsible for all locking activities in multi user environments. + +<li>All field related methods operate on the current record. + +<li>When accessing fields on a given record, processing fields by field number offers slightly better +performance than processing by field name because the number has to be looked up if +the name is used. The field number can be retrieved with xbDbf::FieldNo() when the application program +is initializing. + +<li>Unless otherwise specified, the methods return either XB_NO_ERROR or an error as defined here: <a href=xbae.html>Error Codes</a> + + +<br><br><br><br> + + + + +<center> +<h2>Table Methods</h2> +<table border=1> +<tr><th width=35%>Method</th><th>Description</th><th>Parms</th></tr> +<tr><td>virtual xbInt16 Abort()</td><td>Cancel any updates not already committed to the table.</td></tr> +<tr><td>virtual xbInt16 AppendRecord()</td><td>Append the record buffer to the end of the table.</td></tr> +<tr><td>virtual xbInt16 BlankRecord()</td><td>Blank the current record buffer.</td></tr> +<tr><td>virtual xbInt16 Commit()</td><td>Commit any updates to the DBF file/table.</td></tr> +<tr><td>virtual xbInt16 Close()</td><td>Close the DBF file/table.</td></tr> +<tr><td>virtual xbInt16 CopyDbfStructure( xbDbf *dNewTable, const xbString &sTableName, const xbString &sTableAlias, xbInt16 iOverlay, xbInt16 iShareMode )</td><td>Copy structure to new DBF file.</td> + <td> + <em>dNewTable</em> - Pointer to new xbDbf class<br> + <em>sTableName</em> - New Table name<br> + <em>sTableAlias</em> - Alias for new table</br> + <em>iOverlay</em><br> + <li>xbTrue - Overlay if file exists<br> + <li>xbFalse - Don't overlay<br> + <em>iShareMode</em><br> + <li>XB_SINGLE_USER<br> + <li>XB_MULTI_USER + </td> +</tr> + +<tr><td>virtual xbInt16 CreateTable( const xbString &sTableName, const xbString &sAlias, xbSchema *pSchema, xbInt16 iOverlay, xbInt16 iShareMode ) = 0</td><td>Create new table / DBF file.</td> + <td> + <em>sTableName</em> - New Table name<br> + <em>sAlias</em> - Alias for new table<br> + <em>pSchema</em> - Pointer to field definition structure<br> + <em>iOverlay</em><br> + <li>xbTrue - Overlay if file exists<br> + <li>xbFalse - Don't overlay<br> + <em>iShareMode</em><br> + <li>XB_SINGLE_USER<br> + <li>XB_MULTI_USER + </td> +</tr> + +<tr><td>virtual xbInt16 DeleteTable()</td><td>Delete table / DBF file and all associated indices and memo files.</td></tr> + +<tr><td>virtual xbInt16 DeleteAll( xbInt16 iOption )</td><td>Set or remove delete flags for all records in the table.</td> + <td> + <em>iOption</em><br> + <li>0 - Set all delete flags<br> + <li>1 - Remove all delete flags + </td> +</tr> + +<tr><td>virtual xbInt16 DeleteAllRecords()</td><td>Set delete flags for all records in the table.</td></tr> +<tr><td>virtual xbInt16 DeleteRecord()</td><td>Delete the current record.</td></tr> + +<tr><td>virtual xbInt16 DumpHeader( xbInt16 iOption ) const</td><td>Dump DBF header information to the console.</td> + <td> + <em>iOption</em><br> + <li>1 = Print header only<br> + <li>2 = Field data only<br> + <li>3 = Header and Field data<br> + <li>4 = Header, Field and Memo header data if applicable + </td> +</tr> + +<tr><td>virtual xbInt16 DumpRecord( xbUInt32 ulRecNo, xbInt16 iOutputDest = 0, xbInt16 iOutputFmt = 0 )</td><td>Dump the contents of the specified record.</td> + <td> + <em>ulRecNo</em> - Record number of record to be dumped + <em>iOutputDest</em><br> + <li>0 = stdout<br> + <li>1 = Syslog<br> + <li>2 = Both<br> + <em>iOutputFmt</em><br> + <li>0 = with field names<br> + <li>1 = 1 line per rec, no field names<br> + <li>2 = 1 line per rec, first line is a list of field names. + </td> + </tr> + +<tr><td>virtual xbInt16 GetAutoCommit() const</td><td>Get the Auto Commit status.</td></tr> +<tr><td>virtual xbInt16 GetAutoCommit( xbInt16 iOption ) const</td><td>Get the Auto Commit status.</td><td><em>iOption:</em><br>0 = Table Status<br>1 = System Status.</td></tr> +<tr><td>virtual xbBool GetBof()</td><td>Returns true if beginning of file.</td></tr> +<tr><td>virtual xbUInt32 GetCurRecNo() const</td><td>Returns the current record number.</td></tr> +<tr><td>virtual xbInt16 GetDbfStatus() const</td><td>Returns Status<br> + <li>0 - Closed<br> + <li>1 - Open<br> + <li>2 - Updates Pending + </td> +</tr> + +<tr><td>virtual xbBool GetEof()</td><td>Returns true if end of file.</td></tr> +<tr><td>virtual xbInt32 GetFieldCnt() const</td><td>Returns the number of fields in the table.</td></tr> +<tr><td>virtual xbInt16 GetFirstRecord()</td><td>Retrieve the first active (not deleted) record in the table.</td></tr> +<tr><td>virtual xbInt16 GetFirstRecord( xbInt16 iOption )</td><td>Retrieve the first record in the table.</td> + <td> + <em>iOption</em><br> + <li>XB_ALL_RECS<br> + <li>XB_ACTIVE_RECS<br> + <li>XB_DELETED_RECS + </td> +</tr> +<tr><td>virtual xbUInt16 GetHeaderLen() const</td><td>Returns the length of the header portion within the DBF file.</td></tr> +<tr><td>virtual xbInt16 GetLastRecord()</td><td>Retrieve the last active (not deleted) record in the table.</td></tr> +<tr><td>virtual xbInt16 GetLastRecord( xbInt16 iOption )</td><td>Retrieve the last record in the table.</td> + <td> + <em>iOption</em><br> + <li>XB_ALL_RECS<br> + <li>XB_ACTIVE_RECS<br> + <li>XB_DELETED_RECS + </td> +</tr> + + +<tr><td>virtual xbInt16 GetNextRecord()</td><td>Retrieve the next active (not deleted) record in the table.</td></tr> +<tr><td>virtual xbInt16 GetNextRecord( xbInt16 iOption )</td><td>Retrieve the next record in the table.</td> + <td> + <em>iOption</em><br> + <li>XB_ALL_RECS<br> + <li>XB_ACTIVE_RECS<br> + <li>XB_DELETED_RECS + </td> +</tr> + +<tr><td>virtual xbInt16 GetNextRecord( xbInt16 iOption, xbUInt32 ulStartRec )</td><td>Retrieve the next record in the table.</td> + <td> + <em>iOption</em><br> + <li>XB_ALL_RECS<br> + <li>XB_ACTIVE_RECS<br> + <li>XB_DELETED_RECS<br> + <em>ulStartRec</em> is the position to start from. + </td> +</tr> + +<tr><td>virtual xbInt16 GetPrevRecord()</td><td>Retrieve the previous active (not deleted) record in the table.</td></tr> +<tr><td>virtual xbInt16 GetPrevRecord( xbInt16 iOption )</td><td>Retrieve the previous record in the table.</td> + <td> + <em>iOption</em><br> + <li>XB_ALL_RECS<br> + <li>XB_ACTIVE_RECS<br> + <li>XB_DELETED_RECS + </td> +</tr> +<tr><td>virtual xbInt16 GetRecord( xbUInt32 ulRecNo )</td><td>Retrieve record <em>ulRecNo</em>.</td><td><em>ulRecNo</em> - Record number to retrieve</td></tr> + +<tr><td>virtual xbInt16 GetRecordCnt( xbUInt32 & ulRecCnt )</td><td>Returns record count in <em>ulRecCnt</em>.</td> + <td> + <em>ulRecCnt</em> - Output number of records in table</tr> + +<tr><td>virtual char * GetRecordBuf( xbInt16 iOpt = 0 ) const</td><td>Returns pointer to record buffer.</td> + <td> + <em>iOpt</em><br> + <li>0 for RecBuf (current contents)<br> + <li>1 for RecBuf2 (original contents) + </td> +</tr> + +<tr><td>virtual xbUInt16 GetRecordLen() const</td><td>Returns the record length</td></tr> +<tr><td>virtual const xbString &GetTblAlias() const</td><td>Returns the table alias. Aliases can be used to manage multiple instances of the same open table.</td></tr> +<tr><td>virtual xbInt16 GetVersion() const = 0</td><td>Returns 3 for DBase III version files, returns 4 for DBase IV version files.</td></tr> +<tr><td>virtual xbXBase *GetXbasePtr() const</td><td>Returns the xbase pointer.</td></tr> +<tr><td>virtual xbBool MemoFieldsExist() const</td><td>Returns true if the table has any associated memo fields.</td></tr> + +<tr><td>virtual xbInt16 Open( const xbString &sTableName )</td><td>Open a table (DBF file).</td> + <td> + <em>sTableName</em> - Table name + </td> +</tr> + +<tr><td>virtual xbInt16 Open( const xbString &sTableName, const xbString &sAlias )</td><td>Open a table (DBF file).</td> +<td> + <em>sTableName</em> - Table name<br> + <em>sAlias</em> - Alias name + </td> +</tr> + + +<tr><td>virtual xbInt16 Open( const xbString &sTableName, const xbString &sAlias, xbInt16 iOpenMode, xbInt16 iShareMode ) = 0</td><td>Open a table (DBF file).</td> + <td> + <em>sTableName</em> - Table name<br> + <em>sAlias</em> - Alias name<br> + <em>iOpenMode</em><br> + <li>XB_READ<br> + <li>XB_READ_WRITE<br> + <em>iShareMode</em><br> + <li>XB_SINGLE_USER<br> + <li>XB_MULTI_USER + </td> +</tr> + + +<tr><td>virtual xbInt16 Pack()</td><td>Pack the table, physically remove any records flagged for deletion.</td></tr> +<tr><td>virtual xbInt16 Pack( xbUInt32 &ulDeletedRecCnt )</td><td>Pack the table, physically remove any records flagged for deletion.<br></td> + <td><em>ulDeletedRecordCnt</em> - Output - number of deleted records.</td></tr> + +<tr><td>virtual xbInt16 PutRecord()</td><td>Write record buffer to current location</td></tr> + +<tr><td>virtual xbInt16 PutRecord( xbUInt32 ulRecNo )</td><td>Write record buffer to record position <em>ulRecNo</em>.</td> + <td> + <em>ulRecNo</em> - Record number to write. + </td> +</tr> + +<tr><td>virtual xbInt16 RecordDeleted( xbInt16 iOpt = 0 ) const</td><td>Returns true if currect record is flagged for deletion, otherwise returns false.</td> + <td> + <em>iOpt</em><br> + <li>0 - check RecBuf (current contents)<br> + <li>1 - check RecBuf2 (original contents) + </td> +</tr> + + +<tr><td>virtual xbInt16 Rename( const xbString sNewName ) = 0</td><td>Rename the table.</td> + <td> + <em>sNewName</em> - New tablename. + </td> +</tr> + +<tr><td>virtual xbInt16 SetAutoCommit( xbInt16 iAutoCommit )</td><td>Set table specific auto commit setting.</td> + <td> + <em>iAutoCommit</em><br> + <li>0 - Auto Commit off<br> + <li>1 - Auto Commit on + </td> +</tr> + +<tr><td>virtual xbInt16 UndeleteAllRecords()</td><td>Undelete all records in table flagged for deletion.</td></tr> +<tr><td>virtual xbInt16 UndeleteRecord()</td><td>Undelete the current record.</td></tr> +<tr><td>virtual xbInt16 Zap()</td><td>Initialize the table.</td></tr> +</table> + +<br><br><br> + + + +<h2>Field Methods</h2> + +<table border=1> +<tr><th width=50%>Method</th><th>Description</th><th>Parms</th></tr> +<tr><td>virtual xbInt16 GetField(xbInt16 iFieldNo, xbString &sFieldValue, xbInt16 iRecBufSw ) const</td><td>Get string field.</td> + <td> + <em>iFieldNo</em> Input - Field number to retrieve<br> + <em>sFieldValue</em> Output string<br> + <em>iRecBufSw</em> Record buffer to pull data from.<br> + <li>0 - current buffer + <li>1 - original buffer +</td></tr> + +<tr><td>virtual xbInt16 GetField(xbInt16 iFieldNo, xbString &sFieldValue) const</td><td>Get string field.</td> + <td> + <em>iFieldNo</em> Input - Field number to retrieve<br> + <em>sFieldValue</em> Output string</td></tr> + </td> +</tr> + +<tr><td>virtual xbInt16 GetField(const xbString &sFieldName, xbString &sFieldValue) const</td><td>Get string field.</td> + <td> + <em>sFieldName</em> Input - Field name to retrieve<br> + <em>sFieldValue</em> Output string</td></tr> + </td> +</tr> + +<tr><td>virtual xbInt16 GetFieldDecimal( xbInt16 iFieldNo, xbInt16 &iFieldDecimal ) const</td><td>Get decimal field.</td> + <td> + <em>iFieldNo</em> Input - Field number to retrieve<br> + <em>iFieldDecimal</em> Output - Number of decimals defined for field + </td> +</tr> + +<tr><td>virtual xbInt16 GetFieldDecimal( const xbString &sFieldName, xbInt16 &iFieldDecimal ) const</td><td>Get decimal field.</td> + <td> + <em>sFieldName</em> Input - Field name to retrieve<br> + <em>iFieldDecimal</em> Output - Number of decimals defined for field + </td> +</tr> + +<tr><td>virtual xbInt16 GetFieldLen( xbInt16 iFieldNo, xbInt16 &iFieldLen ) const</td><td>Get field length.</td> + <td> + <em>iFieldNo</em> Input - Field number to retrieve<br> + <em>iFieldLen</em> Output - Field length of field + </td> +</tr> + +<tr><td>virtual xbInt16 GetFieldLen( const xbString &sFieldName, xbInt16 &iFieldLen ) const</td><td>Get field length.</td> + <td> + <em>sFieldName</em> Input - Field name to retrieve<br> + <em>iFieldLen</em> Output - Field length of field + </td> +</tr> + +<tr><td>virtual xbInt16 GetFieldName( xbInt16 iFieldNo, xbString &sFieldName ) const</td><td>Get field name.</td> + <td> + <em>iFieldNo</em> Input - Field number to retrieve<br> + <em>sFieldName</em> Output - Field name<br> + </td> +</tr> + +<tr><td>virtual xbInt16 GetFieldNo( const xbString &sFieldName, xbInt16 &iFieldNo ) const</td><td>Get field number.</td> + <td> + <em>sFieldName</em> Input - Field name to retrieve<br> + <em>iFieldNo</em> Output - Field number<br> + </td> +</tr> + +<tr><td>virtual xbInt16 GetFieldNo( const xbString &sFieldName ) const</td><td>Returns a field number for a given field name.</td> + <td> + <em>sFieldName</em> Input - Field name to retrieve<br> + </td> +</tr> + + +<tr><td>virtual xbInt16 GetFieldType( xbInt16 iFieldNo, char &cFieldType ) const</td><td>Get field type.</td> + <td> + <em>iFieldNo</em> Input - Field number to retrieve<br> + <em>cFieldType</em> Output - Field type + </td> +</tr> + +<tr><td>virtual xbInt16 GetFieldType( const xbString &sFieldName, char &cFieldType ) const</td><td>Get field type.</td> + <td> + <em>sFieldName</em> Input - Field name to retrieve<br> + <em>cFieldType</em> Output - Field type + </td> +</tr> + +<tr><td>virtual xbInt16 PutField( const xbString &sFieldName, const xbString &sFieldData )</td><td>Put string field.</td> + <td> + <em>sFieldName</em> Input - Field name to update<br> + <em>sFieldData</em> Input - Update value<br> + </td> +</tr> + +<tr><td>virtual xbInt16 PutField( xbInt16 iFieldNo, const xbString &sFieldData )</td><td>Put string field.</td> + <td> + <em>sFieldNo</em> Input - Field number to update<br> + <em>sFieldData</em> Input - Update value<br> + </td> +</tr> + +<tr><td>virtual xbInt16 PutLogicalField( xbInt16 iFieldNo, const xbString &sFieldData )</td><td>Put logicial field.</td> + <td> + <em>sFieldNo</em> Input - Field number to update<br> + <em>sFieldData</em> Input - Update value<br> + </td> +</tr> + +<tr><td>virtual xbInt16 PutLogicalField( const xbString &sFieldName, const xbString &sFieldData )</td><td>Put logical field.</td> + <td> + <em>sFieldName</em> Input - Field name to update<br> + <em>sFieldData</em> Input - Update value<br></td></tr> + </td> +</tr> + +<tr><td>virtual xbInt16 GetLogicalField( xbInt16 iFieldNo, xbString &sFieldData ) const</td><td>Get logical field.</td> + <td> + <em>iFieldNo</em> Input - Field number to retrieve<br> + <em>sFieldData</em> Output - String name to put result<br> + </td> +</tr> + +<tr><td>virtual xbInt16 GetLogicalField( const xbString &sFieldName, xbString &sFieldData) const</td><td>Get logical field.</td> + <td> + <em>sFieldName</em> Input - Field name to retrieve<br> + <em>sFieldData</em> Output - String name to put result<br> + </td> +</tr> + +<tr><td>virtual xbInt16 PutLogicalField( xbInt16 iFieldNo, xbBool bFieldData )</td><td>Put logical field.</td> + <td> + <em>sFieldNo</em> Input - Field number to update<br> + <em>bFieldData</em> Output - Bool value<br> + </td> +</tr> + +<tr><td>virtual xbInt16 PutLogicalField( const xbString &sFieldName, xbBool bFieldData )</td><td>Put logical field.</td> + <td> + <em>sFieldName</em> Input - Field name to update<br> + <em>bFieldData</em> Output - Bool value<br> + </td> +</tr> + +<tr><td>virtual xbInt16 GetLogicalField( xbInt16 iFieldNo, xbBool &bFieldData ) const</td><td>Get logical field.</td> + <td> + <em>iFieldNo</em> Input - Field number to retrieve<br> + <em>bFieldData</em> Output - Bool value<br> + </td> +</tr> + +<tr><td>virtual xbInt16 GetLogicalField( xbInt16 iFieldNo, xbBool &bFieldData, xbInt16 iRecBufSw ) const</td><td>Get logical field.</td> + <td> + <em>iFieldNo</em> Input - Field number to retrieve<br> + <em>bFieldData</em> Output - Bool value<br> + <em>iRecBufSw</em> Record buffer to pull data from.<br> + <li>0 - current buffer + <li>1 - original buffer, before any updates + </td> +</tr> + +<tr><td>virtual xbInt16 GetLogicalField( const xbString &sFieldName, xbBool &bFieldData) const</td><td>Get logical field.</td> + <td> + <em>sFieldName</em> Input - Field name to retrieve<br> + <em>bFieldData</em> Output - Bool value<br> + </td> +</tr> + +<tr><td>virtual xbInt16 GetLongField( xbInt16 iFieldNo, xbInt32 &lFieldValue ) const</td><td>Get long field.</td> + <td> + <em>iFieldNo</em> Input - Field number to retrieve<br> + </em>lFieldValue<em> Output - xbInt32 field to put result + </td> +</tr> + +<tr><td>virtual xbInt16 GetLongField( const xbString &sFieldName, xbInt32 &lFieldValue ) const</td><td>Get long field.</td> + <td> + <em>sFieldName</em> Input - Field name to retrieve<br> + </em>lFieldValue<em> Output - xbInt32 field to put result + </td> +</tr> + +<tr><td>virtual xbInt16 PutLongField( xbInt16 iFieldNo, xbInt32 lFieldValue )</td><td>Put long field.</td> + <td> + <em>sFieldNo</em> Input - Field number to update<br> + <em>lFieldValue<em> Output - xbInt32 field to put result + </td> +</tr> + +<tr><td>virtual xbInt16 PutLongField( const xbString &sFieldName, xbInt32 lFieldValue )</td><td>Put long field.</td> + <td> + <em>sFieldName</em> Input - Field name to retrieve<br> + <em>lFieldValue<em> Output - xbInt32 update value + </td> +</tr> + +<tr><td>virtual xbInt16 GetULongField( xbInt16 iFieldNo, xbUInt32 &lFieldValue ) const</td><td>Get unsigned long field.</td> + <td> + <em>iFieldNo</em> Input - Field number to retrieve<br> + <em>ulFieldValue<em> Output - xbUInt32 field to put result + </td> +</tr> + +<tr><td>virtual xbInt16 GetULongField( const xbString &sFieldName, xbUInt32 &lFieldValue ) const</td><td>Get unsigned long field.</td> + <td> + <em>sFieldName</em> Input - Field name to retrieve<br> + <em>ylFieldValue<em> Output - xbUInt32 field to put result + </td> +</tr> + +<tr><td>virtual xbInt16 PutULongField( xbInt16 iFieldNo, xbUInt32 lFieldValue )</td><td>Put unsigned long field.</td> + <td> + <em>sFieldNo</em> Input - Field number to update<br> + <em>lFieldValue<em> Output - xbInt32 update value + </td> +</tr> + +<tr><td>virtual xbInt16 PutULongField( const xbString &sFieldNo, xbUInt32 lFieldValue )</td><td>Put unsigned long field.</td> + <td> + <em>sFieldName</em> Input - Field name to update<br> + <em>lFieldValue<em> Output - xbUInt32 update value + </td> +</tr> + +<tr><td>virtual xbInt16 GetDoubleField( xbInt16 FieldNo, xbDouble &dFieldValue ) const</td><td>Get double field.</td> + <td> + <em>iFieldNo</em> Input - Field number to retrieve<br> + <em>dFieldValue<em> Output - xbDouble field to put result + </td> +</tr> + +<tr><td>virtual xbInt16 GetDoubleField( xbInt16 FieldNo, xbDouble &dFieldValue, xbInt16 iRecBufSw ) const</td><td>Get double field.</td> + <td> + <em>iFieldNo</em> Input - Field number to retrieve<br> + <em>dFieldValue<em> Output - xbDouble field to put result + </td> +</tr> + +<tr><td>virtual xbInt16 GetDoubleField( const xbString &sFieldName, xbDouble &dFieldValue ) const</td><td>Get double field.</td> + <td> + <em>sFieldName</em> Input - Field name to retrieve<br> + <em>dFieldValue<em> Output - xbDouble field to put result + </td> +</tr> + +<tr><td>virtual xbInt16 PutDoubleField( xbInt16 FieldNo, xbDouble dFieldValue )</td><td>Put double field.</td> + <td> + <em>sFieldNo</em> Input - Field number to update<br> + <em>dFieldValue<em> Output - xbDouble update value + </td> +</tr> + + +<tr><td>virtual xbInt16 PutDoubleField( const xbString &FieldName, xbDouble dFieldValue )</td><td>Put double field.</td> + <td> + <em>sFieldName</em> Input - Field name to update<br> + <em>dFieldValue<em> Output - xbDouble update value + </td> +</tr> + +<tr><td>virtual xbInt16 GetFloatField( xbInt16 iFieldNo, xbFloat &fFieldValue ) const</td><td>Get float field.</td> + <td> + <em>iFieldNo</em> Input - Field number to retrieve<br> + <em>fFieldValue<em> Output - xbFloat field to put result + </td> +</tr> + +<tr><td>virtual xbInt16 GetFloatField( const xbString &sFieldName, xbFloat &fFieldValue ) const</td><td>Get float field.</td> + <td> + <em>sFieldName</em> Input - Field name to retrieve<br> + <em>fFieldValue<em> Output - xbFloat field to put result + </td> +</tr> + +<tr><td>virtual xbInt16 PutFloatField( xbInt16 iFieldNo, xbFloat fFieldValue )</td><td>Put float field.</td> + <td> + <em>sFieldName</em> Input - Field number to update<br> + <em>fFieldValue<em> Output - xbFloat update value + </td> +</tr> + +<tr><td>virtual xbInt16 PutFloatField( const xbString &sFieldName, xbFloat fFieldValue )</td><td>Put float field.</td> + <td> + <em>sFieldName</em> Input - Field name to update<br> + <em>fFieldValue<em> Output - xbFloat update value + </td> +</tr> + +<tr><td>virtual xbInt16 GetDateField( xbInt16 iFieldNo, xbDate &dt ) const</td><td>Get date field.</td> + <td> + <em>iFieldNo</em> Input - Field number to retrieve<br> + <em>dt<em> Output - xbDate field to put result + </td> +</tr> + +<tr><td>virtual xbInt16 GetDateField( const xbString &sFieldName, xbDate &dt ) const</td><td>Get date field.</td> + <td> + <em>sFieldName</em> Input - Field name to retrieve<br> + <em>dt<em> Output - xbDate field to put result + </td +</tr> + +<tr><td>virtual xbInt16 PutDateField( xbInt16 iFieldNo, const xbDate &dt )</td><td>Put date field.</td> + <td> + <em>sFieldName</em> Input - Field number to update<br> + <em>dt</em> Output - xbDate update value + </td> +</tr> + +<tr><td>virtual xbInt16 PutDateField( const xbString &sFieldName, const xbDate &dt )</td><td>Put date field.</td> + <td> + <em>sFieldName</em> Input - Field name to update<br> + <em>dt</em> Output - xbDate update value + </td> +</tr> + +<tr><td>virtual xbInt16 GetNullSts( xbInt16 iFieldNo, xbBool &bIsNull ) const<br> + virtual xbInt16 GetNullSts( const xbString &sFieldName, xbBool &bIsNull ) const<br> + virtual xbInt16 GetNullSts( xbInt16 iFieldNo, xbBool &bIsNull, xbInt16 iRecBufSw ) const</td> + <td>Get Field Null Status</td> + <td> + <em>sFieldName</em> Input - Field name to check<br> + <em>iFieldNo</em> Input - Field no to check<br> + <em>bIsNull</em> Output - True if the field is null (all spaces).<br> + <em>iRecBufSw</em> Record buffer to pull data from.<br> + <li>0 - current buffer + <li>1 - original buffer + </td> +</tr> + +</table> + + + +<br><br><br> +<h2>Memo File/Field Methods</h2> + +<table border=1> +<tr><th>Method</th><th>Description</th><th>Parms</th></tr> +<tr><td>virtual xbInt16 GetMemoFieldCnt() const</td><td>Returns number of memo fields in the table.</td></tr> +<tr><td>virtual xbMemo *GetMemoPtr()</td><td>Returns a pointer to the associated memo file instance.</td></tr> +<tr><td>virtual xbUInt32 GetCreateMemoBlockSize() const</td><td>Returns the block size a new memo file will be created with. Block sizes are in 512 byte increments.</td></tr> +<tr><td>virtual xbInt16 GetMemoField( xbInt16 iFldNo, xbString &sMemoData )</td><td>Get memo field data.</td> + <td> + <em>iFldNo</em> Input - Memo field number to retrieve<br> + <em>sMemoData</em> Output - xbString field to put result + </td> +</tr> + +<tr><td>virtual xbInt16 GetMemoField( const xbString & sFldName, xbString &sMemoData )</td><td>Get memo field data.</td> + <td> + <em>iFldName</em> Input - Memo field name to retrieve<br> + <em>sMemoData</em> Output - xbString field to put result + </td> +</tr> + +<tr><td>virtual xbInt16 GetMemoFieldLen( xbInt16 iFldNo, xbUInt32 &ulMemoFieldLen )</td><td>Get memo field length.</td> + <td> + <em>iFldNo</em> Input - Memo field number to retrieve<br> + <em>ulMemoFieldLen</em> Output - xbUInt32 field to put result + </td> +</tr> + +<tr><td>virtual xbInt16 GetMemoFieldLen( const xbString & sFldName, xbUInt32 &ulMemoFieldLen )</td><td>Get memo field length.</td> + <td> + <em>iFldName</em> Input - Memo field name to retrieve<br> + <em>ulMemoFieldLen</em> Output - xbUInt32 field to put result + </td> +</tr> + +<tr><td>virtual xbBool MemoFieldExists( xbInt16 iFieldNo ) const</td><td>Returns xbTrue if memo field exists, else returns xbFalse.</td> + <td> + <em>iFieldNo</em> Input - field number + </td> +</tr> + +<tr><td>virtual xbBool MemoFieldExists( const xbString &sFieldName ) const</td><td>Returns xbTrue if memo field exists, else returns xbFalse.</td> + <td> + <em>sFieldName</em> Input - field name + </td> +</tr> + +<tr><td>virtual xbInt16 SetCreateMemoBlockSize( xbUInt32 ulBlockSize ) = 0</td><td>Set the block size for the memo file. Must be called before memo file is created.</td> + <td> + <em>ulBlockSize</em> Input - New block size in 512 byte increments + </td> +</tr> + +<tr><td>virtual xbInt16 UpdateMemoField( xbInt16 iFldNo, const xbString &sMemoData )</td><td>Update memo field.</td> + <td> + <em>iFldNo</em> Input - Memo field number to update<br> + <em>sMemoData</em> Input - Memo data to update + </td> +</tr> + +<tr><td>virtual xbInt16 UpdateMemoField( const xbString & sFldName, const xbString &sMemoData )</td><td>Update memo field.</td> + <td> + <em>iFldName</em> Input - Memo field name to update<br> + <em>sMemoData</em> Input - Memo data to update + </td> +</tr> +</table> + + + + +<br><br><br> +<h2>Lock Methods</h2> +<table border=1> +<tr><td colspan=3> + +If auto locking is turned on (default setting), xbase64 handles locking automatically.<br> +If auto locking is turned off and application is running in a multi user environment, then +locking functions will need to be handled by the application program. +</td></tr> + +<tr><th>Method</th><th>Description</th><th>Parms</th></tr> +<tr><td>virtual xbInt16 LockTable( xbInt16 iLockFunction )</td><td>Lock the table.</td> + <td> + <em>LockFunction</em><br> + <li>XB_LOCK<br> + <li>XB_UNLOCK + </td> +</tr> +<tr><td>virtual xbInt16 LockRecord( xbInt16 iLockFunction, xbUInt32 ulRecNo )</td><td>Lock record.</td> + <td> + <em>iLockFunction</em><br> + <li>XB_LOCK <br> + <li>XB_UNLOCK<br> + <em>ulRecNo</em> - Record number to lock or unlock + </td> +</tr> +<tr><td>virtual xbInt16 LockAppend( xbInt16 iLockFunction )</td><td>Lock append bytes for adding new record.</td> + <td> + <em>iLockFunction</em><br> + <li>XB_LOCK<br> + <li>XB_UNLOCK + </td> +</tr> +<tr><td>virtual xbInt16 LockHeader( xbInt16 iLockFunction )</td><td>Lock table header bytes for updating table.</td> + <td> + <em>iLockFunction</em><br> + <li>XB_LOCK<br> + <li>XB_UNLOCK + </td> +</tr> +<tr><td>virtual xbInt16 LockMemo( xbInt16 iLockFunction )</td><td>Lock memo table for update. + <td> + <em>iLockFunction</em><br> + <li>XB_LOCK<br> + <li>XB_UNLOCK + </td> +</tr> +<tr><td>virtual xbBool GetMemoLocked() const</td><td>Returns the memo lock status.</td></tr> + +<tr><td>virtual xbInt16 LockIndices( xbInt16 iLockFunction )</td><td>Lock indices for update.</td> + <td> + <em>iLockFunction</em><br> + <li>XB_LOCK<br> + <li>XB_UNLOCK + </td> +</tr> +<tr><td>xbInt16 GetAutoLock() const</td><td>Retrieve current auto lock status.</td></tr> + +<tr><td>void SetAutoLock( xbInt16 iAutoLock )</td><td>Set autolock status for table</td> + <td> + <em>iAutoLock</em><br> + <li>1 - Use auto lock for this table.<br> + <li>0 - Don't use auto lock for this table.<br> + <li>-1 - (minus one) Use system default. + </td> +</tr> + +<tr><td>xbInt16 GetLockFlavor() const</td><td>Always returns 1. Included for potential future alternative locking schemes.</td></tr> +<tr><td>void SetLockFlavor( xbInt16 iLockFlavor )</td><td>For future use. Included for potential future alternative locking schemes.</td></tr> +<tr><td>xbBool GetTableLocked() const</td><td>Returns Table Locked status.</td></tr> +<tr><td>xbBool GetHeaderLocked() const</td><td>Returns Header Locked Status.</td></tr> +<tr><td>xbUInt32 GetAppendLocked() const</td><td>Returns Append Bytes locked status.</td></tr> +<tr><td>xbLinkListNode<xbUInt32> * GetFirstRecLock() const</td><td>Returns pointer to linked list of record locks.</td></tr> +<tr><td>void DumpTableLockStatus() const</td><td>Dumps all lock information for debugging purposes.</td></tr> +</table> + + + +<br><br><br> +<h2>Index Methods</h2> +<table border=1> +<tr><th width=35%>Method</th><th width=35%>Description</th><th>Parms</th></tr> +<tr><td> virtual xbInt16 CheckTagIntegrity( xbInt16 iTagOpt, xbInt16 iOutputOpt )</td><td>For debugging, check tag integrity.</td> + <td> + <em>iTagOpt</em><br> + <li>0 - Check current tag<br> + <li>1 - Check all tags<br> + <em>iOutputOpt</em><br> + <li>0 = stdout<br> + <li>1 = Syslog<br> + <li>2 = Both + </td> +</tr> + +<tr><td> virtual xbInt16 CloseIndexFile( xbIx *pIx )</td><td>Close an index file.</td> + <td> + <em>pIx</em> Pointer to index file instance. +</tr> + +<tr><td> virtual xbInt16 CreateTag( const xbString &sIxType, const xbString &sName, const xbString &sKey, const xbString &sFilter, + xbInt16 iDescending, xbInt16 iUnique, xbInt16 iOverLay, xbIx **xbIxOut, void **vpTagOut )</td> + <td>Create index tag</td> + <td> + <em>sIxType</em> Input - MDX or NDX<br> + <em>sName</em> Input - Tag Name<br> + <em>sKey</em> Input - Key Expression<br> + <em>sFilter</em> Input - Filter Expression (MDX only)<br> + <em>iDescending</em> Input - xbTrue for descending, xbFalse ascending<br> + <em>iUnique</em> Input - xbTrue for unique, xbFalse not unique<br> + <em>iOverlay</em> Input - xbTrue to overlay if existing file exists<br> + <em>**xbIxOut</em> Output - Pointer to ix instance<br> + <em>**vpTagOut</em> Output - Pointer to tag + </td> +</tr> + +<tr><td> virtual xbInt16 DeleteTag( const xbString &sIxType, const xbString &sName )</td><td>Delete a tag.</td> + <td> + <em>sIxType</em> Input - MDX or NDX<br> + <em>sName</em> Input - Tag Name<br> + <em>sKey</em> Input - Key Expression + </td> +</tr> + +<tr><td> virtual xbInt16 DeleteAllIndexFiles()</td><td>Delete all indices for table.</td></tr> + +<tr><td> virtual xbInt16 Find( xbString &sKey )</td><td>Find xbString key for current tag (assumes character index).</td> + <td> + <em>sKey</em> - String search key + </td> +</tr> + +<tr><td> virtual xbInt16 Find( xbDate &dtKey )</td><td>Find xbDate key for current tag(assumes date index).</td> + <td> + <em>dtKey</em> - Date search key + </td> +</tr> + +<tr><td> virtual xbInt16 Find( xbDouble &dKey )</td><td>Find numeric key for current tag (assumes numeric index).</td> + <td> + <em>dKey</em> - Nueric search key + </td> +</tr> + +<tr><td> virtual xbIx *GetCurIx() const</td><td>Returns pointer to current index file.</td></tr> +<tr><td> virtual void *GetCurTag() const</td><td>Returns pointer to current tag.</td></tr> +<tr><td> virtual xbInt16 GetFirstKey()</td><td>Get the first key for the current tag, reposition current record.</td></tr> +<tr><td> virtual xbInt16 GetNextKey()</td><td>Get the next key for the current tag, reposition current record.</td></tr> +<tr><td> virtual xbInt16 GetPrevKey()</td><td>Get the previous key for the current tag, reposition current record.</td></tr> +<tr><td> virtual xbInt16 GetLastKey()</td><td>Get the last key for the current tag, reposition current record.</td></tr> +<tr><td> virtual const xbString &GetCurIxType() const</td><td>Returns the current index type.</td></tr> +<tr><td> virtual const xbString &GetCurTagName() const</td><td>Returns the current tag name.</td></tr> +<tr><td> virtual xbIxList *GetIxList() const</td><td>Returns a pointer to list of open indices.</td></tr> +<tr><td> virtual xbInt32 GetPhysicalIxCnt () const</td><td>Returns the count of open index files for the table.</td></tr> +<tr><td> xbLinkListNode<xbTag *> *GetTagList () const</td><td>Returns a pointer to a list of tags for the table.</td></tr> +<tr><td> virtual xbInt16 OpenIndex( const xbString &sIxType, const xbString &sIndexName )</td> + <td>Open the index.<br>MDX index files are opened automatically.<br>NDX index files can be opened automatically.</td> + <td> + <em>sIxType</em><br> + <li>NDX<br> + <li>MDX<br> + <em>sIndexName</em> - index file name + </td> +</tr> + +<tr><td> virtual xbInt16 Reindex( xbInt16 iTagOpt )</td><td>Reindex</td> + <td> + <em>iTagOpt</em><br> + <li>0 - Reindex current tag<br> + <li>1 - Reindex all tags + </td> +</tr> + +<tr><td> virtual xbInt16 SetCurTag( const xbString &sTagName )</td><td>Set current tag.</td> + <td> + <em>sTagName</em> Tag name + </td> +</tr> + +<tr><td> virtual void SetCurTag( const xbString &sIxType, xbIx *pIx, void *vpTag )</td><td>Set current tag.</td> + <td> + <em>sIxType</em><br> + <li>NDX<br> + <li>MDX<br> + <em>pIx</em> - Pointer to index object<br> + <em>vpTag</em> - Pointer to tag object + </td> +</tr> + +<tr><td> virtual xbInt16 AssociateIndex( const xbString &sType, const xbString &sName, xbInt16 iOption )</td> + <td>Use this method to add an NDX index file name to an INF file.<br> + When a DBF file is opened, Xbase64 automatically opens NDX index files that are included in the appropriate INF file. + This is also used for ODBC compatibility with other xbase type tools. + </td> + <td> + <em>sIxType</em> Currently only NDX.<br> Future versions can support additional non prod index types.<br> + <em>sIxName</em> The index name.<br> + <em>iOpt</em><br> + <li>0 - Add index to .INF if not already there<br> + <li>1 - Remove index from .INF if it exists + </td> +</tr> + +<tr><td> xbLinkListNode<xbString> *GetInfList() const</td><td>Returns list of INF file entries.</td></tr> +</table> + +<br><br><br> +<h2>Block Read Methods</h2> +<table border=1> +<tr><th>Method</th><th>Description</th></tr> +<tr><td>xbInt16 DisableBlockReadProcessing()</td><td>Disable block read processing for table. +<tr><td>xbInt16 EnableBlockReadProcessing()</td> + <td>Enable block read processing for table.<br> + This significantly speeds up processing speed if reading from the file sequentially.<br> + For random access, better performance will be achieved with block reading turned off. + </td> +</tr> +<tr><td>xbBool GetBlockReadStatus() const</td><td>Get block read status.</td></tr> +</table> + +</center> + + + +<br><br> <hr> +<p><img src="xbase.jpg"><br><hr> </BODY> </HTML> diff --git a/docs/html/xbc11.html b/docs/html/xbc11.html index 4230f3f..315ccc5 100755 --- a/docs/html/xbc11.html +++ b/docs/html/xbc11.html @@ -1,12 +1,146 @@ <!DOCTYPE HTML PUBLIC> <HTML> -<TITLE>Xbase DBMS Chapter 10</TITLE> +<TITLE>Xbase DBMS Chapter 11</TITLE> <BODY BGCOLOR=#FFFFFF> -<H2><p align="center">CDX Indices</p></H2> -<p align="center">Chapter Updated 11/28/22</p><hr> +<H2><p align="center">Logging</p></H2> +<p align="center">Chapter Updated 04/28/23</p><hr> -<h3>Pending IDX index module development.</h3> +<br><br> +The objective of this chapter is to provide information regarding the logging funcitionality contained within the Xbase64 library. +<br><br> +When the Xbase64 generates an error, it writes an entry in the logfile if logging is enabled. +The library generates an error mesage with an error code value and an error stop value. +The error code identifies what the error is, the error stop identifies where it errored in the libary. + +<br><br> +The xbLog class supports the following functionality:<br><br> +<li>Error and message logging. +<li>Rolling log files. When log file fills, full file is closed and new file is opened. +<li>Configurable size. +<li>Configurable name. +<li>Configurable location. +<br><br><br> + + +<h3>Default Logfile Settings:</h3> +<table border=1> +<tr><th>Setting</th><th>Default Value</th><th>Initialization Source</th></tr> +<tr><td>Folder:</td><td>#define PROJECT_LOG_DIR</td><td>CMakelists.txt</td></tr> +<tr><td>Name:</td><td>#define PROJECT_DFLT_LOGFILE</td><td>xbconfig.h.in</td></tr> +<tr><td>Size:</td><td>100000</td><td>xbLog::xbLog()</td></tr> +</table> + +<br><br> +<br><br> + +The logfile is controlled by the main xbXBase class via the methods listed in the table below. +To change the logfile location or name or size, use the DisableMsgLogging() and EnableMessageLogging() +to get the updates to take effect. + +<br><br> + + +<h3>Methods for managing the logfile</h3> +<table border=1> +<tr><th>Method</th><th>Description</th></tr> +<tr><td>xbString& xbSsv::GetLogDirectory() const</td><td>Get the log file directory.</td><tr> +<tr><td>xbString& xbSsv::GetLogFileName() const</td><td>Get the log file name.</td></tr> +<tr><td>xbString& xbSsv::SetLogDirectory( const xbString &sLogDirectory )</td><td>Set the log file directory.</td><tr> +<tr><td>void xbSsv::SetLogFileName( const xbString &sLogFileName )</td><td>Set the log file name.</td></tr> +<tr><td>void xbXBase::DisableMsgLogging()</td><td>Disable message logging.</td></tr> +<tr><td>void xbXBase::EnableMsgLogging()</td><td>Enable message logging.</td></tr> +<tr><td>xbInt16 xbXBase::FlushLog()</td><td>Flush any buffered log file messages to disk.</td></tr> +<tr><td>const xbXBase::xbString &GetLogFqFileName() const</td><td>Get fully qualified logfile name.</td></tr> +<tr><td>size_t xbXBase::GetLogSize() const</td><td>Get the log file roll over size.</td></tr> +<tr><td>xbBool xbXBase::GetLogStatus() const</td><td>Get the logging file status.</td></tr> +<tr><td>void xbXBase::SetLogSize( size_t lSize )</td><td>Set the logfile roll over size.</td></tr> +</table> + + +<br><br> +<h3>Example program demonstrating logfile related methods.</h3> + +<xmp> +/* xb_ex_log.cpp + +XBase64 Software Library + +Copyright (c) 1997,2003,2014,2022,2023 Gary A Kunkel + +The xb64 software library is covered under the terms of the GPL Version 3, 2007 license. + +Email Contact: + + XDB-devel@lists.sourceforge.net + XDB-users@lists.sourceforge.net + +*/ + +// This program demostrates how to use logging + + +#include "xbase.h" + +using namespace xb; + +int main( int argCnt, char **av ) +{ + + #ifdef XB_LOGGING_SUPPORT + + xbXBase x; + xbString sMsg; + + + std::cout << "Default Logfile Name is: [" << x.GetLogFqFileName().Str() + << "] Rollover size = [" << x.GetLogSize() + << "]" << std::endl; + + if( x.GetLogStatus() ) + std::cout << "Logging is active" << std::endl; + else + std::cout << "Logging is inactive" << std::endl; + + x.SetLogDirectory( PROJECT_LOG_DIR ); // use the library log directory + x.SetLogFileName ( "MySpecialLogFile.txt" ); // set to use a special name + x.SetLogSize ( x.GetLogSize() * 2 ); // double the log file size + + // enable the logfile and write a message for the new settings to take effect + x.EnableMsgLogging(); + sMsg.Sprintf( "Program [%s] initializing...", av[0] ); + x.WriteLogMessage( sMsg ); + + std::cout << "New Logfile Name is: [" << x.GetLogFqFileName().Str() + << "] Rollover size = [" << x.GetLogSize() + << "]" << std::endl; + + if( x.GetLogStatus() ) + std::cout << "Logging is active" << std::endl; + else + std::cout << "Logging is inactive" << std::endl; + + // write some messages to the logfile + for( int i = 0; i < 5; i++ ){ + sMsg.Sprintf( "Test message [%d]", i ); + x.WriteLogMessage( sMsg ); + } + + sMsg.Sprintf( "Program [%s] terminating..", av[0] ); + x.WriteLogMessage( sMsg ); + + x.FlushLog(); // not really needed, but here for demonstration purposes + + #endif // B_LOGGING_SUPPORT + + return 0; +} + +</xmp> + + +<br><br> <hr> +<p><img src="xbase.jpg"><br><hr> </BODY> </HTML> diff --git a/docs/html/xbc12.html b/docs/html/xbc12.html index a40c7e0..29d6dc1 100755 --- a/docs/html/xbc12.html +++ b/docs/html/xbc12.html @@ -2,85 +2,278 @@ <HTML> <TITLE>Xbase DBMS Chapter 12</TITLE> <BODY BGCOLOR=#FFFFFF> -<H1><p align="center">Record and File Locking</p></H1> -<p align="center">Chapter Updated 12/13/22</p><hr> +<H2><p align="center">Dates</p></H2> +<p align="center">Chapter Updated 04/28/23</p><hr> -<h3>Locking Overview</h3> +<br><br> -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.<br><br> +<h3>Class xbDate methods</h3> +<table border=1> +<tr><th>Method</th><th>Description</th></tr> -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(). -<br><br> -Locking can also be enabled / disabled at the table level with with xbDbf::SetAutoLock().<br><br> -If autolocking is disabled and the code base is being used in a multi user environment, it is -up to the application program to verify the needed locks are set as there is no checking or -setting any locks if autolocking is turned off. It is only safe to turn off the autolocking functionality -if the library is being used in a single user environment. -<br><br> -The current Xbase64 record locking logic is modeled after DBase (tm) V7 locking. -<br><br> +<tr><td>xbDate()<br>xbDate( const char * Date8 )<br>xbDate( const xbString &Date8 )<br>xbDate( xbInt32 lJulDate )</td><td>xbDate constructor.</td></tr> +<tr><td>xbDate( xbUInt16 iInit )</td><td>Special xbDate constructor, called to initialize static variables and/or set to Sysdate</td></tr> -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 -<em>errno</em> or function <em>perror()</em> can be executed to view the -results. -<br><br> +<tr><td>void operator=( const xbDate &d )</td><td>Set a date equal to another date.</td></tr> +<tr><td>void operator+=( xbInt32 i )</td><td>Increment a date.</td><tr> +<tr><td>void operator-=( xbInt32 i )</td><td>Decrement a date.</td><tr> +<tr><td>void operator++( xbInt32 i )</td><td>Increment a date.</td><tr> +<tr><td>void operator--( xbInt32 i )</td><td>Decrement a date.</td><tr> -The errno field may contain one of the following values if the lock was not -successful.<br><br> -<TABLE BORDER> -<TR VALIGN="BASELINE"> -<TR><TH ALIGN="LEFT">Error Code<TD>Description -<TR><TH ALIGN="LEFT">EBADF<TD>Invalid file descriptor -<TR><TH ALIGN="LEFT">EINVAL<TD>Invalid lock information or file does not support locks -<TR><TH ALIGN="LEFT">EACCESS<BR>EAGAIN<TD>Lock can not be set because it is blocked by an existing lock on the file. -<TR><TH ALIGN="LEFT">ENOLCK<TD>The system is out of lock resources, too many file locks in place. -<TR><TH ALIGN="LEFT">EDEADLK<TD>Deadlock condition -<TR><TH ALIGN="LEFT">EINTR<TD>Process was interrupted by a signal while it was waiting -</TABLE> -<br><br> +<tr><td>xbInt32 operator-( const xbDate & ) const</td><td>Determine the number of days between two dates.</td><tr> +<tr><td>const char * operator-( xbInt32 i )</td><td>Subtract <em>i</em> days from a date.</td><tr> +<tr><td>const char * operator+( xbInt32 i )</td><td>Add <em>i</em> days to a date.</td><tr> -<h3>Linux/Windows File Locking Compatibility Issue</h3> +<tr><td>xbBool operator==( const xbDate & ) const</td><td>Compare for equal dates.</td><tr> +<tr><td>xbBool operator!=( const xbDate & ) const</td><td>Compare for not equal dates.</td><tr> +<tr><td>xbBool operator< ( const xbDate & ) const</td><td>Compare for less than date.</td><tr> +<tr><td>xbBool operator> ( const xbDate & ) const</td><td>Compare for greater than date.</td><tr> +<tr><td>xbBool operator<=( const xbDate & ) const</td><td>Compare for less than or euql to date.</td><tr> +<tr><td>xbBool operator>=( const xbDate & ) const</td><td>Compare for greater than or equal to date.</td><tr> -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. -<br><br> -In Unix, a program can not lock a file so another process can not access it.<br> -In Windows, a program can lock a file so another process can not access it.<br> -DBase(tm) supports routines to open files exclusively, preventing other users from opening a file.<br> -Locking on the Mac/Apple platform only works on NFS shares. It does not work with SMB shares. +<tr><td>xbInt16 CalcRollingCenturyForYear( xbInt16 year ) const</td><td>Calculate century for a give 2 digit year. Uses 80/20 method.</td><tr> +<tr><td>xbInt16 CenturyOf() const</td><td>Return century of the date.</td><tr> +<tr><td>xbInt16 CharDayOf( xbString &sOutCharDay )</td><td>Retrieve the character day.</td><tr> +<tr><td>xbInt16 CharMonthOf( xbString &sOutCharMonth )</td><td>Retrive the character month.</td><tr> +<tr><td>xbBool DateIsValid ( const xbString &sDate8 ) const;</td><td>Check if a given date is valid.</td><tr> +<tr><td>xbInt16 DayOf( xbInt16 iFormat ) const</td><td>Return Day of week, month or year depending on the option.</td><tr> +<tr><td>xbInt16 CTOD( const xbString &sCtodInDate )</td><td>Sets the date from input date in format MM/DD/YY</td><tr> +<tr><td>xbInt16 FormatDate( const xbString &sFmtIn, xbString &sFmtOut )</td><td>Create a formatted date string based on input format.</td><tr> +<tr><td>const char *Str() const</td><td>Return a pointer the date value.</td><tr> +<tr><td>xbBool IsLeapYear( xbInt16 iYear ) const<br>IsLeapYear() const</td><td>Returns true if leap year, otherwise returns false.</td><tr> +<tr><td>xbBool IsNull() const</td><td>Returns xbTrue is the date is null, else returns false.</td><tr> +<tr><td>xbInt32 JulianDays() const</td><td>Return the Julian days value.</td><tr> +<tr><td>xbInt16 JulToDate8( xbInt32 lJulDate )</td><td>Convert a Julian date to xbDate value.</td><tr> +<tr><td>xbInt16 LastDayOfMonth()</td><td>Calculate the last day of a month for the given teat and month.</td><tr> +<tr><td>xbInt16 MonthOf() const</td><td>Return the numeric month of the date.</td><tr> +<tr><td>xbInt16 Set( const xbString &Date8 )</td><td>Set the date to valid input date.</td><tr> +<tr><td>xbInt16 Sysdate()</td><td>Set the date to the system date.</td><tr> +<tr><td>xbInt16 YearOf() const</td><td>Return the numeric year of the date.</td><tr> + +</table> + +<br><br><hr><br><br> +<h2>Example program using xbDate class</h2> + +<xmp> +/* xb_ex_date.cpp + + +XBase64 Software Library + +Copyright (c) 1997,2003,2014,2021,2022 Gary A Kunkel + +The xb64 software library is covered under the terms of the GPL Version 3, 2007 license. + +Email Contact: + + XDB-devel@lists.sourceforge.net + XDB-users@lists.sourceforge.net + +This program demonstrates using the xbDate class + +*/ + + +#include "xbase.h" + +using namespace xb; + +int main() +{ + + xbXBase x; /* initial date static variables */ + + xbString StringDate( "19601007" ); /* oct 7 1960 */ + char CharDate[9] = "19611109"; /* nov 9 1961 */ + + xbDate d1; /* today is default */ + xbDate d2( StringDate ); /* from string data */ + xbDate d3( CharDate ); /* from char data */ + xbDate d4; /* another date class */ + xbString s; + + std::cout << "This program demonstrates usage of the xbDate class" << std::endl; + std::cout << "Date 1 (Sysdate) is " << d1.Str() << std::endl; + std::cout << "Date 2 (StringDate) is " << d2.Str() << std::endl; + std::cout << "Date 3 (CharDate) is " << d3.Str() << std::endl; + + std::cout << "This year is " << d1.YearOf() << std::endl; + std::cout << "Year of xbString Date is " << d2.YearOf() + << std::endl; + std::cout << "Year of char Date is " << d3.YearOf() + << std::endl; + + std::cout << "This Month is " << d1.MonthOf() << std::endl; + std::cout << "Month of xbString Date is " << d2.MonthOf() + << std::endl; + std::cout << "Month of char Date is " << d3.MonthOf() + << std::endl; + + std::cout << "Today is day " << d1.DayOf( XB_FMT_WEEK ) << " of the week" << std::endl; + std::cout << "StringDate is day " << d2.DayOf( XB_FMT_MONTH ) << " of the month" << std::endl; + std::cout << "CharDate is day " << d3.DayOf( XB_FMT_YEAR ) << " of the year" << std::endl; -<br><h3>Samba settings</h3> + if( d1.IsLeapYear()) + std::cout << "This is a leap year" << std::endl; + else + std::cout << "This is not a leap year." << std::endl; -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:<br> -<br> -[sharename]<br> -oplocks = False<br> -level2 oplocks = False + if( d2.IsLeapYear()) + std::cout << "StringDate is a leap year" << std::endl; + else + std::cout << "StringDate is not a leap year." << std::endl; + if( d3.IsLeapYear()) + std::cout << "CharDate is a leap year" << std::endl; + else + std::cout << "CharDate is not a leap year." << std::endl; -<br><h3>iLockFlavor</h3> + std::cout << "Today is " << d1.Sysdate() << std::endl; -The library was constructed in a manner so that it could be updated to support alternate lock "flavors". -The 4.x.x library is built to mirror the DBase locking, but the structure is in place to expand to other locking -types if needed. + if( d1.DateIsValid( "19951301" )) + std::cout << "19951301 is a valid date" << std::endl; + else + std::cout << "19951301 is not a valid date" << std::endl; + if( d1.DateIsValid( "19920229" )) + std::cout << "19920229 is a valid date" << std::endl; + else + std::cout << "19920229 is not a valid date" << std::endl; + if( d2.DateIsValid( StringDate )) + std::cout << StringDate.Str() << " is a valid date" << std::endl; + else + std::cout << StringDate.Str() << " is not a valid date" << std::endl; + std::cout << "Today's Julian date " << d1.JulianDays() << std::endl; + std::cout << "Julian date of Jan 01, 1970 " << d2.JulianDays() << std::endl; + std::cout << "StringDate Julian date " << d2.JulianDays() << std::endl; -<br><br><br> -<hr><br> + std::cout << "There are " << (d1.JulianDays() - d2.JulianDays()) << " days between " << d1.Str() << " and " << d2.Str() << std::endl; + + std::cout << "Todays Julian date (Number of days since Jan 1 0100):" << d1.JulianDays() << std::endl; + + d4 = d1; // set d4 class = to sysdate + std::cout << "Object d4 initialized to " << d4.Str() << std::endl; + std::cout << "This should be todays date: " + << d4.JulToDate8(d4.JulianDays()) << std::endl; + std::cout << "In 7 days it will be " + << d4.JulToDate8(d4.JulianDays() + 7L ) << std::endl; + + d1.CharDayOf( s ); + std::cout << "Today is " << s.Str() << std::endl; + + d2.CharDayOf( s ); + std::cout << "StringDate day is " << s.Str() << std::endl; + d1.CharMonthOf( s ); + std::cout << "This month is " << s.Str() << std::endl; + d2.CharMonthOf( s ); + std::cout << "StringDate month is " << s.Str() << std::endl; + + + /* various format routines using different formats, strings and chars */ + xbString sOutDate; + + d1.FormatDate( "YYDDD", sOutDate ); + std::cout << "Format (YYDDD) = " << sOutDate.Str() << std::endl; + + d1.FormatDate( "MM/DD/YY", sOutDate ); + std::cout << "Format (MM/DD/YY) = " << sOutDate.Str() << std::endl; + + d1.FormatDate( "YY-MM-DD", sOutDate ); + std::cout << "Format (YY-MM-DD) = " << sOutDate.Str() << std::endl; + + d1.FormatDate( "DDDDDDDDD, MMMMMMMMMM DD YYYY", sOutDate ); + std::cout << "Format (DDDDDDDDD, MMMMMMMMMM DD YYYY) = " << sOutDate.Str() << std::endl; + + std::cout << "Last day this month " << d1.LastDayOfMonth() << std::endl; + std::cout << "Last day of month for StringDate is " << d2.LastDayOfMonth() << std::endl; + + std::cout << "Overloaded operators test..." << std::endl; + + if( d1 == d2 ) + std::cout << d1.Str() << " is equal to " << d2.Str() + << std::endl; + else + std::cout << d1.Str() << " is not equal to " << d2.Str() + << std::endl; + + if( d1 != d3 ) + std::cout << d1.Str() << " is not equal to " << d3.Str() + << std::endl; + else + std::cout << d1.Str() << " is equal to " << d3.Str() + << std::endl; + + if( d1 < d2 ) + std::cout << d1.Str() << " is less than " << d2.Str() + << std::endl; + else + std::cout << d1.Str() << " is not less than " << d2.Str() + << std::endl; + + if( d1 > d2 ) + std::cout << d1.Str() << " is greater than " << d2.Str() + << std::endl; + else + std::cout << d1.Str() << " is not greater than " << d2.Str() + << std::endl; + + if( d1 <= d2 ) + std::cout << d1.Str() << " is less than or equal to " << d2.Str() + << std::endl; + else + std::cout << d1.Str() << " is not less than or equal to " + << d2.Str() << std::endl; + + if( d1 >= d2 ) + std::cout << d1.Str() << " is greater than or equal to " + << d2.Str() << std::endl; + else + std::cout << d1.Str() << " is not greater than or equal to " + << d2.Str() << std::endl; + + d1.Sysdate(); + d1++; + std::cout << "Tomorrow is " << d1.Str() << std::endl; + d1-=2; + std::cout << "Yesterday was " << d1.Str() << std::endl; + std::cout << "There are " << d1 - d2 << " days between " << d1.Str() + << " and " << d2.Str() << std::endl; + + d1="20140701"; + std::cout << "Operator = example " << d1.Str() << std::endl; + + d1+=5; + std::cout << "Operator += 5 example " << d1.Str() << std::endl; + + d1--; + std::cout << "Operator -- example " << d1.Str() << std::endl; + + d1-4; + std::cout << "Operator -4 example " << d1.Str() << std::endl; + + d1+10; + std::cout << "Operator +10 example " << d1.Str() << std::endl; + std::cout << "CenturyOf() " << d1.CenturyOf() << std::endl; + + xbString sWorkDate; + d1.CTOD( "10/07/60" ); + std::cout << "CTOD( '10/07/60' ) " << d1.Str() << std::endl; + + d1.Set( "19590118" ); + std::cout << "Set( '19590118' ) " << d1.Str() << std::endl; + + std::cout << "CalcRollingCenturyForYear( 95 ) = " << d1.CalcRollingCenturyForYear( 95 ) << std::endl; + return 0; +} +</xmp> + +<br><br> +<hr> <p><img src="xbase.jpg"><br><hr> -</BODY> -</HTML> +</body> +</html> diff --git a/docs/html/xbc13.html b/docs/html/xbc13.html deleted file mode 100755 index 9f51a85..0000000 --- a/docs/html/xbc13.html +++ /dev/null @@ -1,46 +0,0 @@ - -<!DOCTYPE HTML PUBLIC> -<HTML> -<TITLE>Xbase DBMS Chapter 13</TITLE> -<BODY BGCOLOR=#FFFFFF> -<H2><p align="center">Logfiles</p></H2> -<p align="center">Chapter Updated 11/29/22</p><hr> - - -<h3>Logging</h3> - -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. - -<hr> - -#include "xbase.h"<br> -using namespace xb;<br> -<br> -int main( int argCnt, char **av ){<br> - - #ifdef XB_LOGGING_SUPPORT<br> - xbString sMsg;<br> - xbString sLogFileName;<br> - xbXBase x;<br> - sLogFileName = "/home/xbase/logfiles/LogFile.txt";<br> - x.SetLogFileName( sLogFileName );<br> - x.EnableMsgLogging(); <br><br> - - - std::cout << "Logfile is [" << x.GetLogFqFileName().Str() << "]" << std::endl;<br> - sMsg.Sprintf( "Program [%s] initializing...", av[0] );<br> - x.WriteLogMessage( sMsg );<br> - std::cout << "Logging status is " << x.GetLogStatus() << std::endl;<br> - sMsg = "A logfile message";<br> - x.WriteLogMessage( sMsg );<br> - x.DisableMsgLogging();<br> - #endif /* XB_LOGGING_SUPPORT */<br> - return 0;<br> -}<br> - -<hr> -<p><img src="xbase.jpg"><hr> -</BODY> -</HTML> diff --git a/docs/html/xbc14.html b/docs/html/xbc14.html deleted file mode 100755 index 2c086df..0000000 --- a/docs/html/xbc14.html +++ /dev/null @@ -1,113 +0,0 @@ -<!DOCTYPE HTML PUBLIC> -<HTML> -<TITLE>Xbase DBMS Chapter 14</TITLE> -<BODY BGCOLOR=#FFFFFF> -<H2><p align="center">CDX Indices</p></H2> -<p align="center">Chapter Updated 12/08/22</p><hr> - -<h3>SQL Command Status</h3> - -Development of SQL support is still underway and very preliminary. As of the 4.0.3 version, the following SQL commands -are available.<br><br> -The SQL commands are modeled after industry standard SQL specifications and do what you would expect an SQL command to do. -<br> -Use of <em>[brackets]</em> in this chapter identifies optional components of a given command. -<br><br> -<hr> -<h3>ALTER TABLE</h3> -Expected format:<br> -ALTER TABLE tablename.DBF RENAME TO newtablename.DBF -<br><br> -<hr> -<h3>CREATE INDEX</h3> -Expected format to create an Dbase 3, NDX index:<br> -CREATE INDEX ixname.NDX ON tablename.dbf ( EXPRESSION ) [ASSOCIATE] - -<br><br> -Expected format to create an Dbase 4, tag on an MDX index:<br> -CREATE [UNIQUE] INDEX tagname ON tablename.DBF ( EXPRESSION ) [DESC] [FILTER .NOT. DELETED()] - -<br><br> -The ASSOCIATE parameter is specific to Xbase64 library, it is used to associate non production (NDX) index file to a dbf -file so it will be automatically opened with the dbf file whenever the dbf file is opened by the xbase64 routines. -<br><br> -The [ASSOCIATE] parameter is not used with MDX production indices -<br><br> -Xbase first looks for ".NDX" in the file name to determine if an NDX index should be created. -If .NDX is not in the filename, it looks in the uda for "IXTYPE" for either NDX or MDX to -detmermine the index type to create. if IXTYPE is not found, it creates an MDX tag. -<br><br> -The optional DESC parameter defines an entire index key as descending. This is -different than other SQL implementations where specific fields can be descending. -<br><br> -The optional FILTER parameter is specific to the XBASE64 library, is it used to assign a filter to a tag in an -MDX style index. Everything to the right of the keyword FILTER is considered part of the filter. -<br><br> -The original DBASE indices used to '+' to create an index on more than one field -<br>ie: FIELD1+FIELD2+FIELD3 -<br><brSQL uses commas: ie: FIELD1, FIELD2, FIELD3 -<br> -The Xbase library supports either '+' or ',' when creating mutli field indices. -<br><br> -<hr> - - - -<h3>CREATE TABLE</h3> -Expected format:<br> -CREATE TABLE tablename.dbf (Field1 CHAR(10), INTFLD1 INTEGER, ... ) -<br><br> -<table border=1> -<tr><th>SQL TYPE</th><th>XBASE Field Type</th></tr> -<tr><td>SMALLINT</td><td>NUMERIC(6,0)</td></tr> -<tr><td>INTEGER</td><td>NUMERIC(11,0)</td></tr> -<tr><td>DECIMAL(x,y)</td><td>NUMERIC(x+1,y)</td></tr> -<tr><td>NUMERIC(x,y)</td><td>NUMERIC(x,y)</td></tr> -<tr><td>FLOAT(x,y)</td><td>FLOAT(x,y)</td></tr> -<tr><td>CHAR(n)</td><td>CHARACTER(n)</td></tr> -<tr><td>DATE</td><td>DATE</td></tr> -<tr><td>VARCHAR</td><td>MEMO</td></tr> -<tr><td>LOGICAL</td><td>LOGICAL</td></tr> -</table> -<br> -<hr> - - -<h3>DELETE</h3> -Expected format:<br> -DELETE FROM tablename.DBF [WHERE expression] -<br><br> -<hr> - - -<h3>DROP INDEX</h3> -Expected format:<br> -DROP INDEX [IF EXISTS] ixname.NDX ON tablename.DBF<br> -DROP INDEX [IF EXISTS] tagname ON tablename.DBF<br> -<br> - - -<hr> -<h3>DROP TABLE</h3> -Expected format:<br> -DROP TABLE [IF EXISTS] tablename.DBF -<br> -<hr> -<h3>INSERT</h3> -Expexted format:<br> -INSERT INTO tablename (field1, field2, field3,...) VALUES ( 'charval', numval, 'what is the correct odbc date format to use? CCYYMMDD'); -<br><br> -<hr> -<h3>SET</h3> -Used to set a variable name<br> -Expected format:<br> -SET ATTRIBUTE = DATAVALUE<br> -SET ATTRIBUTE = ^ (to delete an entry) <br> -<br> -<hr><br><br> -<p><img src=xbase.jpg><br><hr> - -</BODY> -</HTML> - - diff --git a/docs/html/xbc15.html b/docs/html/xbc15.html deleted file mode 100755 index fde33b8..0000000 --- a/docs/html/xbc15.html +++ /dev/null @@ -1,96 +0,0 @@ - -<!DOCTYPE HTML PUBLIC> -<HTML> -<TITLE>Xbase DBMS Chapter 15</TITLE> -<BODY BGCOLOR=#FFFFFF> -<H2><p align="center">Block Read Functionality</p></H2> -<p align="center">Chapter Updated 2/1/23</p><hr> - - -<h3>Block Reads</h3> - -As of release 4.1.1, the Xbase library includes functionality for reading a DBF file in blocks, rather than one record at a time.<br><br> - -This functionality can be used to improve application performance in situations where a data file is being read sequentially. -For situations where records are retrieved randomly from the file, enabling this probably won't help much. In short, this -can be turned on when accessing a file sequentially and should be left off when not processing sequentially.<br><br> - -The logic is all handled internally within the library, all that is needed is to enable it and the library handles the rest.<br><br> - -<h3>One Caveat</h3> -This functionality was originally designed with reporting in mind and doesn't currently have any auto locking associated with it. -<br><br> - - -<h3>Sample Code</h3> -See example code below for how to enable and disable the feature. - - -<hr> - -#include "xbase.h"<br> -using namespace xb;<br> -<br> -int main(int ac,char** av)<br> -{<br> - xbXBase x;<br> - xbInt16 iRc;<br> - x.EnableMsgLogging();<br> - x.SetLogSize( 1000000L );<br> -<br> - if (ac <= 1) {<br> - std::cout << "Usage: xb_dumprecs filename..." << std::endl;<br> - return 1;<br> - }<br> -<br> - xbDbf *MyFile = NULL;<br> - if(( iRc = x.OpenHighestVersion( av[1], "", &MyFile )) != XB_NO_ERROR ){<br> - std::cout << "Could not open file iRc = " << iRc << " file = " << av[1] << std::endl;<br> - x.DisplayError( iRc );<br> - return 0;<br> - }<br> -<br> -// std::cout << "Processing file sequentially from beginning..." << std::endl;<br> -<br> -<br> -<b> - // turn on Block Read Processing<br> - #ifdef XB_BLOCKREAD_SUPPORT<br> - MyFile->EnableBlockReadProcessing();<br> - #endif<br> -</b> -<br> - xbUInt32 j = 0;<br> - xbUInt32 ulRecCnt = 0;<br> -<br> - iRc = MyFile->GetRecordCnt( ulRecCnt );<br> -<br> - if( iRc < XB_NO_ERROR )<br> - return iRc;<br> - while( j < ulRecCnt ){<br> - if( j == 0 )<br> - iRc = MyFile->DumpRecord(++j, 2, 2 );<br> - else<br> - iRc = MyFile->DumpRecord(++j, 2, 1 );<br> - if( iRc != XB_NO_ERROR ){<br> - x.DisplayError( iRc );<br> - return 1;<br> - }<br> - }<br> - std::cout << j << " Records processed." << std::endl;<br> -<br> -<br><b> - // optionally turn off Block Read Processing<br> - #ifdef XB_BLOCKREAD_SUPPORT<br> - MyFile->DisableBlockReadProcessing();<br> - #endif<br></b> -<br> - MyFile->Close();<br> - return 0;<br> -}<br> -<br> - -<hr> -<p><img src="xbase.jpg"><hr> -</BODY> -</HTML> diff --git a/docs/html/xbc16.html b/docs/html/xbc16.html deleted file mode 100755 index 873264d..0000000 --- a/docs/html/xbc16.html +++ /dev/null @@ -1,52 +0,0 @@ -<!DOCTYPE HTML PUBLIC> -<HTML> -<TITLE>Xbase DBMS Chapter 16</TITLE> -<BODY BGCOLOR=#FFFFFF> -<H2><p align="center">Class Inventory</p></H2> -<p align="center">Chapter Updated 2/1/23</p><hr> -<br> -<center><h3>Class Descriptions</h3></center> - -<center> -<table border=1> -<tr><th>Class</th><th>Description</th></tr> -<tr><td>xbBcd</td><td>Supports binary coded decimal data</td></tr> -<tr><td>xbBlockRead<td>Supports block read functionality for improved sequential file access performance.</td></tr> -<tr><td>xbDate</td><td>Support date operations on a given date formatted as YYYYMMDD</td></tr> -<tr><td>xbDbf</td><td>Base class for DBF file handling. If you are adding support for a new file type, <br>derive new file type class from this.</td></tr> -<tr><td>xbDbf3</td><td>Derived from xbDbf, supports DBase V3 files</td></tr> -<tr><td>xbDbf4</td><td>Derived from xbDbf, supports DBase V4 files</td></tr> -<tr><td>xbExp</td><td>Class for supporting expression logic</td></tr> -<tr><td>xbExpNode</td><td>Class definition of a single node, utilized by xbExp</td></tr> -<tr><td>xbFile</td><td>Main file class. If you are porting this library to another platform, start here</td></tr> -<tr><td>xbFilter</td><td>Supports filters</td></tr> -<tr><td>xbIx</td><td>Base class for index file support. If you are adding support for a new index type, <br>derive new index type class from this.</td></tr> -<tr><td>xbIxNdx</td><td>Derived from xbIx, supports NDX style indices.</td></tr> -<tr><td>xbIxMdx</td><td>Derived from xbIx, supports MDX style indices</td></tr> -<tr><td>xbLinkList</td><td>Class supporting linked list functionality</td></tr> -<tr><td>xbLinkListOrd</td><td>Class supporting ordered linked list functionality</td></tr> -<tr><td>xbLinkListNode</td><td>Class defining one node, used by xbLinkList and xbLinkListOrd</td></tr> -<tr><td>xbLog</td><td>Class supporting general log file activity</td></tr> -<tr><td>xbMemo</td><td>Base class for supporting memo (.DBT) files. If you are adding support for a new memo type, <br>derive new memo type class from this.</td></tr> -<tr><td>xbMemoDbt3</td><td>Derived from xbMemo, supports V3 Memo files</td></tr> -<tr><td>xbMemoDbt4</td><td>Derived from xbMemo, supports V3 Memo files</td></tr> -<tr><td>xbSql</td><td>Supports SQL access</td></tr> -<tr><td>xbSsv</td><td>Base class, shared system values</td></tr> -<tr><td>xbString</td><td>String handling class</td></tr> -<tr><td>xbTag</td><td>Class to support index tags</td></tr> -<tr><td>xbTblMgr</td><td>Class used internally in the library for managing multiple open files/tables</td></tr> -<tr><td>xbUda</td><td>Class for supporting fields for the xbSql functions. Stands for User data area</td></tr> -<tr><td>xbXBase</td><td>Class to tie everything together. Every application program starts with one of these</td></tr> -</table> -</center> - -<hr> -<br><br> -Fix me... -<p><img src="Xbase64ClassDiagram.jpg"><br> - -<br><br> -<hr> -<p><img src="xbase.jpg"><br><hr> -</BODY> -</HTML> diff --git a/docs/html/xbc17.html b/docs/html/xbc17.html deleted file mode 100755 index c0b2208..0000000 --- a/docs/html/xbc17.html +++ /dev/null @@ -1,219 +0,0 @@ -<!DOCTYPE HTML PUBLIC> -<HTML> -<TITLE>Xbase DBMS Chapter 17</TITLE> -<BODY BGCOLOR=#FFFFFF> -<H2><p align="center">Class xbSsv</p></H2> -<p align="center">Chapter Updated 2/7/23</p><hr> - -<h3>Class xbSsv - Shared System Values.</h3> - -Base class xbSsv is used for maintaining static variables used system -wide by the XBase library routines and is a base class that is used by the xbXBase class. -See the diagram in chapter 15 to gain an understanding of where the xbSsv class sits in relation to the -other classes. Accessing the methods in this class are done via the xbXBase class instance.<br><br> -Additionally, there are a few other misc routines contained in this class that are available to all -subordinate classes/objects. -<br><br><br><br> - - -<center> -<table border=1> -<tr><th width=40%>Method</th><th>Description</th></tr> - -<tr><td>void BitDump( unsigned char c ) const<br>void BitDump( char c ) const</td><td>These routines dump the bits for a specified char field to stdout.</td></tr> -<tr><td>xbBool BitSet( unsigned char c, xbInt16 iBitNo ) const</td><td>This routine will set a specified bit in a char field.</td></tr> -<tr><td>void DisplayError( xbInt16 ErrorCode ) const</td><td>This routine prints a description for a specifed error to stdout.</td></tr> - -<tr><td>xbString& GetDataDirectory() const<br>void SetDataDirectory( const xbString &sDataDirectory )</td> - <td>Get and Set the current directory where the library routines expect to find the .DBF, .DBT, .NDX and .MDX files.</td></tr> - -<tr><td>xbString& GetDefaultDateFormat() const<br>void SetDefaultDateFormat( const xbString &sDefaultDateFormat )</td> - <td>Get and Set the current default date format used by the date formatting routines if no format specifier is provided.</td></tr> - -<tr><td>xbInt16 GetEndianType() const</td><td>Returns the current Endian type of the machine the library is operating on.</td></tr> -<tr><td>const char *GetErrorMessage( xbInt16 ErrorCode ) const</td><td>Returns a pointer to an error message for a given error number.</td></tr> - -<tr><td>xbBool GetDefaultAutoCommit() const<br>void SetDefaultAutoCommit( xbBool bDefaultAutoCommit )</td> - <td>Get and Set the default auto commit status. If auto commit is on, the library will automatically post any updates to the database when navigating away from an updated record.</td></tr> - -<tr><td>xbBool GetHomeDir( xbString &sHomeDirOut )</td><td>Get the home directory for the current user.</td></tr> - -<tr><td>xbString& GetLogDirectory() const<br>void SetLogDirectory( const xbString &sLogDirectory )</td> - <td>Get and set the directory location for any system generated logfiles.</td></tr> -<tr><td>xbString& GetLogFileName() const</td><td>Returns the default log file name.</td></tr> - - -<tr><td>xbBool GetMultiUser() const<br>void SetMultiUser( xbBool bMultiUser )</td> - <td>Get and set multi user status. This turns the auto locking on and off. For better performance in single user applications, turn multuser off.</td></tr> - -<tr><td>xbInt16 GetUniqueKeyOpt() const<br>xbInt16 SetUniqueKeyOpt( xbInt16 iUniqueKeyOpt )</td> - <td>Determines library behavior for unique key processing. The original Dbase (tm) product allowed duplicate recrds in the .DBF file when the unique option was specified for a given index tag. - The Xbase library supports either the original DBase behavior (XB_EMULATE_DBASE), or the prevention of duplicate records for duplicate keys (XB_HALT_ON_DUPKEY).</td></tr> - - -<tr><td>xbInt16 GetDefaultLockRetries() const<br>void SetDefaultLockRetries( xbInt16 iRetryCount )</td> - <td>Get and Set the number of times to attempt a lock</td></tr> - -<tr><td>xbInt32 GetDefaultLockWait() const<br>void SetDefaultLockWait( xbInt32 lRetryWait ) - </td><td>Get and Set the wait time between lock attempts.</td></tr> - -<tr><td>xbInt16 GetDefaultLockFlavor() const<br>void SetDefaultLockFlavor( xbInt16 iLockFlavor ) - </td><td>For future use. With current versions, only DBase (TM) locking offsets are supported.</td></tr> - -<tr><td>xbBool GetDefaultAutoLock() const<br>void SetDefaultAutoLock( xbBool bAutoLock )<br>void EnableDefaultAutoLock()<br>void DisableDefaultAutoLock() - </td><td>Set, Get or update Auto Lock Status</td></tr> - - -<tr><td>xbInt16 GetCreateMdxBlockSize() const<br>xbInt16 SetCreateMdxBlockSize( xbInt16 ulBlockSize ) - </td><td>Set or get MDX Index block size. Must be a multiple of 512.</td></tr> - -<tr><td>xbUInt32 GetDefaultBlockReadSize() const<br>void SetDefaultBlockReadSize( xbUInt32 ulDfltBlockReadSize ) - </td><td>Set or Get the default block size for Block Read functionality. Block reading is used to improve sequentential access performance.</td></tr> -</table> - -<br><br> - -<h3>Example program using xbSsv methods</h3> -</center> -<xmp> -/* xb_ex_ssv.cpp -XBase64 Software Library - -Copyright (c) 1997,2003,2014,2021,2022,2023 Gary A Kunkel - -The xb64 software library is covered under the terms of the GPL Version 3, 2007 license. - -Email Contact: - - XDB-devel@lists.sourceforge.net - XDB-users@lists.sourceforge.net - -This program demonstrates using functionality of the xbSsv class (Shared system values) - -*/ - -#include "xbase.h" - -using namespace xb; - -int main( int ac, char ** av ){ - - xbXBase x; // set up xbase for business - xbString sMsg; // a message string - - sMsg.Sprintf( "Program [%s] initializing...", av[0] ); - std::cout << sMsg.Str() << std::endl; - - // example code to set up log file usage - #ifdef XB_LOGGING_SUPPORT - char cSeperator; // is this a unix (/) or windows (\) file system - xbString sLog; // general string for log file activities - sLog = x.GetLogFqFileName().Str(); // get the system default log file name - std::cout << "System default logfile is [" << sLog.Str() << "]" << std::endl; - - cSeperator = sLog.GetPathSeparator(); // get the seperator from - std::cout << "Path seperator = [" << cSeperator << "]" << std::endl; - - sLog.Sprintf( "..%c", cSeperator ); - x.SetLogDirectory( sLog ); - std::cout << "sLog = [" << sLog.Str() << "]\n"; - - sLog = x.GetLogFqFileName().Str(); // get the system default log file name - std::cout << "New logfile is [" << sLog.Str() << "]" << std::endl; - - // turn on logging after file name set - x.EnableMsgLogging(); - #endif // XB_LOGGING_SUPPORT - - // const char *GetErrorMessage( xbInt16 ErrorCode ) const; - // void DisplayError( xbInt16 ErrorCode ) const; - std::cout << "DisplayError( -100 ) - "; - x.DisplayError( -100 ); - // << "]" << std::endl; - - - // void SetDefaultDateFormat( const xbString &sDefaultDateFormat ); - // xbString& GetDefaultDateFormat() const; - std::cout << "GetDefaultDateFormat() - " << x.GetDefaultDateFormat() << std::endl; - - // void SetDataDirectory ( const xbString &sDataDirectory ); - // xbString& GetDataDirectory() const; - std::cout << "GetDataDirectory() - " << x.GetDataDirectory() << std::endl; - - // xbInt16 GetEndianType() const; - if( x.GetEndianType() == 'L' ) - std::cout << "Little Endian Architecture." << std::endl; - else - std::cout << "Bid Endian Architecture." << std::endl; - - //xbBool GetDefaultAutoCommit() const; - //void SetDefaultAutoCommit( xbBool bDefaultAutoCommit ); - if( x.GetDefaultAutoCommit()) - std::cout << "AutoCommit is on." << std::endl; - else - std::cout << "AutoCommit is off." << std::endl; - - //xbBool GetMultiUser () const; - //void SetMultiUser ( xbBool bMultiUser ); - if( x.GetMultiUser()) - std::cout << "Multi user (locking) is enabled." << std::endl; - else - std::cout << "Multi user (locking) not enabled." << std::endl; - - #if defined (XB_NDX_SUPPORT) || defined (XB_MDX_SUPPORT) - // xbInt16 GetUniqueKeyOpt () const; - // xbInt16 SetUniqueKeyOpt ( xbInt16 iUniqueKeyOpt ); - // XB_HALT_ON_DUPKEY - // XB_EMULATE_DBASE - if( x.GetUniqueKeyOpt() == XB_HALT_ON_DUPKEY ) - std::cout << "UniqueKey option - XB_HALT_ON_DUPKEY" << std::endl; - else if( x.GetUniqueKeyOpt() == XB_EMULATE_DBASE ) - std::cout << "UniqueKey option - XB_EMULATE_DBASE" << std::endl; - #endif // (XB_NDX_SUPPORT) || defined (XB_MDX_SUPPORT) - - #ifdef XB_LOCKING_SUPPORT - //xbInt16 GetDefaultLockRetries () const; - //void SetDefaultLockRetries ( xbInt16 iRetryCount ); - //xbInt32 GetDefaultLockWait () const; - //void SetDefaultLockWait ( xbInt32 lRetryWait ); - //xbInt16 GetDefaultLockFlavor () const; - //void SetDefaultLockFlavor ( xbInt16 iLockFlavor ); - //xbBool GetDefaultAutoLock () const; - //void SetDefaultAutoLock ( xbBool bAutoLock ); - //void EnableDefaultAutoLock (); - //void DisableDefaultAutoLock (); - - std::cout << "GetDefaultLockRetries() - " << x.GetDefaultLockRetries() << std::endl; - std::cout << "GetDefaultLockWait() - " << x.GetDefaultLockWait() << std::endl; - std::cout << "GetDefaultAutoLock() - " << x.GetDefaultAutoLock() << std::endl; - #endif // XB_LOCKING_SUPPORT - - #ifdef XB_MDX_SUPPORT - // xbInt16 GetCreateMdxBlockSize() const; - // xbInt16 SetCreateMdxBlockSize( xbInt16 ulBlockSize ); - std::cout << "GetCreateMdxBlockSize() - " << x.GetCreateMdxBlockSize() << std::endl; - #endif // XB_MDX_SUPPORT - - #ifdef XB_BLOCKREAD_SUPPORT - // xbUInt32 GetDefaultBlockReadSize() const; - // void SetDefaultBlockReadSize( xbUInt32 ulDfltBlockReadSize ); - std::cout << "GetDefaultBlockReadSize() - " << x.GetDefaultBlockReadSize() << std::endl; - #endif // XB_BLOCKREAD_SUPPORT - - //xbBool BitSet ( unsigned char c, xbInt16 iBitNo ) const; - //void BitDump ( unsigned char c ) const; - //void BitDump ( char c ) const; - std::cout << "BitDump( 'A' ) - "; - x.BitDump( 'A' ); - - return 0; -} - - -</xmp> - -<br><br> -<hr> -<p><img src="xbase.jpg"><br><hr> -</BODY> -</HTML> diff --git a/docs/html/xbc18.html b/docs/html/xbc18.html deleted file mode 100755 index 36f3b50..0000000 --- a/docs/html/xbc18.html +++ /dev/null @@ -1,252 +0,0 @@ -<!DOCTYPE HTML PUBLIC> -<HTML> -<TITLE>Xbase DBMS Chapter 18</TITLE> -<BODY BGCOLOR=#FFFFFF> -<H2><p align="center">Class xbXBase</p></H2> -<p align="center">Chapter Updated 2/7/23</p><hr> - -<h3>Class xbXBase - Core Level Class</h3> - - -The xbXBase class is the core class that needs to be in every application program. -Established an instance of class xbXBase before any other Xbase calls are made. - -<i>xbXBase x</i> - -<br><br> -xbXBase is derived from base classes xbTblMgr and xbSsv. -<br><br><br><br> - - - - - -<center> -<table border=1> -<tr><th width=40%>Method</th><th>Description</th><th>Category</th></tr> - -<tr><td>xbInt16 CloseAllTables()</td><td>Close all open tables.</td><td>Table</tr> - -<tr><td>xbInt16 OpenHighestVersion( const xbString &sTableName, const xbString &sAlias, xbDbf &dbf, int dummy )</td><td>Open highest version available for sTableName.</td><td>Table</tr> -<tr><td>xbInt16 OpenHighestVersion( const xbString &sTableName, const xbString &sAlias, xbDbf **dbf )</td><td>Open highest version available for sTableName.</td><td>Table</tr> -<tr><td>xbDbf * Open( const xbString &sTableName, xbInt16 &iRc )</td><td>Open the highest available version of the dbf file. Defaults to XB_READ_WRITE and XB_MULTI_USER mode.</td><td>Table</tr> -<tr><td>xbDbf * Open( const xbString &sTableName, const xbString &sAlias, xbInt16 iOpenMode, xbInt16 iShareMode, xbInt16 iVersion, xbInt16 &iRc )</td><td>Open table.</td><td>Table</tr> - -<tr><td colspan=3><hr></td></tr> -<tr><td>void DisableMsgLogging()</td><td>Disable logging routines.</td><td>Logging</td></tr> -<tr><td>void EnableMsgLogging ()</td><td>Enable logging routines.</td><td>Logging</td></tr> -<tr><td>xbInt16 FlushLog()</td><td>Flush any queued logfile updates to disk.</td><td>Logging</td></tr> -<tr><td>const xbString &GetLogDirectory () const</td><td>Get the current logfile directory.</td><td>Logging</td></tr> -<tr><td>const xbString &GetLogFileName () const</td><td>Get the current logfile name.</td><td>Logging</td></tr> -<tr><td>const xbString &GetLogFqFileName() const</td><td>Get fully qualified logfile name.</td><td>Logging</td></tr> -<tr><td>xbBool GetLogStatus () const</td><td>Get the logging status.</td><td>Logging</td></tr> -<tr><td>void SetLogDirectory( const xbString &sLogFileDirectory )</td><td>Set the log directory. Must be done while logging is off.</td><td>Logging</td></tr> -<tr><td>void SetLogFileName( const xbString &sLogFileName )</td><td>Set the log file name. Must be done while logging is off.</td><td>Logging</td></tr> -<tr><td>void SetLogSize( size_t lSize )</td><td>Set the logfile size. After the size is reached, the log file roll.</td><td>Logging</td></tr> -<tr><td>xbInt16 WriteLogBytes ( xbUInt32 lCnt, const char *p )</td><td>Write lCnt bytes pointed to by pointer p to the logfile.</td><td>Logging</td></tr> -<tr><td>xbInt16 WriteLogMessage( const xbString &sLogMessage, xbInt16 iOutputOpt = 0 )</td><td>Write a string to the logfile.</td><td>Logging</td></tr> - -<tr><td colspan=3><hr></td></tr> -<tr><td>xbInt16 xbXBase::GetCmdLineOpt( xbInt32 lArgc, char **sArgv, xbString &sOptRqst, xbString &sParmOut )<br> -xbXBase::GetCmdLineOpt( xbInt32 lArgc, char **sArgv, const char *sOptRqst, xbString &sParmOut )</td><td>Parse command line values seeking given parameter info.</td><td>Misc</td></tr> - -<tr><td>void xbSleep( xbInt32 lMillisecs )</td><td>Sleep command, used mainly in lock commands for waiting between retries.</td><td>Misc</td></td></tr> - -<tr><td colspan=3><hr></td></tr> -<tr><td>xbInt16 ABS( xbDouble dIn, xbDouble &dOut )</td><td>Dbase ABS function.</td><td>Expression</td></tr> -<tr><td>xbInt16 ALLTRIM( const xbString &sIn, xbString &sOut )</td><td>Dbase ALLTRIM function.</td><td>Expression</td></tr> -<tr><td>xbInt16 ASC( const xbString &s, xbDouble &dAscOut )</td><td>Dbase ASC function.</td><td>Expression</td></tr> -<tr><td>xbInt16 AT( const xbString &sSrchFor, const xbString &sBase, xbDouble &dPos )</td><td>Dbase AT function.</td><td>Expression</td></tr> -<tr><td>xbInt16 CDOW( xbDate &dInDate, xbString &sOutDow )</td><td>Dbase CDOW function.</td><td>Expression</td></tr> -<tr><td>xbInt16 CHR( xbDouble dAsciCd, xbString &sOut )</td><td>Dbase CHR function.</td><td>Expression</td></tr> -<tr><td>xbInt16 CMONTH( xbDate &dInDate, xbString &sOutMonth )</td><td>Dbase CMONTH function.</td><td>Expression</td></tr> -<tr><td>xbInt16 CTOD( const xbString &sInDate, xbDate &dOutDate )</td><td>Dbase CTOD function.</td><td>Expression</td></tr> -<tr><td>xbInt16 DATE( xbDate &dOutDate )</td><td>Dbase DATE function.</td><td>Expression</td></tr> -<tr><td>xbInt16 DAY( const xbDate &dInDate, xbDouble &dOutDay )</td><td>Dbase DAY function.</td><td>Expression</td></tr> -<tr><td>xbInt16 DEL( xbDbf * d, xbString &sOut, xbInt16 iRecBufSw = 0 )</td><td>Dbase DEL function.</td><td>Expression</td></tr> -<tr><td>xbInt16 DELETED( xbDbf * d, xbBool &bOut, xbInt16 iRecBufSw = 0 )</td><td>Dbase DELETED function.</td><td>Expression</td></tr> -<tr><td>xbInt16 DESCEND( const xbString &sIn,xbString &sOut )<br>xbInt16 DESCEND( const xbDate &dInDate, xbDate &dOutDate )<br>xbInt16 DESCEND( const xbDouble dIn, xbDouble &dsOut )</td><td>Dbase DESCEND function.</td><td>Expression</td></tr> -<tr><td>xbInt16 DOW( const xbDate &sInDate, xbDouble &dDowOut )</td><td>Dbase DOW function.</td><td>Expression</td></tr> -<tr><td>xbInt16 DTOC( xbDate &dInDate, xbString &sOutFmtDate )</td><td>Dbase DTOC function.</td><td>Expression</td></tr> -<tr><td>xbInt16 DTOS( xbDate &dInDate, xbString &sOutFmtDate )</td><td>Dbase DTOS function.</td><td>Expression</td></tr> -<tr><td>xbInt16 EXP( xbDouble dIn, xbDouble &dOut )</td><td>Dbase EXP function.</td><td>Expression</td></tr> -<tr><td>xbInt16 IIF( xbBool bResult, const xbString &sTrueResult, const xbString &sFalseResult, xbString &sResult )</td><td>Dbase IIF function.</td><td>Expression</td></tr> -<tr><td>xbInt16 INT( xbDouble dIn, xbDouble &dOut )</td><td>Dbase INT function.</td><td>Expression</td></tr> -<tr><td>xbInt16 ISALPHA( const xbString &s, xbBool &bResult )</td><td>Dbase ISALPHA function.</td><td>Expression</td></tr> -<tr><td>xbInt16 ISLOWER( const xbString &s, xbBool &bResult )</td><td>Dbase ISLOWER function.</td><td>Expression</td></tr> -<tr><td>xbInt16 ISUPPER( const xbString &s, xbBool &bResult )</td><td>Dbase ISUPPER function.</td><td>Expression</td></tr> -<tr><td>xbInt16 LEFT( const xbString &sIn, xbUInt32 lCharCnt, xbString &sOut )</td><td>Dbase LEF function.</td><td>Expression</td></tr> -<tr><td>xbInt16 LEN( const xbString &sIn, xbDouble &dLen )</td><td>Dbase LEN function.</td><td>Expression</td></tr> -<tr><td>xbInt16 LOG( xbDouble dIn, xbDouble &dOut )</td><td>Dbase LOG function.</td><td>Expression</td></tr> -<tr><td>xbInt16 LOWER( const xbString &sIn, xbString &sOut )</td><td>Dbase LOWER function.</td><td>Expression</td></tr> -<tr><td>xbInt16 LTRIM( const xbString &sIn, xbString & sOut )</td><td>Dbase LTRIM function.</td><td>Expression</td></tr> -<tr><td>xbInt16 MAX( xbDouble dIn1, xbDouble dIn2, xbDouble &dOut )</td><td>Dbase MAX function.</td><td>Expression</td></tr> -<tr><td>xbInt16 MIN( xbDouble dIn1, xbDouble dIn2, xbDouble &dOut )</td><td>Dbase MIN function.</td><td>Expression</td></tr> -<tr><td>xbInt16 MONTH( xbDate &dInDate, xbDouble &dMonthOut )</td><td>Dbase MONTH function.</td><td>Expression</td></tr> -<tr><td>xbInt16 RECCOUNT( xbDbf * d, xbDouble &dRecOut )</td><td>Dbase RECCOUNT function.</td><td>Expression</td></tr> -<tr><td>xbInt16 RECNO( xbDbf * d, xbDouble &dRecOut )</td><td>Dbase RECNO function.</td><td>Expression</td></tr> -<tr><td>xbInt16 REPLICATE( const xbString &sIn, xbUInt32 ulRepCnt, xbString &sOut )</td><td>Dbase REPLICATE function.</td><td>Expression</td></tr> -<tr><td>xbInt16 RIGHT( const xbString &sIn, xbUInt32 iCharCnt, xbString &sOut )</td><td>Dbase RIGHT function.</td><td>Expression</td></tr> -<tr><td>xbInt16 RTRIM( const xbString &sIn, xbString &sOut )</td><td>Dbase RTRIM function.</td><td>Expression</td></tr> -<tr><td>xbInt16 SPACE( xbInt32 lCnt, xbString &sOut )</td><td>Dbase SPACE function.</td><td>Expression</td></tr> -<tr><td>xbInt16 SQRT( xbDouble dBase, xbDouble &dSqrRt )</td><td>Dbase SQRT function.</td><td>Expression</td></tr> -<tr><td>xbInt16 STOD( const xbString &sIn, xbDate &sDateOut )</td><td>Dbase STOD function.</td><td>Expression</td></tr> -<tr><td>xbInt16 STR( xbDouble dIn, xbString &sOut )</td><td>Dbase function.</td><td>Expression</td></tr> -<tr><td>xbInt16 STR( xbDouble dIn, xbUInt32 ulLen, xbString &sOut )<br> - xbInt16 STR( xbDouble dIn, xbUInt32 ulLen, xbUInt32 ulDec, xbString &sOut )<br> - xbInt16 STR( xbDouble dIn, xbUInt32 ulLen, xbUInt32 ulDec, xbString &sPadChar, xbString &sOut )</td><td>Dbase STR function.</td><td>Expression</td></tr> -<tr><td>xbInt16 STRZERO( xbDouble dIn, xbUInt32 ulLen, xbUInt32 ulDec, xbString &sOut )</td><td>Dbase STRZERO function.</td><td>Expression</td></tr> -<tr><td>xbInt16 SUBSTR( const xbString &sIn, xbUInt32 ulStartPos, xbUInt32 ulLen, xbString &sOut )</td><td>Dbase SUBSTR function.</td><td>Expression</td></tr> -<tr><td>xbInt16 TRIM( const xbString &sIn, xbString &sOut )</td><td>Dbase TRIM function.</td><td>Expression</td></tr> -<tr><td>xbInt16 UPPER( const xbString &sIn, xbString &sOut )</td><td>Dbase UPPER function.</td><td>Expression</td></tr> -<tr><td>xbInt16 VAL( const xbString &sIn, xbDouble &dOut )</td><td>Dbase VAL function.</td><td>Expression</td></tr> -<tr><td>xbInt16 YEAR( xbDate &dInDate, xbDouble &dOutYear )</td><td>Dbase YEAR function.</td><td>Expression</td></tr> -</table> - -<br><br> -<hr> - -<h3>Example program using xbXbase methods</h3> -</center> -<xmp> -/* xb_ex_ssv.cpp -XBase64 Software Library - -Copyright (c) 1997,2003,2014,2021,2022,2023 Gary A Kunkel - -The xb64 software library is covered under the terms of the GPL Version 3, 2007 license. - -Email Contact: - - XDB-devel@lists.sourceforge.net - XDB-users@lists.sourceforge.net - -This program demonstrates using functionality of the xbSsv class (Shared system values) - -*/ - -#include "xbase.h" - -using namespace xb; - -int main( int ac, char ** av ){ - - xbXBase x; // set up xbase for business - xbString sMsg; // a message string - - sMsg.Sprintf( "Program [%s] initializing...", av[0] ); - std::cout << sMsg.Str() << std::endl; - - // example code to set up log file usage - #ifdef XB_LOGGING_SUPPORT - char cSeperator; // is this a unix (/) or windows (\) file system - xbString sLog; // general string for log file activities - sLog = x.GetLogFqFileName().Str(); // get the system default log file name - std::cout << "System default logfile is [" << sLog.Str() << "]" << std::endl; - - cSeperator = sLog.GetPathSeparator(); // get the seperator from - std::cout << "Path seperator = [" << cSeperator << "]" << std::endl; - - sLog.Sprintf( "..%c", cSeperator ); - x.SetLogDirectory( sLog ); - std::cout << "sLog = [" << sLog.Str() << "]\n"; - - sLog = x.GetLogFqFileName().Str(); // get the system default log file name - std::cout << "New logfile is [" << sLog.Str() << "]" << std::endl; - - // turn on logging after file name set - x.EnableMsgLogging(); - #endif // XB_LOGGING_SUPPORT - - // const char *GetErrorMessage( xbInt16 ErrorCode ) const; - // void DisplayError( xbInt16 ErrorCode ) const; - std::cout << "DisplayError( -100 ) - "; - x.DisplayError( -100 ); - // << "]" << std::endl; - - - // void SetDefaultDateFormat( const xbString &sDefaultDateFormat ); - // xbString& GetDefaultDateFormat() const; - std::cout << "GetDefaultDateFormat() - " << x.GetDefaultDateFormat() << std::endl; - - // void SetDataDirectory ( const xbString &sDataDirectory ); - // xbString& GetDataDirectory() const; - std::cout << "GetDataDirectory() - " << x.GetDataDirectory() << std::endl; - - // xbInt16 GetEndianType() const; - if( x.GetEndianType() == 'L' ) - std::cout << "Little Endian Architecture." << std::endl; - else - std::cout << "Bid Endian Architecture." << std::endl; - - //xbBool GetDefaultAutoCommit() const; - //void SetDefaultAutoCommit( xbBool bDefaultAutoCommit ); - if( x.GetDefaultAutoCommit()) - std::cout << "AutoCommit is on." << std::endl; - else - std::cout << "AutoCommit is off." << std::endl; - - //xbBool GetMultiUser () const; - //void SetMultiUser ( xbBool bMultiUser ); - if( x.GetMultiUser()) - std::cout << "Multi user (locking) is enabled." << std::endl; - else - std::cout << "Multi user (locking) not enabled." << std::endl; - - #if defined (XB_NDX_SUPPORT) || defined (XB_MDX_SUPPORT) - // xbInt16 GetUniqueKeyOpt () const; - // xbInt16 SetUniqueKeyOpt ( xbInt16 iUniqueKeyOpt ); - // XB_HALT_ON_DUPKEY - // XB_EMULATE_DBASE - if( x.GetUniqueKeyOpt() == XB_HALT_ON_DUPKEY ) - std::cout << "UniqueKey option - XB_HALT_ON_DUPKEY" << std::endl; - else if( x.GetUniqueKeyOpt() == XB_EMULATE_DBASE ) - std::cout << "UniqueKey option - XB_EMULATE_DBASE" << std::endl; - #endif // (XB_NDX_SUPPORT) || defined (XB_MDX_SUPPORT) - - #ifdef XB_LOCKING_SUPPORT - //xbInt16 GetDefaultLockRetries () const; - //void SetDefaultLockRetries ( xbInt16 iRetryCount ); - //xbInt32 GetDefaultLockWait () const; - //void SetDefaultLockWait ( xbInt32 lRetryWait ); - //xbInt16 GetDefaultLockFlavor () const; - //void SetDefaultLockFlavor ( xbInt16 iLockFlavor ); - //xbBool GetDefaultAutoLock () const; - //void SetDefaultAutoLock ( xbBool bAutoLock ); - //void EnableDefaultAutoLock (); - //void DisableDefaultAutoLock (); - - std::cout << "GetDefaultLockRetries() - " << x.GetDefaultLockRetries() << std::endl; - std::cout << "GetDefaultLockWait() - " << x.GetDefaultLockWait() << std::endl; - std::cout << "GetDefaultAutoLock() - " << x.GetDefaultAutoLock() << std::endl; - #endif // XB_LOCKING_SUPPORT - - #ifdef XB_MDX_SUPPORT - // xbInt16 GetCreateMdxBlockSize() const; - // xbInt16 SetCreateMdxBlockSize( xbInt16 ulBlockSize ); - std::cout << "GetCreateMdxBlockSize() - " << x.GetCreateMdxBlockSize() << std::endl; - #endif // XB_MDX_SUPPORT - - #ifdef XB_BLOCKREAD_SUPPORT - // xbUInt32 GetDefaultBlockReadSize() const; - // void SetDefaultBlockReadSize( xbUInt32 ulDfltBlockReadSize ); - std::cout << "GetDefaultBlockReadSize() - " << x.GetDefaultBlockReadSize() << std::endl; - #endif // XB_BLOCKREAD_SUPPORT - - //xbBool BitSet ( unsigned char c, xbInt16 iBitNo ) const; - //void BitDump ( unsigned char c ) const; - //void BitDump ( char c ) const; - std::cout << "BitDump( 'A' ) - "; - x.BitDump( 'A' ); - - return 0; -} - - -</xmp> - -<br><br> -<hr> -<p><img src="xbase.jpg"><br><hr> -</BODY> -</HTML> diff --git a/docs/html/xbc2.html b/docs/html/xbc2.html index 72a6009..71d4585 100755 --- a/docs/html/xbc2.html +++ b/docs/html/xbc2.html @@ -2,24 +2,38 @@ <HTML> <TITLE>Xbase DBMS Chapter 2</TITLE> <BODY BGCOLOR=#FFFFFF> -<H2><p align="center">Database Overview</p></H2> -<p align="center">Chapter Updated 11/21/22</p><hr> - -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.<br><br> - -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. +<H2><p align="center">System Overview</p></H2> +<p align="center">Chapter Updated 04/28/23</p><hr> + +<br><br> +The <em>XBase64</em> library is a cross platform object oriented C++ set of classes for +accessing and manipulating the following Xbase file types:<br><br> + + +<table border=1> +<tr><th>Extension</th><th>Description</th><th>Supported by Xbase64 library?</th></tr> +<tr><td>*.DBF</td><td>Main DBF file or table name</td><td><center>Y</center></td></tr> +<tr><td>*.DBT</td><td>Verson 3 or Version 4 memo file</td><td><center>Y</center></td></tr> +<tr><td>*.NDX</td><td>Single tag index file</td><td><center>Y</center></td></tr> +<tr><td>*.MDX</td><td>Multi tag index file</td><td><center>Y</center></td></tr> +<tr><td>*.INF</td><td>ODBC file used for auto open of NDX files</td><td><center>Y</center></td></tr> +<tr><td>*.NTX</td><td>Clipper indexfile </td><td><center>Future</center></td></tr> +<tr><td>*.CDX</td><td>Fox Pro indexfile </td><td><center>Future</center></td></tr> +<tr><td>*.IDX</td><td>Fox Pro index file</td><td><center>Future</center></td></tr> +</table> + + + + +<br><br> + +DBF files are comprised of a variable length header record which stores +information about the file and describes he fixed length record format, +followed by a series of fixed length data records. <br><br> Each fixed length data record is preceded by a one byte indicator -which identifiies if the record has been deleted. If the record is +which identifies 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.<br><br> @@ -70,7 +84,6 @@ method will back out any updates to the record buffer. <br><br> - <hr> <br> <h3>Xbase Database File Header - DBF Version III and Version IV</h3> @@ -156,16 +169,8 @@ 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.<br><br> -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. - -<h4>Technical memo file information</h4> +<h3>Technical memo file information</h3> The following info on memo fields is for the curious. It is not required @@ -261,6 +266,102 @@ is added to the free block chain. Version 3 and 4 memo fields are terminated with two contiguous 0x1A bytes of data. <br><br> <hr> + + +<h3>Block Reads</h3> + +As of release 4.1.1, the Xbase library includes functionality for reading a DBF file in blocks, rather than one record at a time.<br><br> + +This functionality can be used to improve application performance in situations where a data file is being read sequentially. +For situations where records are retrieved randomly from the file, enabling this probably won't help much. In short, this +can be turned on when accessing a file sequentially and should be left off when not processing sequentially.<br><br> + +The logic is handled internally within the library, all that is needed is to +enable it and the library handles the rest. Additionally, the block read functionality +was designed with for sequential file access and is designed with reporting in mind. +It doesn't currently have any auto locking associated with it. +<br><br> + +To enable and disable Block Reading for a DBF file, use +<em>xbDbf::EnableBlockReadProcessing()</em> +and <em>xbDbf::DisableBlockReadProcessing()</em>. +<br><br> + +<hr> +<h3>Locking Overview</h3> + +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.<br><br> + +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(). +<br><br> +Locking can also be enabled / disabled at the table level with with xbDbf::SetAutoLock().<br><br> +If autolocking is disabled and the code base is being used in a multi user environment, it is +up to the application program to verify the needed locks are set as there is no checking or +setting any locks if autolocking is turned off. It is only safe to turn off the autolocking functionality +if the library is being used in a single user environment. + +<br><br> +The current Xbase64 record locking logic is modeled after DBase (tm) V7 locking. +<br><br> + +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 +<em>errno</em> or function <em>perror()</em> can be executed to view the +results. +<br><br> + +The errno field may contain one of the following values if the lock was not +successful.<br><br> +<TABLE BORDER> +<TR VALIGN="BASELINE"> +<TR><TH ALIGN="LEFT">Error Code<TD>Description +<TR><TH ALIGN="LEFT">EBADF<TD>Invalid file descriptor +<TR><TH ALIGN="LEFT">EINVAL<TD>Invalid lock information or file does not support locks +<TR><TH ALIGN="LEFT">EACCESS<BR>EAGAIN<TD>Lock can not be set because it is blocked by an existing lock on the file. +<TR><TH ALIGN="LEFT">ENOLCK<TD>The system is out of lock resources, too many file locks in place. +<TR><TH ALIGN="LEFT">EDEADLK<TD>Deadlock condition +<TR><TH ALIGN="LEFT">EINTR<TD>Process was interrupted by a signal while it was waiting +</TABLE> +<br><br> + +<h3>Linux/Windows File Locking Compatibility Issue</h3> + +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. + +<br><br> +In Unix, a program can not lock a file so another process can not access it.<br> +In Windows, a program can lock a file so another process can not access it.<br> +DBase(tm) supports routines to open files exclusively, preventing other users from opening a file.<br> +Locking on the Mac/Apple platform only works on NFS shares. It does not work with SMB shares. + +<br><h3>Samba settings</h3> + +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:<br> +<br> +[sharename]<br> +oplocks = False<br> +level2 oplocks = False + + +<br><h3>iLockFlavor</h3> + +The library was constructed in a manner so that it could be updated to support alternate lock "flavors". +The 4.x.x library is built to mirror the DBase locking, but the structure is in place to expand to other locking +types if needed. + + +<br><br> +<hr> <p><img src="xbase.jpg"><hr> </BODY> </HTML> diff --git a/docs/html/xbc3.html b/docs/html/xbc3.html index f2f4a1d..866850f 100755 --- a/docs/html/xbc3.html +++ b/docs/html/xbc3.html @@ -2,8 +2,8 @@ <HTML> <TITLE>Xbase DBMS Chapter 3</TITLE> <BODY BGCOLOR=#FFFFFF> -<H1><p align="center">Fields and Strings</p></H1> -<p align="center">Chapter Updated 11/21/22</p><hr> +<H1><p align="center">Fields, Strings and Dates</p></H1> +<p align="center">Chapter Updated 04/28/23</p><hr> <br><br> The main objective of this chapter is to provide basic information regarding @@ -13,7 +13,6 @@ 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.<br><br> - <TABLE BORDER> <CAPTION ALIGN="TOP"><h3>Field Types</H3></CAPTION> <TR VALIGN="BASELINE"> @@ -33,7 +32,7 @@ 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.<br><br> -<h2>Memo Fields</h2> +<h3>Memo Fields</h3> Memo fields are variable length data fields which are stored in two parts. This first part is a ten byte field which is stored @@ -52,14 +51,14 @@ using. To utilize memo fields, the application program must allocate a buffer which is large enough to handle the memo data.<br><br> -<h2>Fields and Field Numbers</h2> +<h3>Fields and Field Numbers</h3> 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.<br><br> -<h2>Strings</h2> +<h3>Strings</h3> Xbase64 includes support for a string class <em>xbString</em>. The xbString class interface was originally derived from the @@ -67,6 +66,37 @@ The xbString class interface was originally derived from the If you are familiar with other string classes, this one should be similar. Strings can be used to manage strings of character data. <br><br> + +<h3>Date Fields</h3> + +All dates are stored in the .DBF files as Gregorian dates with format CCYYMMDD.<br><br> +The library date routines work with dates formated with the same CCYYMMDD format.<br><br> + +<h3>Null Dates</h3> +Date fields in the database stored as eight spaces are considered null dates.<br><br> + +<h3>Leap Years</h3> + +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. + +<h3>Julian Dates</h3> + +The Julian date routines calculate a Julian date as the number of days +since 01/01/0001 with an offset of 1721425L. +<br><br> + +Julian dates are useful for doing date arithmetic such as determining the +difference between two dates or calculating a future or past date.<br><br> + +To determine the difference between two dates, convert both dates to a +Julian date and subtract one from the other.<br><br> + +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.<br><br> + <hr> <p><img src="xbase.jpg"><hr> </BODY> diff --git a/docs/html/xbc4.html b/docs/html/xbc4.html index a0275ed..f8a48d9 100755 --- a/docs/html/xbc4.html +++ b/docs/html/xbc4.html @@ -1,79 +1,206 @@ <!DOCTYPE HTML PUBLIC> -<HTML> -<TITLE>Xbase DBMS Chapter 4</TITLE> -<BODY BGCOLOR=#FFFFFF> -<H1><p align="center">Date Processing</p></H1> -<p align="center">Chapter Updated 12/09/22</p><hr> - -The objective of this chapter is to provide information regarding -the basic concepts of date arithmetic and supply generic -C/C++ date methods.<br><br> - -<h2>Leap Years</h2> - -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 - -<xmp> - int year; - - if(( year % 4 == 0 && year % 100 != 0 ) || year % 400 = 0 ) - LEAP_YEAR = TRUE; - else - LEAP_YEAR = FALSE -</xmp> - - -<h2>Julian Dates</h2> - -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.<br><br> - -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.<br><br> - -To determine the difference between two dates, convert both dates to a -Julian date and subtract one from the other.<br><br> - -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.<br><br> - -The Julian date routines use a base date of 01/01/0001. DBase julian Dates have an offset of 1721425L, reason unknown. +<html> +<title>Xbase DBMS Chapter 4</title> +<body bgcolor=#FFFFFF> +<h1><p align="center">Expression Handling<br></h1> +<p align="center">Chapter Updated 04/28/23</p><hr> + +<h3>Overview</h3> + +The main objective of this chapter is to provide information regarding the +basic concepts of using the Xbase64 Expression module.<br><br> + +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. +<br><br> +Expressions are primarily used for index key definitions and filter criteria, but +can also be used for other tasks as well. +<br><br> + +<h3>Internal fuctioning</h3> +The expression module works in two phases. Firstly, method +<em>ParseExpression</em> 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. <br><br> +Secondly, method <em>ProcessExpression</em> 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.<br><br> -<h2>Gregorian Dates</h2> +If an expression will be processed repeatedly, it is best to pre-parse the +tree using <em>ParseExpression</em>, then for each new call to the expression, +execute method <em>ProcessExpression</em> which processes the tree. + +<h3>Expression Return Types</h3> +Expressions will return a type of CHAR, NUMERIC, DATE or LOGICAL.<br><br> + +An expression return type can be determined with method <em> +GetExpressionResultType</em> after parsing it.<br><br> + +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 +<em>enum { WorkBufMaxLen = 200 };</em> in file <em>exp.h</em>. -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. <br><br> +<table border=1> +<tr><th>Return Type</th><th>XBase Type</th></tr> +<tr><td>CHAR</td><td>xbString</td></tr> +<tr><td>NUMERIC</td><td>xbDouble</td></tr> +<tr><td>DATE</td><td>xbDate</td></tr> +<tr><td>LOGICAL</td><td>xbBool</td></tr> +</table> -The methods supplied with this software are based on gregorian dates with -the format of CCYYMMDD for century, year, month and day.<br><br> +<br><br> +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. +<br><br> +<h3>Expression Functions</h3> +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.<br><br> + +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.<br><br> + + +<table border=1> +<tr><th>Function Name</th><th>Return Type</th><th>Description</th></tr> +<tr><td>ABS</td><td>N</td><td>Calculate absolute value of numeric expression</td></tr> +<tr><td>ALLTRIM</td><td>C</td><td>Trim leading andtrailing whitespace from a string</td></tr> +<tr><td>ASC</td><td>N</td><td>Return ASCII code for first character in a string</td></tr> +<tr><td>AT</td><td>N</td><td>Return starting position of a string within a string</td></tr> +<tr><td>CDOW</td><td>C</td><td>Retun character weekday name for a date</td></tr> +<tr><td>CHR</td><td>C</td><td>Convert numeric expression to a character</td></tr> +<tr><td>CMONTH</td><td>C</td><td>Return month name for a date</td></tr> +<tr><td>CTOD</td><td>D</td><td>Return date from a character date input</td></tr> +<tr><td>DATE</td><td>D</td><td>Return system date</td></tr> +<tr><td>DAY</td><td>N</td><td>Return the day of the month from a date</td></tr> +<tr><td>DEL</td><td>C</td><td>Return record deletion status for a record</td></tr> +<tr><td>DELETED</td><td>L</td><td>Return record deletion status for a record<</td></tr> +<tr><td>DESCEND</td><td>1</td><td>Clipper DESCEND function</td></tr> +<tr><td>DOW</td><td>N</td><td>Return number of day of week</td></tr> +<tr><td>DTOC</td><td>C</td><td>Return character date from input date</td></tr> +<tr><td>DTOS</td><td>C</td><td>Return character CCYYMMDD date from input date</td></tr> +<tr><td>EXP</td><td>N</td><td>Return exponent value</td></tr> +<tr><td>IIF</td><td>C</td><td>Immediate If</td></tr> +<tr><td>INT</td><td>N</td><td>Convert number to integer, truncate any decimals</td></tr> +<tr><td>ISALPHA</td><td>L</td><td>Check if string begins with alpha character</td></tr> +<tr><td>ISLOWER</td><td>L</td><td>Check if string begins with lower case alpha character</td></tr> +<tr><td>ISUPPER</td><td>L</td><td>Check if string begins with upper case character</td></tr> +<tr><td>LEFT</td><td>C</td><td>Return left characters from a string</td></tr> +<tr><td>LEN</td><td>N</td><td>Return lenght of string</td></tr> +<tr><td>LOG</td><td>N</td><td>Calculate logarithm</td></tr> +<tr><td>LOWER</td><td>C</td><td>Convert upper case to lower case</td></tr> +<tr><td>LTRIM</td><td>C</td><td>Trim left side of a string</td></tr> +<tr><td>MAX</td><td>N</td><td>Return higher of two values</td></tr> +<tr><td>MIN</td><td>N</td><td>Return lesser of two values</td></tr> +<tr><td>MONTH</td><td>N</td><td>Return number of month for a given date</td></tr> +<tr><td>RECNO</td><td>N</td><td>Return current rec number for a given table</td></tr> +<tr><td>RECCOUNT</td><td>N</td><td>Return number of records in a given table</td></tr> +<tr><td>REPLICATE</td><td>C</td><td>Repeat character expression N times</td></tr> +<tr><td>RIGHT</td><td>C</td><td>Return right characters from as tring</td></tr> +<tr><td>RTRIM</td><td>C</td><td>Trim right side of string</td></tr> +<tr><td>SPACE</td><td>C</td><td>Generate a string of N spaces</td></tr> +<tr><td>SQRT</td><td>N</td><td>Calculate square root</td></tr> +<tr><td>STOD</td><td>D</td><td>Convert 8 byte CCYYMMDD date to date</td></tr> +<tr><td>STR</td><td>C</td><td>Convert number to character string</td></tr> +<tr><td>STRZERO</td><td>C</td><td>Convert number to character string with leading zeroes. Clipper Function.</td></tr> +<tr><td>SUBSTR</td><td>C</td><td>Extract portion oif one string from another string</td></tr> +<tr><td>TRIM</td><td>C</td><td>Trim left and right sides of a string</td></tr> +<tr><td>UPPER</td><td>C</td><td>Conver lower case to upper case</td></tr> +<tr><td>VAL</td><td>N</td><td>Convert numeric characters to number</td></tr> +<tr><td>YEAR</td><td>N</td><td>Return year for a given date</td></tr> +</table> + +<br><br> +<h3>Expression Components</h3> +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 "-'". +<br><br> +A field is simply a field name in the default database, or is in the form +of database->fieldname. + + +<br><br> +<h3>Expression Literals</h3> + +<table border=1> +<tr><th>Type</th><th>Example</th></tr> +<tr><td>CHAR</td><td>"literal" or 'literal'</td></tr> +<tr><td>NUMERIC</td><td>+99999.99</td></tr> +<tr><td>DATE</td><td>{10/07/60} or {02/09/1989}</td></tr> +</table> + +<br><br> +<h3>Expression Operators</h3> +<table border=1> +<tr><th>Type</th><th>Operator</th><th>Precedence</th><th>Result</th><th>Notes</th></tr> +<tr><td>Parens</td><td>()</td><td>12</td></tr> +<tr><td>Numeric Operator</td><td>+ (unary)</td><td>11</td><td>N</td></tr> +<tr><td>Numeric Operator</td><td>- (unary)</td><td>11</td><td>N</td></tr> +<tr><td>Numeric Operator</td><td>--X</td><td>10</td><td>N</td></tr> +<tr><td>Numeric Operator</td><td>++X</td><td>10</td><td>N</td></tr> +<tr><td>Numeric Operator</td><td>**</td><td>9</td><td>N</td></tr> +<tr><td>Numeric Operator</td><td>^</td><td>9</td><td>N</td></tr> +<tr><td>Numeric Operator</td><td>%</td><td>8</td><td>N</td></tr> +<tr><td>Numeric Operator</td><td>*</td><td>8</td><td>N</td></tr> +<tr><td>Numeric Operator</td><td>/</td><td>8</td><td>N</td></tr> +<tr><td>Numeric Operator</td><td>+ Addition</td><td>7</td><td>N</td></tr> +<tr><td>Numeric Operator</td><td>- Subtraction</td><td>7</td><td>N</td></tr> +<tr><td>Numeric Operator</td><td>X--</td><td>6</td><td>N</td></tr> +<tr><td>Numeric Operator</td><td>X++</td><td>6</td><td>N</td></tr> +<tr></tr> +<tr><td>String Operator</td><td>+</td><td>5</td><td>C</td><td>Concatonate 1</td></tr> +<tr><td>String Operator</td><td>-</td><td>5</td><td>C</td><td>Concatonate 2</td></tr> +<tr></tr> +<tr><td>Relational Operator</td><td>=</td><td>4</td><td>L</td><td>N,C,D</td></tr> +<tr><td>Relational Operator</td><td>#, <>, !=</td><td>4</td><td?L</td><td>N,C,D</td></tr> +<tr><td>Relational Operator</td><td><</td><td>4</td><td>L</td><td>N,C,D</td></tr> +<tr><td>Relational Operator</td><td>></td><td>4</td><td>L</td><td>N,C,D</td></tr> +<tr><td>Relational Operator</td><td><=</td><td>4</td><td>L</td><td>N,C,D</td></tr> +<tr><td>Relational Operator</td><td>>=</td><td>4</td><td>L</td><td>N,C,D</td></tr> +<tr><td>Relational Operator</td><td>$</td><td>4</td><td>L</td><td>N,C,D</td></tr> +<tr><td>Relational Operator</td><td>==</td><td></td><td></td><td>Clipper operator, not implemented yet</td></tr> +<tr></tr> +<tr><td>Logical Operator</td><td>NOT</td><td>3</td><td>L</td><td>Evaluated after all math and relational operators</td></tr> +<tr><td>Logical Operator</td><td>.NOT.</td><td>3</td><td>L</td><td>Evaluated after all math and relational operators</td></tr> +<tr><td>Logical Operator</td><td>AND</td><td>2</td><td>L</td><td>Evaluated after all math and relational operators</td></tr> +<tr><td>Logical Operator</td><td>.AND.</td><td>2</td><td>L</td><td>Evaluated after all math and relational operators</td></tr> +<tr><td>Logical Operator</td><td>OR</td><td>1</td><td>L</td><td>Evaluated after all math and relational operators</td></tr> +<tr><td>Logical Operator</td><td>.OR.</td><td>1</td><td>L</td><td>Evaluated after all math and relational operators</td></tr> +</table> + +<br><br> +<h3>Example Expressions</h3> +<li>CUSTOMERS->LNAME + ", " + CUSTOMERS->FNAME +<li>LNAME + ", " + FNAME +<li>STARTDT + 90 +<li>DATE() - 7 +<li>YEAR( TODAY() ) +<li>IIF( "A" = "N", "true result", "false result" ) +<li>IIF( "A" = "N" .OR. 2 > 1 , "true result", "false result" ) +<li>IIF( .NOT. "A" = "N", "true result", "false result" ) +<li>.NOT. DELETED() +<br><br> -<h2>Date Formats</h2> -All dates are stored in the .DBF files with format CCYYMMDD.<br><br> -All date routines work with dates formated with the same CCYYMMDD format.<br><br> +<h3>Example program</h3> +For an example on how to use the expression logic, see program +<em>src/examples/xb_ex_expression.cpp</em>. +<br><br> <hr> <p><img src="xbase.jpg"><br><hr> diff --git a/docs/html/xbc5.html b/docs/html/xbc5.html index 9708b17..66b0f62 100755 --- a/docs/html/xbc5.html +++ b/docs/html/xbc5.html @@ -1,205 +1,434 @@ <!DOCTYPE HTML PUBLIC> <html> <title>Xbase DBMS Chapter 5</title> -<body bgcolor=#FFFFFF> -<h1><p align="center">Expression Handling<br></h1> -<p align="center">Chapter Updated 12/26/22</p><hr> +<body BGCOLOR=#FFFFFF> +<H1><p align="center">Index Overview</p></H1> +<p align="center">Chapter Updated 04/29/23</p><hr> -<h3>Overview</h3> +The objective of this chapter is to provide information regarding +the basic concepts of index processing for the Xbase library.<br><br> -The main objective of this chapter is to provide information regarding the -basic concepts of using the Xbase64 Expression module.<br><br> -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. +<h3>Overview</h3> -The functions included were derived from dBASE III Plus, dBASE IV and Clipper. -<br><br> -Expressions are primarily used for index key definitions and filter criteria, but -can also be used for other tasks as well. -<br><br> +The Xbase64 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. -<h3>Internal fuctioning</h3> -The expression module works in two phases. Firstly, method -<em>ParseExpression</em> 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. <br><br> -Secondly, method <em>ProcessExpression</em> 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.<br><br> +The 4.0.x rewrite includes the NDX and MDX formats. Earlier versions of the +library included an NTX format which will be brought forward into the +library rewrite at some point in the future. + + +<h3>Tags</h3> + +Each index file contains one or more tags depending on the file type. Each tag is a sort order +and has characteristics: Sort order (ASC or DESC), unique or not unique and some formats support filtering. +Each open table (dbf file) has an "active tag" for database operations. + +<h3>Index processing design</h3> -If an expression will be processed repeatedly, it is best to pre-parse the -tree using <em>ParseExpression</em>, then for each new call to the expression, -execute method <em>ProcessExpression</em> which processes the tree. +The library is construcuted to handle index files with multiple tags per file. Single tag files like the NDX indices +are treated as a multi tag file, but there is only one tag. This allows for maximum flexibility for future +additional index types. -<h3>Expression Return Types</h3> -Expressions will return a type of CHAR, NUMERIC, DATE or LOGICAL.<br><br> -An expression return type can be determined with method <em> -GetExpressionResultType</em> after parsing it.<br><br> -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 -<em>enum { WorkBufMaxLen = 200 };</em> in file <em>exp.h</em>. +<h3>Index updates</h3> + +The library automatically updates all tags in all open index files. + <br><br> +<h3>Index File Types</h3> + <table border=1> -<tr><th>Return Type</th><th>XBase Type</th></tr> -<tr><td>CHAR</td><td>xbString</td></tr> -<tr><td>NUMERIC</td><td>xbDouble</td></tr> -<tr><td>DATE</td><td>xbDate</td></tr> -<tr><td>LOGICAL</td><td>xbBool</td></tr> +<tr><th>File<br>Type</th><th>Source</th><th>Max Tags<br>Per File</th><th>Auto Opened</th><th>Sort Order</th><th>Unique Keys</th> + <th>Reclaimed Nodes</th><th>Filter Support</th><th>Status</th></tr> +<tr> + <td>NDX</td><td>dBase</td> + <td><center>1</center></td> + <td><center>Optional</center></td> + <td>ASC only</td> + <td><center>Y</center></td> + <td><center>N</center></td> + <td><center>N</center></td> + <td><center>Available in 4.0.1</center></td> +</tr> +<tr> + <td>MDX</td><td>dBase</td> + <td><center>47</center></td> + <td><center>Yes</center></td> + <td><center>ASC or DESC</center></td> + <td><center>Y</center></td> + <td><center>Y</center></td> + <td><center>Y</center></td> + <td><center>Available in 4.0.1</center></td> +</tr> +<tr> + <td>NTX</td> + <td>Clipper</td> + <td><center>1</center></td> + <td><center>Optional</center></td> + <td><center></center></td> + <td><center></center></td> + <td><center></center></td> + <td><center></center></td> + <td><center>Pending retrofit</center></td> +</tr> +<tr> + <td>CDX</td> + <td>Fox Pro</td> + <td><center></center></td> + <td><center></center></td> + <td><center></center></td> + <td><center></center></td> + <td><center></center></td> + <td><center></center></td> + <td><center>Pending development</center></td> +<tr> +<tr> + <td>IDX</td><td>Fox Pro</td> + <td></td> + <td></td> + <td></td> + <td></td> + <td></td> + <td></td> + <td>Pending development</td> +<tr> + </table> <br><br> -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. +<h3>Index/Tag Methods</h3> + +<table border=1> +<tr><th width=45%>Method</th><th>Description</th></tr> +<tr> + <td>xbInt16 xbDbf::CheckTagIntegrity( xbInt16 iTagOpt, xbInt16 iOutputOpt ) + </td><td>Checks a tag for missing or duplicate entries. Available if XB_DEBUG_SUPPORT is on.</td> +</tr> +<tr> + <td>xbInt16 xbDbf::CloseIndexFile( xbIx *pIx ) + </td><td>Close an index file. Indices are automatically closed when the table is closed. + <br>Not typically called in an application program.</td> +</tr> +<tr> + <td>xbInt16 xbDbf::CreateTag( const xbString &sIxType, const xbString &sName, const xbString &sKey, const xbString &sFilter, + xbInt16 iDescending, xbInt16 iUnique, xbInt16 iOverLay, xbIx **xbIxOut, void **vpTagOut ); + </td><td>Create a new tag.</td> +</tr> +<tr> + <td>xbInt16 xbDbf::DeleteTag( const xbString &sIxType, const xbString &sName ) + </td><td>Delete existing tag.</td> +</tr> +<tr> + <td>xbInt16 xbDbf::Find( xbString &sKey )<br>xbInt16 xbDbf::Find( xbDate &dtKey )<br>xbInt16 xbDbf::Find( xbDouble &dKey ) + </td><td>Find key value for the active tag.</td> +</tr> +<tr> + <td>xbIx * xbDbf::GetCurIx() const + </td><td>Returns a pointer to the current index object.</td> +</tr> + <td>xbString & xbDbf::GetCurIxType() const + </td><td>Returns the current index type.</td> +</tr> +</tr> + <td>void * xbDbf::GetCurTag() const + </td><td>Retrieve pointer to the current active tag.</td> +</tr> +<tr> + <td>const xbString & xbDbf::GetCurTagName() const + </td><td>Returns the current tag name.</td> +</tr> + <td>xbInt16 xbDbf::GetFirstKey() + </td><td>Retrieve the first key for the active tag.</td> +</tr> +<tr> + <td>xbIxList * xbDbf::GetIxList() const + </td><td>Returns a pointer to the list of active indices. +</tr> +<tr> + <td>xbInt16 xbDbf::GetLastKey() + </td><td>Retrieve the last key for the active tag.</td> +</tr> +<tr> + <td>xbInt16 xbDbf::GetNextKey() + </td><td>Retrieve the next key for the active tag.</td> +</tr> +<tr> + <td>xbInt32 xbDbf::GetPhysicalIxCnt() const + </td><td>Returns count of number of physical files opened for DBF table.</td> +</tr> +<tr> + <td>xbInt16 xbDbf::GetPrevKey() + </td><td>Retrieve the previous key for the active tag.</td> +<tr> + <td>xbLinkListNode<xbTag *> * xbDbf::GetTagList() const + </td><td>Returns pointer to linked list of open tags for the DBF file/table.</td> +</tr> +<tr> + <td>xbInt16 xbDbf::OpenIndex( const xbString &sIxType, const xbString &sIndexName ) + </td><td>Open an index file. Only used for index files that aren't automatically opened.</td> +</tr> +<tr> + <td>xbInt16 xbDbf::Reindex( xbInt16 iTagOpt ) + </td><td>Rebuild a tag. Available if XB_DEBUG_SUPPORT is on.</td> +</tr> +<tr> + <td>xbInt16 xbDbf::SetCurTag( const xbString &sTagName )<br> + void xbDbf::SetCurTag( const xbString &sIxType, xbIx *pIx, void *vpTag ) + </td><td>Set current tag.</td> +</tr> +</table> <br><br> -<h3>Expression Functions</h3> -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.<br><br> -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.<br><br> +<h3>Internal Data Storage</h3> <table border=1> -<tr><th>Function Name</th><th>Return Type</th><th>Description</th></tr> -<tr><td>ABS</td><td>N</td><td>Calculate absolute value of numeric expression</td></tr> -<tr><td>ALLTRIM</td><td>C</td><td>Trim leading andtrailing whitespace from a string</td></tr> -<tr><td>ASC</td><td>N</td><td>Return ASCII code for first character in a string</td></tr> -<tr><td>AT</td><td>N</td><td>Return starting position of a string within a string</td></tr> -<tr><td>CDOW</td><td>C</td><td>Retun character weekday name for a date</td></tr> -<tr><td>CHR</td><td>C</td><td>Convert numeric expression to a character</td></tr> -<tr><td>CMONTH</td><td>C</td><td>Return month name for a date</td></tr> -<tr><td>CTOD</td><td>D</td><td>Return date from a character date input</td></tr> -<tr><td>DATE</td><td>D</td><td>Return system date</td></tr> -<tr><td>DAY</td><td>N</td><td>Return the day of the month from a date</td></tr> -<tr><td>DEL</td><td>C</td><td>Return record deletion status for a record</td></tr> -<tr><td>DELETED</td><td>L</td><td>Return record deletion status for a record<</td></tr> -<tr><td>DESCEND</td><td>1</td><td>Clipper DESCEND function</td></tr> -<tr><td>DOW</td><td>N</td><td>Return number of day of week</td></tr> -<tr><td>DTOC</td><td>C</td><td>Return character date from input date</td></tr> -<tr><td>DTOS</td><td>C</td><td>Return character CCYYMMDD date from input date</td></tr> -<tr><td>EXP</td><td>N</td><td>Return exponent value</td></tr> -<tr><td>IIF</td><td>C</td><td>Immediate If</td></tr> -<tr><td>INT</td><td>N</td><td>Convert number to integer, truncate any decimals</td></tr> -<tr><td>ISALPHA</td><td>L</td><td>Check if string begins with alpha character</td></tr> -<tr><td>ISLOWER</td><td>L</td><td>Check if string begins with lower case alpha character</td></tr> -<tr><td>ISUPPER</td><td>L</td><td>Check if string begins with upper case character</td></tr> -<tr><td>LEFT</td><td>C</td><td>Return left characters from a string</td></tr> -<tr><td>LEN</td><td>N</td><td>Return lenght of string</td></tr> -<tr><td>LOG</td><td>N</td><td>Calculate logarithm</td></tr> -<tr><td>LOWER</td><td>C</td><td>Convert upper case to lower case</td></tr> -<tr><td>LTRIM</td><td>C</td><td>Trim left side of a string</td></tr> -<tr><td>MAX</td><td>N</td><td>Return higher of two values</td></tr> -<tr><td>MIN</td><td>N</td><td>Return lesser of two values</td></tr> -<tr><td>MONTH</td><td>N</td><td>Return number of month for a given date</td></tr> -<tr><td>RECNO</td><td>N</td><td>Return current rec number for a given table</td></tr> -<tr><td>RECCOUNT</td><td>N</td><td>Return number of records in a given table</td></tr> -<tr><td>REPLICATE</td><td>C</td><td>Repeat character expression N times</td></tr> -<tr><td>RIGHT</td><td>C</td><td>Return right characters from as tring</td></tr> -<tr><td>RTRIM</td><td>C</td><td>Trim right side of string</td></tr> -<tr><td>SPACE</td><td>C</td><td>Generate a string of N spaces</td></tr> -<tr><td>SQRT</td><td>N</td><td>Calculate square root</td></tr> -<tr><td>STOD</td><td>D</td><td>Convert 8 byte CCYYMMDD date to date</td></tr> -<tr><td>STR</td><td>C</td><td>Convert number to character string</td></tr> -<tr><td>STRZERO</td><td>C</td><td>Convert number to character string with leading zeroes. Clipper Function.</td></tr> -<tr><td>SUBSTR</td><td>C</td><td>Extract portion oif one string from another string</td></tr> -<tr><td>TRIM</td><td>C</td><td>Trim left and right sides of a string</td></tr> -<tr><td>UPPER</td><td>C</td><td>Conver lower case to upper case</td></tr> -<tr><td>VAL</td><td>N</td><td>Convert numeric characters to number</td></tr> -<tr><td>YEAR</td><td>N</td><td>Return year for a given date</td></tr> +<tr><th>Type<th>Stored in DBF as</th><th>Stored in NDX as</th><th>Stored in MDX as</th></tr> +<tr><td>C</td><td>Character data</td><td>Character data</td><td>Character data</td></tr> +<tr><td>F</td><td>Text numbers</td><td>xbDouble</td><td>xbBcd</td></tr> +<tr><td>N</td><td>Text numbers</td><td>xbDouble</td><td>xbBcd</td></tr> +<tr><td>D</td><td>Text YYYYMMDD</td><td>xbDouble Julian</td><td>xbDouble Julian</td></tr> </table> +<br><br> + +<hr> +<h2>NDX Indices</h2> +The objective of this section is to provide information regarding the +basic concepts of how .NDX index files work in the Xbase64 library. +Information in this section has been acquired by searching the internet +and by examining the structure of known good NDX indexes.<br><br> + +<h4>NDX Index File Characteristics</h4> +<li>NDX indices maintain keys in ascending sort order only.<br><br> +<li>NDX indices support <em>unique</em> or <em>non unique</em> keys.<br><br> + +<em>Unique</em> 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. <br><br> -<h3>Expression Components</h3> -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 "-'". + +<em>Non-unique</em> 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.<br><br> + +<li>NDX indexes are automatically updated by the Xbase library after the +indices are opened.<br> +<li>Character keys are left justified and padded on the right with spaces.<br> +<li>Numeric keys are stored as eight byte double values.<br> +<li>Date kets are stored as julian eigth byte double values.<br> + +<h4>NDX File Internals</h4> + +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.<br><br> + +<li>The <em>Head Node</em> 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.<br><br> + + +<TABLE BORDER> +<CAPTION ALIGN="TOP"><h3>NDX Header Node</H3></CAPTION> +<TR VALIGN="BASELINE"> +<TR><TH ALIGN="LEFT">Type<TD>Size<TD>Field Name<TD>Description +<TR><TH ALIGN="LEFT">xbLong<TD>4<TD>StartNode<TD>This identifies the root node of + the index. The Header node is node 0. +<TR><TH ALIGN="LEFT">xbLong<TD>4<TD>Total Nodes<TD>This is the count of the total + nodes in the index. The count includes the header node. +<TR><TH ALIGN="LEFT">xbLong<TD>4<TD>NoOfKeys<TD>Total number of keys in the index +1 +<TR><TH ALIGN="LEFT">xbUShort<TD>2<TD>KeyLen<TD>The index key length +<TR><TH ALIGN="LEFT">xbUShort<TD>2<TD>KeysPerNode<TD>The maximum number of keys per node +<TR><TH ALIGN="LEFT">xbUShort<TD>2<TD>KeyType<TD>Type of key<br> +00 - Character<br>01 - Numeric +<TR><TH ALIGN="LEFT">xbLong<TD>4<TD>Keysize<TD>Key record size + 8 +<TR><TH ALIGN="LEFT">char<TD>1<TD>Unknown<TD>Reserved +<TR><TH ALIGN="LEFT">char<TD>1<TD>Unique<TD>Unique indicator<br> +00 - Not Unique - XB_NON_UNIQUE<br>01 - Unique - XB_UNIQUE +<TR><TH ALIGN="LEFT">char<TD>488<TD>KeyExpression<TD>Key expression string +<TR><TH ALIGN="LEFT"><TD>512<TD><TD>Total bytes in node +</TABLE> <br><br> -A field is simply a field name in the default database, or is in the form -of database->fieldname. +The following structure is used by the Xbase64 NDX routines: +<xmp> + 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 */ + } +</xmp> +<br><br> + +<h4>Interior and Leaf Nodes</h4> + +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.<br><br> +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.<br><br> +Leaf nodes have 0 in the LeftNodeNo field but do have a value in the +DbfRecNo field which points to a DFB record.<br><br> + + +<TABLE BORDER> +<CAPTION ALIGN="TOP"><h3>NDX Interior Node and Leaf Node Structure</H3></CAPTION> +<TR VALIGN="BASELINE"> +<TR><TH ALIGN="LEFT">Type<TD>Size<TD>Field Name<TD>Description +<TR><TH ALIGN="LEFT">xbLong<TD>4<TD>NoOfKeysThisNode<TD>The number of key values in this node. +<TR><TH ALIGN="LEFT">char<TD>508<TD>KeyRec<TD>A repeating structure of + pointers and keys. See the next table for the KeyRec structure. +</TABLE> <br><br> -<h3>Expression Literals</h3> +<TABLE BORDER> +<CAPTION ALIGN="TOP"><h3>KeyRec Structure</H3></CAPTION> +<TR VALIGN="BASELINE"> +<TR><TH ALIGN="LEFT">Type<TD>Size<TD>Field Name<TD>Description +<TR><TH ALIGN="LEFT">xbLong<TD>4<TD>LeftNodeNo<TD>The node number of the lower node + for this key. 0 in Leaf Nodes. +<TR><TH ALIGN="LEFT">xbLong<TD>4<TD>DbfRecNo<TD>The DBF record number for this key. + 0 in Interior Nodes. +<TR><TH ALIGN="LEFT">char<TD>KeyLen<TD>KeyValue<TD>The key value. +</TABLE> -<table border=1> -<tr><th>Type</th><th>Example</th></tr> -<tr><td>CHAR</td><td>"literal" or 'literal'</td></tr> -<tr><td>NUMERIC</td><td>+99999.99</td></tr> -<tr><td>DATE</td><td>{10/07/60} or {02/09/1989}</td></tr> -</table> +<br><br> +For those interested in knowing how the Xbase64 DBMS manipulates and +navigates index files, the following discussion may be helpfull.<br><br> +Xbase64 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. <br><br> -<h3>Expression Operators</h3> -<table border=1> -<tr><th>Type</th><th>Operator</th><th>Precedence</th><th>Result</th><th>Notes</th></tr> -<tr><td>Parens</td><td>()</td><td>12</td></tr> -<tr><td>Numeric Operator</td><td>+ (unary)</td><td>11</td><td>N</td></tr> -<tr><td>Numeric Operator</td><td>- (unary)</td><td>11</td><td>N</td></tr> -<tr><td>Numeric Operator</td><td>--X</td><td>10</td><td>N</td></tr> -<tr><td>Numeric Operator</td><td>++X</td><td>10</td><td>N</td></tr> -<tr><td>Numeric Operator</td><td>**</td><td>9</td><td>N</td></tr> -<tr><td>Numeric Operator</td><td>^</td><td>9</td><td>N</td></tr> -<tr><td>Numeric Operator</td><td>%</td><td>8</td><td>N</td></tr> -<tr><td>Numeric Operator</td><td>*</td><td>8</td><td>N</td></tr> -<tr><td>Numeric Operator</td><td>/</td><td>8</td><td>N</td></tr> -<tr><td>Numeric Operator</td><td>+ Addition</td><td>7</td><td>N</td></tr> -<tr><td>Numeric Operator</td><td>- Subtraction</td><td>7</td><td>N</td></tr> -<tr><td>Numeric Operator</td><td>X--</td><td>6</td><td>N</td></tr> -<tr><td>Numeric Operator</td><td>X++</td><td>6</td><td>N</td></tr> -<tr></tr> -<tr><td>String Operator</td><td>+</td><td>5</td><td>C</td><td>Concatonate 1</td></tr> -<tr><td>String Operator</td><td>-</td><td>5</td><td>C</td><td>Concatonate 2</td></tr> -<tr></tr> -<tr><td>Relational Operator</td><td>=</td><td>4</td><td>L</td><td>N,C,D</td></tr> -<tr><td>Relational Operator</td><td>#, <>, !=</td><td>4</td><td?L</td><td>N,C,D</td></tr> -<tr><td>Relational Operator</td><td><</td><td>4</td><td>L</td><td>N,C,D</td></tr> -<tr><td>Relational Operator</td><td>></td><td>4</td><td>L</td><td>N,C,D</td></tr> -<tr><td>Relational Operator</td><td><=</td><td>4</td><td>L</td><td>N,C,D</td></tr> -<tr><td>Relational Operator</td><td>>=</td><td>4</td><td>L</td><td>N,C,D</td></tr> -<tr><td>Relational Operator</td><td>$</td><td>4</td><td>L</td><td>N,C,D</td></tr> -<tr><td>Relational Operator</td><td>==</td><td></td><td></td><td>Clipper operator, not implemented yet</td></tr> -<tr></tr> -<tr><td>Logical Operator</td><td>NOT</td><td>3</td><td>L</td><td>Evaluated after all math and relational operators</td></tr> -<tr><td>Logical Operator</td><td>.NOT.</td><td>3</td><td>L</td><td>Evaluated after all math and relational operators</td></tr> -<tr><td>Logical Operator</td><td>AND</td><td>2</td><td>L</td><td>Evaluated after all math and relational operators</td></tr> -<tr><td>Logical Operator</td><td>.AND.</td><td>2</td><td>L</td><td>Evaluated after all math and relational operators</td></tr> -<tr><td>Logical Operator</td><td>OR</td><td>1</td><td>L</td><td>Evaluated after all math and relational operators</td></tr> -<tr><td>Logical Operator</td><td>.OR.</td><td>1</td><td>L</td><td>Evaluated after all math and relational operators</td></tr> -</table> +<hr> +<h2>MDX Indices</h2> +The objective of this section is to provide information regarding the +basic concepts of how .MDX index files work in the Xbase64 library.<br> +Information for MDX files has been gathered by searching the internet +and by examining the structure of known good MDX index files.<br><br> + +<h4>MDX Index File Characteristics</h4> + +<li>MDX files are the same name as the corresponding DBF file with an MDX extension. +<li>MDX files are automatically opened by the library when the DBF file is opened. +<li>MDX index files (aka prod indices) contain from one to 47 tags, where each tag has it's own key characteristics. +<li>MDX indices maintain keys in either ascending or descending sort order. +<li>MDX indices support filtered keys. For example, a filter of <b>.NOT. DELETED()</b> will keep deleted records out +of the index tag. +<li>MDX indices are automatically updated by the Xbase library after the +indices are opened. +<li>MDX indices support <em>unique</em> or <em>non unique</em> keys.<br><br> + +<em>Unique</em> 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. <br><br> -<h3>Example Expressions</h3> -<li>CUSTOMERS->LNAME + ", " + CUSTOMERS->FNAME -<li>LNAME + ", " + FNAME -<li>STARTDT + 90 -<li>DATE() - 7 -<li>YEAR( TODAY() ) -<li>IIF( "A" = "N", "true result", "false result" ) -<li>IIF( "A" = "N" .OR. 2 > 1 , "true result", "false result" ) -<li>IIF( .NOT. "A" = "N", "true result", "false result" ) -<li>.NOT. DELETED() + +<em>Non-unique</em> 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.<br><br> + + +<li>Character keys are left justified and padded on the right with spaces. +<li>Numeric keys are stored as twelve byte BCD values. +<li>Date keys are stored as eight byte double julian values. + +<h4>MDX File Internals</h4> + +The following information is not needed to use the library, it is just included +for general information.<br><br> + +MDX files are comprised of 512 pages where multiple pages make a block. The default +setting is 1024 blocks, each block containing two pages.<br><br> + +The first four pages contain: +<li>Bytes 0 - 543 contain general file information. +<li>Bytes 544 - 2047 is a 47 item table containing specific tag information. +<br><br> + +Pages five and beyound: +<li>Bytes 2048 and beyond contain tag header blocks, interior nodes and leaf nodes. + +<br><br> + +<h4>Interior and Leaf Nodes</h4> + +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.<br><br> + +<hr> +<br><br> +<h2>TDX Indices</h2> +TDX index files are an Xbase64 library specific implementation of indexing which +can be used for creating temporary indices. They can be created as needed and are +automatically deleted when the table/DBF file is closed.<br><br> + +TDX files are built on the MDX index logic and supports the following functionality: +<li>Complex Key Expressions +<li>Filters +<li>Unique / Non-unique keys +<li>Ascending / Descending keys +<li>Max of 47 unique temporary index tags <br><br> +To create a temporary index, set the Type field to "TDX" when using the xbDbf::CreateTag() method. +All other functionality is the same when using temp indices. The only requirement is to set the +type when creating it.<br><br> -<h3>Example program</h3> -For an example on how to use the expression logic, see program -<em>src/examples/xb_ex_expression.cpp</em>. +Additionally, the create tag only defines the index. If the table is populated with data and +you need the index populated accordingly, use the xbDbf::Reindex() method to bring it up to data after +creating it. <br><br> <hr> diff --git a/docs/html/xbc6.html b/docs/html/xbc6.html index 094545f..aa38ad4 100755 --- a/docs/html/xbc6.html +++ b/docs/html/xbc6.html @@ -2,152 +2,112 @@ <HTML> <TITLE>Xbase DBMS Chapter 6</TITLE> <BODY BGCOLOR=#FFFFFF> -<H1><p align="center">Index Overview</p></H1> -<p align="center">Chapter Updated 12/09/22</p><hr> +<H2><p align="center">SQL Support</p></H2> +<p align="center">Chapter Updated 04/28/23</p><hr> -The objective of this chapter is to provide information regarding -the basic concepts of index processing for the Xbase library.<br><br> - - -<h2>Overview</h2> - -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. +<h3>SQL Command Status</h3> +Development of SQL support is still underway and very preliminary. As of the 4.0.3 version, the following SQL commands +are available.<br><br> +The SQL commands are modeled after industry standard SQL specifications and do what you would expect an SQL command to do. +<br> +Use of <em>[brackets]</em> in this chapter identifies optional components of a given command. <br><br> -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. - - -<h2>Tags</h2> - -Each index file contains one or more tags depending on the file type. Each tag is a sort order -and has characteristics: Sort order (ASC or DESC), unique or not unique and some formats support filtering. -Each open table (dbf file) has an "active tag" for database operations. - -<h2>Index processing design</h2> +<hr> +<h3>ALTER TABLE</h3> +Expected format:<br> +ALTER TABLE tablename.DBF RENAME TO newtablename.DBF +<br><br> +<hr> +<h3>CREATE INDEX</h3> +Expected format to create an Dbase 3, NDX index:<br> +CREATE INDEX ixname.NDX ON tablename.dbf ( EXPRESSION ) [ASSOCIATE] -The library is construcuted to handle index files with multiple tags per file. Single tag files like the NDX indices -are treated as a multi tag file, but there is only one tag. This allows for maximum flexibility for future -additional index types. +<br><br> +Expected format to create an Dbase 4, tag on an MDX index:<br> +CREATE [UNIQUE] INDEX tagname ON tablename.DBF ( EXPRESSION ) [DESC] [FILTER .NOT. DELETED()] +<br><br> +The ASSOCIATE parameter is specific to Xbase64 library, it is used to associate non production (NDX) index file to a dbf +file so it will be automatically opened with the dbf file whenever the dbf file is opened by the xbase64 routines. +<br><br> +The [ASSOCIATE] parameter is not used with MDX production indices +<br><br> +Xbase first looks for ".NDX" in the file name to determine if an NDX index should be created. +If .NDX is not in the filename, it looks in the uda for "IXTYPE" for either NDX or MDX to +detmermine the index type to create. if IXTYPE is not found, it creates an MDX tag. +<br><br> +The optional DESC parameter defines an entire index key as descending. This is +different than other SQL implementations where specific fields can be descending. +<br><br> +The optional FILTER parameter is specific to the XBASE64 library, is it used to assign a filter to a tag in an +MDX style index. Everything to the right of the keyword FILTER is considered part of the filter. +<br><br> +The original DBASE indices used to '+' to create an index on more than one field +<br>ie: FIELD1+FIELD2+FIELD3 +<br><brSQL uses commas: ie: FIELD1, FIELD2, FIELD3 +<br> +The Xbase library supports either '+' or ',' when creating mutli field indices. +<br><br> +<hr> -<h2>Index updates</h2> -The library automatically updates all tags in all open index files. +<h3>CREATE TABLE</h3> +Expected format:<br> +CREATE TABLE tablename.dbf (Field1 CHAR(10), INTFLD1 INTEGER, ... ) +<br><br> +<table border=1> +<tr><th>SQL TYPE</th><th>XBASE Field Type</th></tr> +<tr><td>SMALLINT</td><td>NUMERIC(6,0)</td></tr> +<tr><td>INTEGER</td><td>NUMERIC(11,0)</td></tr> +<tr><td>DECIMAL(x,y)</td><td>NUMERIC(x+1,y)</td></tr> +<tr><td>NUMERIC(x,y)</td><td>NUMERIC(x,y)</td></tr> +<tr><td>FLOAT(x,y)</td><td>FLOAT(x,y)</td></tr> +<tr><td>CHAR(n)</td><td>CHARACTER(n)</td></tr> +<tr><td>DATE</td><td>DATE</td></tr> +<tr><td>VARCHAR</td><td>MEMO</td></tr> +<tr><td>LOGICAL</td><td>LOGICAL</td></tr> +</table> +<br> +<hr> +<h3>DELETE</h3> +Expected format:<br> +DELETE FROM tablename.DBF [WHERE expression] <br><br> -<h2>Index File Types</h2> +<hr> -<table border=1> -<tr><th>File<br>Type</th><th>Source</th><th>Max Tags<br>Per File</th><th>Auto Opened</th><th>Sort Order</th><th>Unique Keys</th> - <th>Reclaimed Nodes</th><th>Filter Support</th><th>Status</th></tr> -<tr> - <td>NDX</td><td>dBase</td> - <td><center>1</center></td> - <td><center>Optional</center></td> - <td>ASC only</td> - <td><center>Y</center></td> - <td><center>N</center></td> - <td><center>N</center></td> - <td><center>Available in 4.0.1</center></td> -</tr> -<tr> - <td>MDX</td><td>dBase</td> - <td><center>47</center></td> - <td><center>Yes</center></td> - <td><center>ASC or DESC</center></td> - <td><center>Y</center></td> - <td><center>Y</center></td> - <td><center>Y</center></td> - <td><center>Available in 4.0.1</center></td> -</tr> -<tr> - <td>NTX</td> - <td>Clipper</td> - <td><center>1</center></td> - <td><center>Optional</center></td> - <td><center>?</center></td> - <td><center>?</center></td> - <td><center>?</center></td> - <td><center>?</center></td> - <td><center>Pending upgrades</center></td> -</tr> -<tr> - <td>CDX</td> - <td>Fox Pro</td> - <td><center>?</center></td> - <td><center>?</center></td> - <td><center>?</center></td> - <td><center>?</center></td> - <td><center>?</center></td> - <td><center>?</center></td> - <td><center>Pending upgrades</center></td> -<tr> -<tr> - <td>IDX</td><td>Fox Pro</td><td></td><td></td><td></td><td></td><td></td><td></td><td>Undeveloped</td> -<tr> -</table> +<h3>DROP INDEX</h3> +Expected format:<br> +DROP INDEX [IF EXISTS] ixname.NDX ON tablename.DBF<br> +DROP INDEX [IF EXISTS] tagname ON tablename.DBF<br> +<br> -<br><br> -<h2>Index/Tag Methods</h2> -<table border=1> -<tr><th>Method</th><th>Description</th></tr> - -<tr> - <td>xbDbf::CheckTagIntegrity</td><td>Checks a tag for missing or duplicate entries. Available if XB_DEBUG_SUPPORT is on.</td> -</tr> -<tr> - <td>xbDbf::CreateTag</td><td>Create a new tag.</td> -</tr> -<tr> - <td>xbDbf::DeleteTag</td><td>Delete existing tag.</td> -</tr> -<tr> - <td>xbDbf::Find</td><td>Find key value for the active tag.</td> -</tr> -<tr> - <td>xbDbf::GetFirsKey</td><td>Retrieve the first key for the active tag.</td> -</tr> -<tr> - <td>xbDbf::GetLastKey</td><td>Retrieve the last key for the active tag.</td> -</tr> -<tr> - <td>xbDbf::GetNextKey</td><td>Retrieve the next key for the active tag.</td> -</tr> -<tr> - <td>xbDbf::GetPrevKey</td><td>Retrieve the previous key for the active tag.</td> -</tr> -<tr> - <td>xbDbf::GetCurTag</td><td>Retrieve the tag name key for the active tag.</td> -</tr> -<tr> - <td>xbDbf::OpenIndex</td><td>Open an index file. Only used for index files that aren't automatically opened.</td> -</tr> -<tr> - <td>xbDbf::Reindex</td><td>Rebuild a tag. Available if XB_DEBUG_SUPPORT is on.</td> -</tr> -<tr> - <td>xbDbf::SetCurTag</td><td>Set current tag.</td> -</tr> -</table> -<br><br> -<h2>Internal Data Storage</h2> -<table border=1> -<tr><th>Type<th>Stored in DBF as</th><th>Stored in NDX as</th><th>Stored in MDX as</th></tr> -<tr><td>C</td><td>Character data</td><td>Character data</td><td>Character data</td></tr> -<tr><td>F</td><td>Text numbers</td><td>xbDouble</td><td>xbBcd</td></tr> -<tr><td>N</td><td>Text numbers</td><td>xbDouble</td><td>xbBcd</td></tr> -<tr><td>D</td><td>Text YYYYMMDD</td><td>xbDouble Julian</td><td>xbDouble Julian</td></tr> -</table> +<hr> +<h3>DROP TABLE</h3> +Expected format:<br> +DROP TABLE [IF EXISTS] tablename.DBF +<br> +<hr> +<h3>INSERT</h3> +Expexted format:<br> +INSERT INTO tablename (field1, field2, field3,...) VALUES ( 'charval', numval, 'what is the correct odbc date format to use? CCYYMMDD'); <br><br> <hr> -<p><img src="xbase.jpg"><br><hr> +<h3>SET</h3> +Used to set a variable name<br> +Expected format:<br> +SET ATTRIBUTE = DATAVALUE<br> +SET ATTRIBUTE = ^ (to delete an entry) <br> +<br> +<hr><br><br> +<p><img src=xbase.jpg><br><hr> + </BODY> </HTML> + + diff --git a/docs/html/xbc7.html b/docs/html/xbc7.html index 20a60de..6aa7135 100755 --- a/docs/html/xbc7.html +++ b/docs/html/xbc7.html @@ -2,151 +2,51 @@ <HTML> <TITLE>Xbase DBMS Chapter 7</TITLE> <BODY BGCOLOR=#FFFFFF> -<H2><p align="center">NDX Indices</p></H2> -<p align="center">Chapter Updated 11/27/22</p><hr> +<H2><p align="center">Class Inventory</p></H2> +<p align="center">Chapter Updated 04/28/23</p><hr> +<br> +<center><h3>Class Descriptions</h3></center> + +<center> +<table border=1> +<tr><th>Class</th><th>Description</th></tr> +<tr><td>xbBcd</td><td>Supports binary coded decimal data</td></tr> +<tr><td>xbBlockRead<td>Supports block read functionality for improved sequential file access performance.</td></tr> +<tr><td>xbDate</td><td>Support date operations on a given date formatted as YYYYMMDD</td></tr> +<tr><td>xbDbf</td><td>Base class for DBF file handling. If you are adding support for a new file type, <br>derive new file type class from this.</td></tr> +<tr><td>xbDbf3</td><td>Derived from xbDbf, supports DBase V3 files</td></tr> +<tr><td>xbDbf4</td><td>Derived from xbDbf, supports DBase V4 files</td></tr> +<tr><td>xbExp</td><td>Class for supporting expression logic</td></tr> +<tr><td>xbExpNode</td><td>Class definition of a single node, utilized by xbExp</td></tr> +<tr><td>xbFile</td><td>Main file class. If you are porting this library to another platform, start here</td></tr> +<tr><td>xbFilter</td><td>Supports filters</td></tr> +<tr><td>xbIx</td><td>Base class for index file support. If you are adding support for a new index type, <br>derive new index type class from this.</td></tr> +<tr><td>xbIxNdx</td><td>Derived from xbIx, supports NDX style indices.</td></tr> +<tr><td>xbIxMdx</td><td>Derived from xbIx, supports MDX style indices.</td></tr> +<tr><td>xbIxTdx</td><td>Derived from xbIxMdx, supports TDX (temporary) style indices.<br>Exclusive to XBase64, not compatible with other XBase tools.</td></tr> +<tr><td>xbLinkList</td><td>Class supporting linked list functionality</td></tr> +<tr><td>xbLinkListOrd</td><td>Class supporting ordered linked list functionality</td></tr> +<tr><td>xbLinkListNode</td><td>Class defining one node, used by xbLinkList and xbLinkListOrd</td></tr> +<tr><td>xbLog</td><td>Class supporting general log file activity</td></tr> +<tr><td>xbMemo</td><td>Base class for supporting memo (.DBT) files. If you are adding support for a new memo type, <br>derive new memo type class from this.</td></tr> +<tr><td>xbMemoDbt3</td><td>Derived from xbMemo, supports V3 Memo files</td></tr> +<tr><td>xbMemoDbt4</td><td>Derived from xbMemo, supports V3 Memo files</td></tr> +<tr><td>xbSql</td><td>Supports SQL access</td></tr> +<tr><td>xbSsv</td><td>Base class, shared system values</td></tr> +<tr><td>xbString</td><td>String handling class</td></tr> +<tr><td>xbTag</td><td>Class to support index tags</td></tr> +<tr><td>xbTblMgr</td><td>Class used internally in the library for managing multiple open files/tables</td></tr> +<tr><td>xbUda</td><td>Class for supporting fields for the xbSql functions. Stands for User data area</td></tr> +<tr><td>xbXBase</td><td>Class to tie everything together. Every application program starts with one of these</td></tr> +</table> +</center> -The objective of this chapter is to provide information regarding the -basic concepts of how .NDX index files work in the Xbase environment.<br><br> - -The information in this chapter has been gathered by searching the internet -and by examining the structure of known good NDX indexes.<br><br> - -<h4>NDX Index File Characteristics</h4> - -<li>NDX indices maintain keys in ascending sort order only.<br><br> -<li>NDX indices support <em>unique</em> or <em>non unique</em> keys.<br><br> - -<em>Unique</em> 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. -<br><br> - -<em>Non-unique</em> 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.<br><br> - -<li>NDX indexes are automatically updated by the Xbase library after the -indices are opened.<br><br> - -<li>Character keys are left justified and padded on the right with spaces.<br><br> - -<li>Numeric keys are stored as eight byte double values.<br><br> - -<h4>NDX File Internals</h4> - -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.<br><br> - -<li>The <em>Head Node</em> 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.<br><br> - - -<TABLE BORDER> -<CAPTION ALIGN="TOP"><h3>NDX Header Node</H3></CAPTION> -<TR VALIGN="BASELINE"> -<TR><TH ALIGN="LEFT">Type<TD>Size<TD>Field Name<TD>Description -<TR><TH ALIGN="LEFT">xbLong<TD>4<TD>StartNode<TD>This identifies the root node of - the index. The Header node is node 0. -<TR><TH ALIGN="LEFT">xbLong<TD>4<TD>Total Nodes<TD>This is the count of the total - nodes in the index. The count includes the header node. -<TR><TH ALIGN="LEFT">xbLong<TD>4<TD>NoOfKeys<TD>Total number of keys in the index +1 -<TR><TH ALIGN="LEFT">xbUShort<TD>2<TD>KeyLen<TD>The index key length -<TR><TH ALIGN="LEFT">xbUShort<TD>2<TD>KeysPerNode<TD>The maximum number of keys per node -<TR><TH ALIGN="LEFT">xbUShort<TD>2<TD>KeyType<TD>Type of key<br> -00 - Character<br>01 - Numeric -<TR><TH ALIGN="LEFT">xbLong<TD>4<TD>Keysize<TD>Key record size + 8 -<TR><TH ALIGN="LEFT">char<TD>1<TD>Unknown<TD>Reserved -<TR><TH ALIGN="LEFT">char<TD>1<TD>Unique<TD>Unique indicator<br> -00 - Not Unique - XB_NON_UNIQUE<br>01 - Unique - XB_UNIQUE -<TR><TH ALIGN="LEFT">char<TD>488<TD>KeyExpression<TD>Key expression string -<TR><TH ALIGN="LEFT"><TD>512<TD><TD>Total bytes in node -</TABLE> -<br><br> -The following structure is used by the Xbase NDX routines: -<xmp> - 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 */ - } -</xmp> -<br><br> - -<h4>Interior and Leaf Nodes</h4> - -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.<br><br> - -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.<br><br> - -Leaf nodes have 0 in the LeftNodeNo field but do have a value in the -DbfRecNo field which points to a DFB record.<br><br> - - -<TABLE BORDER> -<CAPTION ALIGN="TOP"><h3>NDX Interior Node and Leaf Node Structure</H3></CAPTION> -<TR VALIGN="BASELINE"> -<TR><TH ALIGN="LEFT">Type<TD>Size<TD>Field Name<TD>Description -<TR><TH ALIGN="LEFT">xbLong<TD>4<TD>NoOfKeysThisNode<TD>The number of key values in this node. -<TR><TH ALIGN="LEFT">char<TD>508<TD>KeyRec<TD>A repeating structure of - pointers and keys. See the next table for the KeyRec structure. -</TABLE> +<hr> <br><br> -<TABLE BORDER> -<CAPTION ALIGN="TOP"><h3>KeyRec Structure</H3></CAPTION> -<TR VALIGN="BASELINE"> -<TR><TH ALIGN="LEFT">Type<TD>Size<TD>Field Name<TD>Description -<TR><TH ALIGN="LEFT">xbLong<TD>4<TD>LeftNodeNo<TD>The node number of the lower node - for this key. 0 in Leaf Nodes. -<TR><TH ALIGN="LEFT">xbLong<TD>4<TD>DbfRecNo<TD>The DBF record number for this key. - 0 in Interior Nodes. -<TR><TH ALIGN="LEFT">char<TD>KeyLen<TD>KeyValue<TD>The key value. -</TABLE> +Fix me... +<p><img src="Xbase64ClassDiagramV2.jpeg" width=1800 height=1800><br> <br><br> -For those interested in knowing how the Xbase DBMS manipulates and -navigates index files, the following discussion may be helpfull.<br><br> - -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. - <hr> <p><img src="xbase.jpg"><br><hr> </BODY> diff --git a/docs/html/xbc8.html b/docs/html/xbc8.html index fcc461c..c7fccbc 100755 --- a/docs/html/xbc8.html +++ b/docs/html/xbc8.html @@ -2,77 +2,222 @@ <HTML> <TITLE>Xbase DBMS Chapter 8</TITLE> <BODY BGCOLOR=#FFFFFF> -<H2><p align="center">MDX Indices</p></H2> -<p align="center">Chapter Updated 12/02/22</p><hr> +<H2><p align="center">Class xbSsv</p></H2> +<p align="center">Chapter Updated 04/13/28</p><hr> -The objective of this chapter is to provide information regarding the -basic concepts of how .MDX index files work in the Xbase environment.<br><br> +<h3>Class xbSsv - Shared System Values.</h3> -The information in this chapter has been gathered by searching the internet -and by examining the structure of known good <DX indexes.<br><br> +Base class xbSsv is used for maintaining static variables used system +wide by the XBase library routines and is a base class that is used by the xbXBase class. +See the diagram in chapter 15 to gain an understanding of where the xbSsv class sits in relation to the +other classes. Accessing the methods in this class are done via the xbXBase class instance.<br><br> +Additionally, there are a few other misc routines contained in this class that are available to all +subordinate classes/objects. +<br><br><br><br> -<h4>MDX Index File Characteristics</h4> +<center> +<table border=1> +<tr><th width=40%>Method</th><th>Description</th></tr> -<li>MDX files are the same name as the corresponding DBF file with an MDX extension. -<li>MDX files are automatically opened by the library when the DBF file is opened. -<li>MDX index files (aka prod indices) contain from one to 47 tags, where each tag has it's own key characteristics. -<li>MDX indices maintain keys in either ascending or descending sort order. -<li>MDX indices support filtered keys. For example, a filter of <b>.NOT. DELETED()</b> will keep deleted records out -of the index tag. -<li>MDX indices are automatically updated by the Xbase library after the -indices are opened. +<tr><td>void BitDump( unsigned char c ) const<br>void BitDump( char c ) const</td><td>These routines dump the bits for a specified char field to stdout.</td></tr> +<tr><td>xbBool BitSet( unsigned char c, xbInt16 iBitNo ) const</td><td>This routine will set a specified bit in a char field.</td></tr> +<tr><td>void DisplayError( xbInt16 ErrorCode ) const</td><td>This routine prints a description for a specifed error to stdout.</td></tr> -<li>MDX indices support <em>unique</em> or <em>non unique</em> keys.<br><br> +<tr><td>xbString& GetDataDirectory() const<br>void SetDataDirectory( const xbString &sDataDirectory )</td> + <td>Get and Set the current directory where the library routines expect to find the .DBF, .DBT, .NDX and .MDX files.</td></tr> -<em>Unique</em> 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. -<br><br> +<tr><td>xbString& GetDefaultDateFormat() const<br>void SetDefaultDateFormat( const xbString &sDefaultDateFormat )</td> + <td>Get and Set the current default date format used by the date formatting routines if no format specifier is provided.</td></tr> -<em>Non-unique</em> 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.<br><br> +<tr><td>xbInt16 GetEndianType() const</td><td>Returns the current Endian type of the machine the library is operating on.</td></tr> +<tr><td>const char *GetErrorMessage( xbInt16 ErrorCode ) const</td><td>Returns a pointer to an error message for a given error number.</td></tr> +<tr><td>xbBool GetDefaultAutoCommit() const<br>void SetDefaultAutoCommit( xbBool bDefaultAutoCommit )</td> + <td>Get and Set the default auto commit status. If auto commit is on, the library will automatically post any updates to the database when navigating away from an updated record.</td></tr> -<li>Character keys are left justified and padded on the right with spaces. -<li>Numeric keys are stored as twelve byte BCD values. -<li>Date keys are stored as eight byte double julian values. +<tr><td>xbBool GetHomeDir( xbString &sHomeDirOut )</td><td>Get the home directory for the current user.</td></tr> -<h4>MDX File Internals</h4> +<tr><td>xbString& GetLogDirectory() const<br>void SetLogDirectory( const xbString &sLogDirectory )</td> + <td>Get and set the directory location for any system generated logfiles.</td></tr> +<tr><td>xbString& GetLogFileName() const<br>void SetLogFileName( const xbString &sLogFileName )</td><td>Returns the default log file name.</td></tr> -The following information is not needed to use the library, it is just included -for general information.<br><br> -MDX files are comprised of 512 pages where multiple pages make a block. The default -setting is 1024 blocks, each block containing two pages.<br><br> +<tr><td>xbBool GetMultiUser() const<br>void SetMultiUser( xbBool bMultiUser )</td> + <td>Get and set multi user status. This turns auto locking on and off. For better performance in single user applications, turn multuser off.</td></tr> -The first four pages contain: -<li>Bytes 0 - 543 contain general file information. -<li>Bytes 544 - 2047 is a 47 item table containing specific tag information. -<br><br> +<tr><td>char GetPathSeparator() const</td> + <td>Get the path separator value for the current environment. Returns either \ (for Windows environment) or / (for Unix environment).</td></tr> -Pages five and beyound: -<li>Bytes 2048 and beyond contain tag header blocks, interior nodes and leaf nodes. +<tr><td>xbString& GetTempDirectory() const<br>void SetTempDirectory( const xbString &sTempDirectory )</td><td>Get and set the temp folder.</td></tr> -<br><br> -<h4>Interior and Leaf Nodes</h4> +<tr><td>xbInt16 GetUniqueKeyOpt() const<br>xbInt16 SetUniqueKeyOpt( xbInt16 iUniqueKeyOpt )</td> + <td>Determines library behavior for unique key processing. The original Dbase (tm) product allowed duplicate recrds in the .DBF file when the unique option was specified for a given index tag. + The Xbase library supports either the original DBase behavior (XB_EMULATE_DBASE), or the prevention of duplicate records for duplicate keys (XB_HALT_ON_DUPKEY).</td></tr> + + +<tr><td>xbInt16 GetDefaultLockRetries() const<br>void SetDefaultLockRetries( xbInt16 iRetryCount )</td> + <td>Get and Set the number of times to attempt a lock</td></tr> + +<tr><td>xbInt32 GetDefaultLockWait() const<br>void SetDefaultLockWait( xbInt32 lRetryWait ) + </td><td>Get and Set the wait time between lock attempts.</td></tr> -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. +<tr><td>xbInt16 GetDefaultLockFlavor() const<br>void SetDefaultLockFlavor( xbInt16 iLockFlavor ) + </td><td>For future use. With current versions, only DBase (TM) locking offsets are supported.</td></tr> -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.<br><br> +<tr><td>xbBool GetDefaultAutoLock() const<br>void SetDefaultAutoLock( xbBool bAutoLock )<br>void EnableDefaultAutoLock()<br>void DisableDefaultAutoLock() + </td><td>Set, Get or update Auto Lock Status</td></tr> + + +<tr><td>xbInt16 GetCreateMdxBlockSize() const<br>xbInt16 SetCreateMdxBlockSize( xbInt16 ulBlockSize ) + </td><td>Set or get MDX Index block size. Must be a multiple of 512.</td></tr> + +<tr><td>xbUInt32 GetDefaultBlockReadSize() const<br>void SetDefaultBlockReadSize( xbUInt32 ulDfltBlockReadSize ) + </td><td>Set or Get the default block size for Block Read functionality. Block reading is used to improve sequentential access performance.</td></tr> +</table> <br><br> +<h3>Example program using xbSsv methods</h3> +</center> +<xmp> +/* xb_ex_ssv.cpp +XBase64 Software Library + +Copyright (c) 1997,2003,2014,2021,2022,2023 Gary A Kunkel + +The xb64 software library is covered under the terms of the GPL Version 3, 2007 license. + +Email Contact: + + XDB-devel@lists.sourceforge.net + XDB-users@lists.sourceforge.net + +This program demonstrates using functionality of the xbSsv class (Shared system values) + +*/ + +#include "xbase.h" + +using namespace xb; + +int main( int ac, char ** av ){ + + xbXBase x; // set up xbase for business + xbString sMsg; // a message string + + sMsg.Sprintf( "Program [%s] initializing...", av[0] ); + std::cout << sMsg.Str() << std::endl; + + // example code to set up log file usage + #ifdef XB_LOGGING_SUPPORT + char cSeperator; // is this a unix (/) or windows (\) file system + xbString sLog; // general string for log file activities + sLog = x.GetLogFqFileName().Str(); // get the system default log file name + std::cout << "System default logfile is [" << sLog.Str() << "]" << std::endl; + + cSeperator = sLog.GetPathSeparator(); // get the seperator from + std::cout << "Path seperator = [" << cSeperator << "]" << std::endl; + + sLog.Sprintf( "..%c", cSeperator ); + x.SetLogDirectory( sLog ); + std::cout << "sLog = [" << sLog.Str() << "]\n"; + + sLog = x.GetLogFqFileName().Str(); // get the system default log file name + std::cout << "New logfile is [" << sLog.Str() << "]" << std::endl; + + // turn on logging after file name set + x.EnableMsgLogging(); + #endif // XB_LOGGING_SUPPORT + + // const char *GetErrorMessage( xbInt16 ErrorCode ) const; + // void DisplayError( xbInt16 ErrorCode ) const; + std::cout << "DisplayError( -100 ) - "; + x.DisplayError( -100 ); + // << "]" << std::endl; + + + // void SetDefaultDateFormat( const xbString &sDefaultDateFormat ); + // xbString& GetDefaultDateFormat() const; + std::cout << "GetDefaultDateFormat() - " << x.GetDefaultDateFormat() << std::endl; + + // void SetDataDirectory ( const xbString &sDataDirectory ); + // xbString& GetDataDirectory() const; + std::cout << "GetDataDirectory() - " << x.GetDataDirectory() << std::endl; + + // xbInt16 GetEndianType() const; + if( x.GetEndianType() == 'L' ) + std::cout << "Little Endian Architecture." << std::endl; + else + std::cout << "Bid Endian Architecture." << std::endl; + + //xbBool GetDefaultAutoCommit() const; + //void SetDefaultAutoCommit( xbBool bDefaultAutoCommit ); + if( x.GetDefaultAutoCommit()) + std::cout << "AutoCommit is on." << std::endl; + else + std::cout << "AutoCommit is off." << std::endl; + + //xbBool GetMultiUser () const; + //void SetMultiUser ( xbBool bMultiUser ); + if( x.GetMultiUser()) + std::cout << "Multi user (locking) is enabled." << std::endl; + else + std::cout << "Multi user (locking) not enabled." << std::endl; + + #if defined (XB_NDX_SUPPORT) || defined (XB_MDX_SUPPORT) + // xbInt16 GetUniqueKeyOpt () const; + // xbInt16 SetUniqueKeyOpt ( xbInt16 iUniqueKeyOpt ); + // XB_HALT_ON_DUPKEY + // XB_EMULATE_DBASE + if( x.GetUniqueKeyOpt() == XB_HALT_ON_DUPKEY ) + std::cout << "UniqueKey option - XB_HALT_ON_DUPKEY" << std::endl; + else if( x.GetUniqueKeyOpt() == XB_EMULATE_DBASE ) + std::cout << "UniqueKey option - XB_EMULATE_DBASE" << std::endl; + #endif // (XB_NDX_SUPPORT) || defined (XB_MDX_SUPPORT) + + #ifdef XB_LOCKING_SUPPORT + //xbInt16 GetDefaultLockRetries () const; + //void SetDefaultLockRetries ( xbInt16 iRetryCount ); + //xbInt32 GetDefaultLockWait () const; + //void SetDefaultLockWait ( xbInt32 lRetryWait ); + //xbInt16 GetDefaultLockFlavor () const; + //void SetDefaultLockFlavor ( xbInt16 iLockFlavor ); + //xbBool GetDefaultAutoLock () const; + //void SetDefaultAutoLock ( xbBool bAutoLock ); + //void EnableDefaultAutoLock (); + //void DisableDefaultAutoLock (); + + std::cout << "GetDefaultLockRetries() - " << x.GetDefaultLockRetries() << std::endl; + std::cout << "GetDefaultLockWait() - " << x.GetDefaultLockWait() << std::endl; + std::cout << "GetDefaultAutoLock() - " << x.GetDefaultAutoLock() << std::endl; + #endif // XB_LOCKING_SUPPORT + + #ifdef XB_MDX_SUPPORT + // xbInt16 GetCreateMdxBlockSize() const; + // xbInt16 SetCreateMdxBlockSize( xbInt16 ulBlockSize ); + std::cout << "GetCreateMdxBlockSize() - " << x.GetCreateMdxBlockSize() << std::endl; + #endif // XB_MDX_SUPPORT + + #ifdef XB_BLOCKREAD_SUPPORT + // xbUInt32 GetDefaultBlockReadSize() const; + // void SetDefaultBlockReadSize( xbUInt32 ulDfltBlockReadSize ); + std::cout << "GetDefaultBlockReadSize() - " << x.GetDefaultBlockReadSize() << std::endl; + #endif // XB_BLOCKREAD_SUPPORT + + //xbBool BitSet ( unsigned char c, xbInt16 iBitNo ) const; + //void BitDump ( unsigned char c ) const; + //void BitDump ( char c ) const; + std::cout << "BitDump( 'A' ) - "; + x.BitDump( 'A' ); + + return 0; +} + + +</xmp> + +<br><br> <hr> <p><img src="xbase.jpg"><br><hr> </BODY> diff --git a/docs/html/xbc9.html b/docs/html/xbc9.html index afcd2fa..1d39a96 100755 --- a/docs/html/xbc9.html +++ b/docs/html/xbc9.html @@ -2,179 +2,254 @@ <HTML> <TITLE>Xbase DBMS Chapter 9</TITLE> <BODY BGCOLOR=#FFFFFF> -<H2><p align="center">NTX Indices</p></H2> -<p align="center">Chapter Updated 11/28/22</p><hr> +<H2><p align="center">Class xbXBase</p></H2> +<p align="center">Chapter Updated 04/28/23</p><hr> +<h3>Class xbXBase - Core Level Class</h3> -<h3>This chapter might be out of date. The NTX module is pending review and updates for release 4.x.x</h3> -The objective of this chapter is to provide information regarding the -basic concepts of how .NTX index files work in the Xbase environment.<br><br> +The xbXBase class is the core class that needs to be in every application program. +Established an instance of class xbXBase before any other Xbase calls are made. -The information in this chapter has been gathered by searching the internet -and by examining the structure of known good NTX indexes.<br><br> +<i>xbXBase x</i> -<h4>NTX Index File Characteristics</h4> - -<ul><li>NTX indices maintain keys in ascending sort order only.<br><br> -<li>NTX indices support <em>unique</em> or <em>non unique</em> keys.<br><br> - -<em>Unique</em> keys must be unique. The database update routines will -fail if an attempt to add a non-unique key is performed.<br><br> - -<em>Non-unique</em> 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.<br><br> - -<li>NTX indexes are automatically updated by the Xbase library after the -indices are opened.<br><br> - -<li>Character keys are left justified and padded on the right with spaces.<br><br> - -<li>Numeric keys are stored as eight byte double values.<br><br> - -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. - -</ul> - - -<h4>NTX File Internals</h4> - -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.<br><br> - -The <em>Head Node</em> 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.<br><br> - - -<TABLE BORDER> -<CAPTION ALIGN="TOP"><h3>NTX Header Node</H3></CAPTION> -<TR VALIGN="BASELINE"> -<TR><TH ALIGN="LEFT">Type<TD>Size<TD>Field Name<TD>Description -<TR><TH ALIGN="LEFT">xbShort<TD>2<TD>Signature Byte<TD>The Clipper signature byte. 0x003h indicates Clipper 87. 0x006h indicates Clipper 5.x -<TR><TH ALIGN="LEFT">xbShort<TD>2<TD>Indexing Version Number<TD>Documented as the "Compiler Version" but I have observed an increasing number. Incremented whenever the index is changed. -<TR><TH ALIGN="LEFT">xbLong<TD>4<TD>First Node Offset<TD>The offset to the first node. -<TR><TH ALIGN="LEFT">xbLong<TD>4<TD>First Unused Page Offset<TD>The offset to the first unused node. -<TR><TH ALIGN="LEFT">xbShort<TD>2<TD>Key Size + 8<TD>The Key Size plus 8 bytes. -<TR><TH ALIGN="LEFT">xbShort<TD>2<TD>Key Size<TD>The size (length) of the key. -<TR><TH ALIGN="LEFT">xbShort<TD>2<TD>Number of Decimals<TD>Number of decimal places in key. -<TR><TH ALIGN="LEFT">xbShort<TD>2<TD>Max Items Per Node<TD>The maximum number of key per node. -<TR><TH ALIGN="LEFT">xbShort<TD>2<TD>1/2 The Max Items Per Node<TD>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. -<TR><TH ALIGN="LEFT">char<TD>256<TD>KeyExpression<TD>Key expression string -<TR><TH ALIGN="LEFT">char<TD>1<TD>Unique<TD>Unique indicator<br> - 00 - Not Unique - XB_NON_UNIQUE<br> - 01 - Unique - XB_UNIQUE -<TR><TH ALIGN="LEFT">char<TD>745<TD>Unused<TD>Unused - - -<TR><TH ALIGN="LEFT"><TD>1024<TD><TD>Total bytes in node -</TABLE> <br><br> -The following structure is used by the Xbase NTX routines: -<xmp> +xbXBase is derived from base classes xbTblMgr and xbSsv. +<br><br><br><br> + +<center> +<table border=1> +<tr><th width=40%>Method</th><th>Description</th><th>Category</th></tr> + + +<tr><td>xbInt16 CloseAllTables()</td><td>Close all open tables.</td><td>Table</tr> + +<tr><td>xbInt16 OpenHighestVersion( const xbString &sTableName, const xbString &sAlias, xbDbf &dbf, int dummy )</td><td>Open highest version available for sTableName.</td><td>Table</tr> +<tr><td>xbInt16 OpenHighestVersion( const xbString &sTableName, const xbString &sAlias, xbDbf **dbf )</td><td>Open highest version available for sTableName.</td><td>Table</tr> +<tr><td>xbDbf * Open( const xbString &sTableName, xbInt16 &iRc )</td><td>Open the highest available version of the dbf file. Defaults to XB_READ_WRITE and XB_MULTI_USER mode.</td><td>Table</tr> +<tr><td>xbDbf * Open( const xbString &sTableName, const xbString &sAlias, xbInt16 iOpenMode, xbInt16 iShareMode, xbInt16 iVersion, xbInt16 &iRc )</td><td>Open table.</td><td>Table</tr> + +<tr><td colspan=3><hr></td></tr> +<tr><td>void DisableMsgLogging()</td><td>Disable logging routines.</td><td>Logging</td></tr> +<tr><td>void EnableMsgLogging ()</td><td>Enable logging routines.</td><td>Logging</td></tr> +<tr><td>xbInt16 FlushLog()</td><td>Flush any queued logfile updates to disk.</td><td>Logging</td></tr> +<tr><td>const xbString &GetLogDirectory () const</td><td>Get the current logfile directory.</td><td>Logging</td></tr> +<tr><td>const xbString &GetLogFileName () const</td><td>Get the current logfile name.</td><td>Logging</td></tr> +<tr><td>const xbString &GetLogFqFileName() const</td><td>Get fully qualified logfile name.</td><td>Logging</td></tr> +<tr><td>xbBool GetLogStatus () const</td><td>Get the logging status.</td><td>Logging</td></tr> +<tr><td>void SetLogDirectory( const xbString &sLogFileDirectory )</td><td>Set the log directory. Must be done while logging is off.</td><td>Logging</td></tr> +<tr><td>void SetLogFileName( const xbString &sLogFileName )</td><td>Set the log file name. Must be done while logging is off.</td><td>Logging</td></tr> +<tr><td>void SetLogSize( size_t lSize )</td><td>Set the logfile size. After the size is reached, the log file roll.</td><td>Logging</td></tr> +<tr><td>xbInt16 WriteLogBytes ( xbUInt32 lCnt, const char *p )</td><td>Write lCnt bytes pointed to by pointer p to the logfile.</td><td>Logging</td></tr> +<tr><td>xbInt16 WriteLogMessage( const xbString &sLogMessage, xbInt16 iOutputOpt = 0 )</td><td>Write a string to the logfile.</td><td>Logging</td></tr> + +<tr><td colspan=3><hr></td></tr> + +<tr><td>xbInt16 xbXBase::CreateFqn( const xbString &sDirIn, const xbString &sNameIn, const xbString &sExtIn, xbString &sFqnOut )</td> +<td>Create fully qualified file name from directory, file name and optional extension. This routine sets the correct separators dependent on OS. +</td><td>Misc</td></tr> + + +<tr><td>xbInt16 xbXBase::GetCmdLineOpt( xbInt32 lArgc, char **sArgv, xbString &sOptRqst, xbString &sParmOut )<br> +xbXBase::GetCmdLineOpt( xbInt32 lArgc, char **sArgv, const char *sOptRqst, xbString &sParmOut )</td><td>Parse command line values seeking given parameter info.</td><td>Misc</td></tr> + +<tr><td>void xbSleep( xbInt32 lMillisecs )</td><td>Sleep command, used mainly in lock commands for waiting between retries.</td><td>Misc</td></td></tr> + +<tr><td colspan=3><hr></td></tr> +<tr><td>xbInt16 ABS( xbDouble dIn, xbDouble &dOut )</td><td>Dbase ABS function.</td><td>Expression</td></tr> +<tr><td>xbInt16 ALLTRIM( const xbString &sIn, xbString &sOut )</td><td>Dbase ALLTRIM function.</td><td>Expression</td></tr> +<tr><td>xbInt16 ASC( const xbString &s, xbDouble &dAscOut )</td><td>Dbase ASC function.</td><td>Expression</td></tr> +<tr><td>xbInt16 AT( const xbString &sSrchFor, const xbString &sBase, xbDouble &dPos )</td><td>Dbase AT function.</td><td>Expression</td></tr> +<tr><td>xbInt16 CDOW( xbDate &dInDate, xbString &sOutDow )</td><td>Dbase CDOW function.</td><td>Expression</td></tr> +<tr><td>xbInt16 CHR( xbDouble dAsciCd, xbString &sOut )</td><td>Dbase CHR function.</td><td>Expression</td></tr> +<tr><td>xbInt16 CMONTH( xbDate &dInDate, xbString &sOutMonth )</td><td>Dbase CMONTH function.</td><td>Expression</td></tr> +<tr><td>xbInt16 CTOD( const xbString &sInDate, xbDate &dOutDate )</td><td>Dbase CTOD function.</td><td>Expression</td></tr> +<tr><td>xbInt16 DATE( xbDate &dOutDate )</td><td>Dbase DATE function.</td><td>Expression</td></tr> +<tr><td>xbInt16 DAY( const xbDate &dInDate, xbDouble &dOutDay )</td><td>Dbase DAY function.</td><td>Expression</td></tr> +<tr><td>xbInt16 DEL( xbDbf * d, xbString &sOut, xbInt16 iRecBufSw = 0 )</td><td>Dbase DEL function.</td><td>Expression</td></tr> +<tr><td>xbInt16 DELETED( xbDbf * d, xbBool &bOut, xbInt16 iRecBufSw = 0 )</td><td>Dbase DELETED function.</td><td>Expression</td></tr> +<tr><td>xbInt16 DESCEND( const xbString &sIn,xbString &sOut )<br>xbInt16 DESCEND( const xbDate &dInDate, xbDate &dOutDate )<br>xbInt16 DESCEND( const xbDouble dIn, xbDouble &dsOut )</td><td>Dbase DESCEND function.</td><td>Expression</td></tr> +<tr><td>xbInt16 DOW( const xbDate &sInDate, xbDouble &dDowOut )</td><td>Dbase DOW function.</td><td>Expression</td></tr> +<tr><td>xbInt16 DTOC( xbDate &dInDate, xbString &sOutFmtDate )</td><td>Dbase DTOC function.</td><td>Expression</td></tr> +<tr><td>xbInt16 DTOS( xbDate &dInDate, xbString &sOutFmtDate )</td><td>Dbase DTOS function.</td><td>Expression</td></tr> +<tr><td>xbInt16 EXP( xbDouble dIn, xbDouble &dOut )</td><td>Dbase EXP function.</td><td>Expression</td></tr> +<tr><td>xbInt16 IIF( xbBool bResult, const xbString &sTrueResult, const xbString &sFalseResult, xbString &sResult )</td><td>Dbase IIF function.</td><td>Expression</td></tr> +<tr><td>xbInt16 INT( xbDouble dIn, xbDouble &dOut )</td><td>Dbase INT function.</td><td>Expression</td></tr> +<tr><td>xbInt16 ISALPHA( const xbString &s, xbBool &bResult )</td><td>Dbase ISALPHA function.</td><td>Expression</td></tr> +<tr><td>xbInt16 ISLOWER( const xbString &s, xbBool &bResult )</td><td>Dbase ISLOWER function.</td><td>Expression</td></tr> +<tr><td>xbInt16 ISUPPER( const xbString &s, xbBool &bResult )</td><td>Dbase ISUPPER function.</td><td>Expression</td></tr> +<tr><td>xbInt16 LEFT( const xbString &sIn, xbUInt32 lCharCnt, xbString &sOut )</td><td>Dbase LEF function.</td><td>Expression</td></tr> +<tr><td>xbInt16 LEN( const xbString &sIn, xbDouble &dLen )</td><td>Dbase LEN function.</td><td>Expression</td></tr> +<tr><td>xbInt16 LOG( xbDouble dIn, xbDouble &dOut )</td><td>Dbase LOG function.</td><td>Expression</td></tr> +<tr><td>xbInt16 LOWER( const xbString &sIn, xbString &sOut )</td><td>Dbase LOWER function.</td><td>Expression</td></tr> +<tr><td>xbInt16 LTRIM( const xbString &sIn, xbString & sOut )</td><td>Dbase LTRIM function.</td><td>Expression</td></tr> +<tr><td>xbInt16 MAX( xbDouble dIn1, xbDouble dIn2, xbDouble &dOut )</td><td>Dbase MAX function.</td><td>Expression</td></tr> +<tr><td>xbInt16 MIN( xbDouble dIn1, xbDouble dIn2, xbDouble &dOut )</td><td>Dbase MIN function.</td><td>Expression</td></tr> +<tr><td>xbInt16 MONTH( xbDate &dInDate, xbDouble &dMonthOut )</td><td>Dbase MONTH function.</td><td>Expression</td></tr> +<tr><td>xbInt16 RECCOUNT( xbDbf * d, xbDouble &dRecOut )</td><td>Dbase RECCOUNT function.</td><td>Expression</td></tr> +<tr><td>xbInt16 RECNO( xbDbf * d, xbDouble &dRecOut )</td><td>Dbase RECNO function.</td><td>Expression</td></tr> +<tr><td>xbInt16 REPLICATE( const xbString &sIn, xbUInt32 ulRepCnt, xbString &sOut )</td><td>Dbase REPLICATE function.</td><td>Expression</td></tr> +<tr><td>xbInt16 RIGHT( const xbString &sIn, xbUInt32 iCharCnt, xbString &sOut )</td><td>Dbase RIGHT function.</td><td>Expression</td></tr> +<tr><td>xbInt16 RTRIM( const xbString &sIn, xbString &sOut )</td><td>Dbase RTRIM function.</td><td>Expression</td></tr> +<tr><td>xbInt16 SPACE( xbInt32 lCnt, xbString &sOut )</td><td>Dbase SPACE function.</td><td>Expression</td></tr> +<tr><td>xbInt16 SQRT( xbDouble dBase, xbDouble &dSqrRt )</td><td>Dbase SQRT function.</td><td>Expression</td></tr> +<tr><td>xbInt16 STOD( const xbString &sIn, xbDate &sDateOut )</td><td>Dbase STOD function.</td><td>Expression</td></tr> +<tr><td>xbInt16 STR( xbDouble dIn, xbString &sOut )</td><td>Dbase function.</td><td>Expression</td></tr> +<tr><td>xbInt16 STR( xbDouble dIn, xbUInt32 ulLen, xbString &sOut )<br> + xbInt16 STR( xbDouble dIn, xbUInt32 ulLen, xbUInt32 ulDec, xbString &sOut )<br> + xbInt16 STR( xbDouble dIn, xbUInt32 ulLen, xbUInt32 ulDec, xbString &sPadChar, xbString &sOut )</td><td>Dbase STR function.</td><td>Expression</td></tr> +<tr><td>xbInt16 STRZERO( xbDouble dIn, xbUInt32 ulLen, xbUInt32 ulDec, xbString &sOut )</td><td>Dbase STRZERO function.</td><td>Expression</td></tr> +<tr><td>xbInt16 SUBSTR( const xbString &sIn, xbUInt32 ulStartPos, xbUInt32 ulLen, xbString &sOut )</td><td>Dbase SUBSTR function.</td><td>Expression</td></tr> +<tr><td>xbInt16 TRIM( const xbString &sIn, xbString &sOut )</td><td>Dbase TRIM function.</td><td>Expression</td></tr> +<tr><td>xbInt16 UPPER( const xbString &sIn, xbString &sOut )</td><td>Dbase UPPER function.</td><td>Expression</td></tr> +<tr><td>xbInt16 VAL( const xbString &sIn, xbDouble &dOut )</td><td>Dbase VAL function.</td><td>Expression</td></tr> +<tr><td>xbInt16 YEAR( xbDate &dInDate, xbDouble &dOutYear )</td><td>Dbase YEAR function.</td><td>Expression</td></tr> +</table> -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]; -}; +<br><br> +<hr> -</xmp> +<h3>Example program using xbXbase methods</h3> +</center> +<xmp> +/* xb_ex_ssv.cpp +XBase64 Software Library -<br><br> +Copyright (c) 1997,2003,2014,2021,2022,2023 Gary A Kunkel + +The xb64 software library is covered under the terms of the GPL Version 3, 2007 license. + +Email Contact: + + XDB-devel@lists.sourceforge.net + XDB-users@lists.sourceforge.net + +This program demonstrates using functionality of the xbSsv class (Shared system values) + +*/ + +#include "xbase.h" + +using namespace xb; + +int main( int ac, char ** av ){ + + xbXBase x; // set up xbase for business + xbString sMsg; // a message string + + sMsg.Sprintf( "Program [%s] initializing...", av[0] ); + std::cout << sMsg.Str() << std::endl; + + // example code to set up log file usage + #ifdef XB_LOGGING_SUPPORT + char cSeperator; // is this a unix (/) or windows (\) file system + xbString sLog; // general string for log file activities + sLog = x.GetLogFqFileName().Str(); // get the system default log file name + std::cout << "System default logfile is [" << sLog.Str() << "]" << std::endl; + + cSeperator = sLog.GetPathSeparator(); // get the seperator from + std::cout << "Path seperator = [" << cSeperator << "]" << std::endl; + + sLog.Sprintf( "..%c", cSeperator ); + x.SetLogDirectory( sLog ); + std::cout << "sLog = [" << sLog.Str() << "]\n"; + + sLog = x.GetLogFqFileName().Str(); // get the system default log file name + std::cout << "New logfile is [" << sLog.Str() << "]" << std::endl; + + // turn on logging after file name set + x.EnableMsgLogging(); + #endif // XB_LOGGING_SUPPORT + + // const char *GetErrorMessage( xbInt16 ErrorCode ) const; + // void DisplayError( xbInt16 ErrorCode ) const; + std::cout << "DisplayError( -100 ) - "; + x.DisplayError( -100 ); + // << "]" << std::endl; + + + // void SetDefaultDateFormat( const xbString &sDefaultDateFormat ); + // xbString& GetDefaultDateFormat() const; + std::cout << "GetDefaultDateFormat() - " << x.GetDefaultDateFormat() << std::endl; + + // void SetDataDirectory ( const xbString &sDataDirectory ); + // xbString& GetDataDirectory() const; + std::cout << "GetDataDirectory() - " << x.GetDataDirectory() << std::endl; + + // xbInt16 GetEndianType() const; + if( x.GetEndianType() == 'L' ) + std::cout << "Little Endian Architecture." << std::endl; + else + std::cout << "Bid Endian Architecture." << std::endl; + + //xbBool GetDefaultAutoCommit() const; + //void SetDefaultAutoCommit( xbBool bDefaultAutoCommit ); + if( x.GetDefaultAutoCommit()) + std::cout << "AutoCommit is on." << std::endl; + else + std::cout << "AutoCommit is off." << std::endl; + + //xbBool GetMultiUser () const; + //void SetMultiUser ( xbBool bMultiUser ); + if( x.GetMultiUser()) + std::cout << "Multi user (locking) is enabled." << std::endl; + else + std::cout << "Multi user (locking) not enabled." << std::endl; + + #if defined (XB_NDX_SUPPORT) || defined (XB_MDX_SUPPORT) + // xbInt16 GetUniqueKeyOpt () const; + // xbInt16 SetUniqueKeyOpt ( xbInt16 iUniqueKeyOpt ); + // XB_HALT_ON_DUPKEY + // XB_EMULATE_DBASE + if( x.GetUniqueKeyOpt() == XB_HALT_ON_DUPKEY ) + std::cout << "UniqueKey option - XB_HALT_ON_DUPKEY" << std::endl; + else if( x.GetUniqueKeyOpt() == XB_EMULATE_DBASE ) + std::cout << "UniqueKey option - XB_EMULATE_DBASE" << std::endl; + #endif // (XB_NDX_SUPPORT) || defined (XB_MDX_SUPPORT) + + #ifdef XB_LOCKING_SUPPORT + //xbInt16 GetDefaultLockRetries () const; + //void SetDefaultLockRetries ( xbInt16 iRetryCount ); + //xbInt32 GetDefaultLockWait () const; + //void SetDefaultLockWait ( xbInt32 lRetryWait ); + //xbInt16 GetDefaultLockFlavor () const; + //void SetDefaultLockFlavor ( xbInt16 iLockFlavor ); + //xbBool GetDefaultAutoLock () const; + //void SetDefaultAutoLock ( xbBool bAutoLock ); + //void EnableDefaultAutoLock (); + //void DisableDefaultAutoLock (); + + std::cout << "GetDefaultLockRetries() - " << x.GetDefaultLockRetries() << std::endl; + std::cout << "GetDefaultLockWait() - " << x.GetDefaultLockWait() << std::endl; + std::cout << "GetDefaultAutoLock() - " << x.GetDefaultAutoLock() << std::endl; + #endif // XB_LOCKING_SUPPORT + + #ifdef XB_MDX_SUPPORT + // xbInt16 GetCreateMdxBlockSize() const; + // xbInt16 SetCreateMdxBlockSize( xbInt16 ulBlockSize ); + std::cout << "GetCreateMdxBlockSize() - " << x.GetCreateMdxBlockSize() << std::endl; + #endif // XB_MDX_SUPPORT + + #ifdef XB_BLOCKREAD_SUPPORT + // xbUInt32 GetDefaultBlockReadSize() const; + // void SetDefaultBlockReadSize( xbUInt32 ulDfltBlockReadSize ); + std::cout << "GetDefaultBlockReadSize() - " << x.GetDefaultBlockReadSize() << std::endl; + #endif // XB_BLOCKREAD_SUPPORT + + //xbBool BitSet ( unsigned char c, xbInt16 iBitNo ) const; + //void BitDump ( unsigned char c ) const; + //void BitDump ( char c ) const; + std::cout << "BitDump( 'A' ) - "; + x.BitDump( 'A' ); + + return 0; +} -<h4>Interior and Leaf Nodes</h4> - -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. <br><br> - -Leaf nodes have 0 in the LeftNodeNo field.<br><br> - - -<TABLE BORDER> -<CAPTION ALIGN="TOP"><h3>NTX Interior Node and Leaf Node Structure</H3></CAPTION> -<TR VALIGN="BASELINE"> -<TR><TH ALIGN="LEFT">Type<TD>Size<TD>Field Name<TD>Description -<TR><TH ALIGN="LEFT">xbShort<TD>2<TD>NoOfKeysThisNode<TD>The number of key values in this node. (N) -<TR><TH ALIGN="LEFT">Array of xbUShort<TD>2<TD>offsets[]<TD>Array of - <pre>HeadNode.KeysPerNode +1</pre> unsigned longs. - These values are the offsets (in bytes) of each key - in this node, from the beginning of the node. -<TR><TH ALIGN="LEFT">char<TD>variable<TD>KeyRecs<TD>A repeating structure of - pointers and keys. See the next table for the KeyRec structure. -</TABLE> -<br><br> -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. - -<BR> -<TABLE BORDER> -<CAPTION ALIGN="TOP"><h3>KeyRec Structure</H3></CAPTION> -<TR VALIGN="BASELINE"> -<TR><TH ALIGN="LEFT">Type<TD>Size<TD>Field Name<TD>Description -<TR><TH ALIGN="LEFT">xbLong<TD>4<TD>LeftNodeNo<TD>The node number (offset from beginning of file) of the lower node - for this key. 0 in Leaf Nodes. -<TR><TH ALIGN="LEFT">xbLong<TD>4<TD>DbfRecNo<TD>The DBF record number for this key. - 0 in Interior Nodes. -<TR><TH ALIGN="LEFT">char<TD>KeyLen<TD>KeyValue<TD>The key value. -</TABLE> +</xmp> <br><br> -For those interested in knowing how the Xbase DBMS manipulates and -navigates index files, the following discussion may be helpfull.<br><br> - -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. - <hr> -<A HREF="mailto:bob@#synxis.com"> -Author: Bob Cotton - bob@synxis.com</A><br> <p><img src="xbase.jpg"><br><hr> </BODY> </HTML> |
