From bfa452a375ea0a0a3f95304a69186936567e5263 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=B6rg=20Frings-F=C3=BCrst?= Date: Mon, 14 Aug 2023 19:45:36 +0200 Subject: New upstream version 4.1.4 --- docs/html/xbc5.html | 208 ---------------------------------------------------- 1 file changed, 208 deletions(-) delete mode 100755 docs/html/xbc5.html (limited to 'docs/html/xbc5.html') diff --git a/docs/html/xbc5.html b/docs/html/xbc5.html deleted file mode 100755 index 9708b17..0000000 --- a/docs/html/xbc5.html +++ /dev/null @@ -1,208 +0,0 @@ - - -Xbase DBMS Chapter 5 - -

Expression Handling

Chapter Updated 12/26/22

- -

Overview

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

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

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

- -

Internal fuctioning

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

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

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

Expression Return Types

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

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

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

- - - - - - -

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

- -

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

-

Expression Functions

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

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

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

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

- -

-

Expression Components

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

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

-

Expression Literals

- - - - - - -

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

- -

-

Expression Operators

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

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

- -

-

Example Expressions

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

LNAME + ", " + FNAME -

STARTDT + 90 -

DATE() - 7 -

YEAR( TODAY() ) -

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

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

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

.NOT. DELETED() -

- - -

Example program

-For an example on how to use the expression logic, see program -src/examples/xb_ex_expression.cpp. -

- -

- - -- cgit v1.2.3 From c894a7cdd8686ea695602a23a511a3f1b0d047be Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=B6rg=20Frings-F=C3=BCrst?= Date: Mon, 14 Aug 2023 21:07:46 +0200 Subject: New upstream version 4.1.4 --- docs/html/xbc5.html | 437 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 437 insertions(+) create mode 100755 docs/html/xbc5.html (limited to 'docs/html/xbc5.html') diff --git a/docs/html/xbc5.html b/docs/html/xbc5.html new file mode 100755 index 0000000..66b0f62 --- /dev/null +++ b/docs/html/xbc5.html @@ -0,0 +1,437 @@ + + +Xbase DBMS Chapter 5 + +

Index Overview

Chapter Updated 04/29/23

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

+ + +

Overview

+ +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. + +

+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. + + +

Index processing design

+ +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. + + + +

Index updates

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

+

Index File Types

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

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

+ +

+

Index/Tag Methods

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

Method	Description
xbInt16 xbDbf::CheckTagIntegrity( xbInt16 iTagOpt, xbInt16 iOutputOpt ) +	Checks a tag for missing or duplicate entries. Available if XB_DEBUG_SUPPORT is on.
xbInt16 xbDbf::CloseIndexFile( xbIx *pIx ) +	Close an index file. Indices are automatically closed when the table is closed. + Not typically called in an application program.
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 ); +	Create a new tag.
xbInt16 xbDbf::DeleteTag( const xbString &sIxType, const xbString &sName ) +	Delete existing tag.
xbInt16 xbDbf::Find( xbString &sKey ) xbInt16 xbDbf::Find( xbDate &dtKey ) xbInt16 xbDbf::Find( xbDouble &dKey ) +	Find key value for the active tag.
xbIx * xbDbf::GetCurIx() const +	Returns a pointer to the current index object.
xbString & xbDbf::GetCurIxType() const +	Returns the current index type.
void * xbDbf::GetCurTag() const +	Retrieve pointer to the current active tag.
const xbString & xbDbf::GetCurTagName() const +	Returns the current tag name.
xbInt16 xbDbf::GetFirstKey() +	Retrieve the first key for the active tag.
xbIxList * xbDbf::GetIxList() const +	Returns a pointer to the list of active indices. +
xbInt16 xbDbf::GetLastKey() +	Retrieve the last key for the active tag.
xbInt16 xbDbf::GetNextKey() +	Retrieve the next key for the active tag.
xbInt32 xbDbf::GetPhysicalIxCnt() const +	Returns count of number of physical files opened for DBF table.
xbInt16 xbDbf::GetPrevKey() +	Retrieve the previous key for the active tag.
xbLinkListNode * xbDbf::GetTagList() const +	Returns pointer to linked list of open tags for the DBF file/table.
xbInt16 xbDbf::OpenIndex( const xbString &sIxType, const xbString &sIndexName ) +	Open an index file. Only used for index files that aren't automatically opened.
xbInt16 xbDbf::Reindex( xbInt16 iTagOpt ) +	Rebuild a tag. Available if XB_DEBUG_SUPPORT is on.
xbInt16 xbDbf::SetCurTag( const xbString &sTagName ) + void xbDbf::SetCurTag( const xbString &sIxType, xbIx pIx, void vpTag ) +	Set current tag.

+

+ + +

Internal Data Storage

+ + + + + + + +

Type	Stored in DBF as	Stored in NDX as	Stored in MDX as
C	Character data	Character data	Character data
F	Text numbers	xbDouble	xbBcd
N	Text numbers	xbDouble	xbBcd
D	Text YYYYMMDD	xbDouble Julian	xbDouble Julian

+

+ +

NDX Indices

+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.

+ +

NDX Index File Characteristics

+ +

NDX indices maintain keys in ascending sort order only.

+

NDX indices support unique or non unique keys.

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

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

+ +

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

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

Numeric keys are stored as eight byte double values.
+

Date kets are stored as julian eigth byte double values.
+ +

NDX File Internals

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

+ +

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

+ + + + + +

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

+

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

+ +

Interior and Leaf Nodes

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

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

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

+ + + + + +

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

+

+ + + +

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

+ +

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

+ +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. +

+

+ +

MDX Indices

+The objective of this section is to provide information regarding the +basic concepts of how .MDX index files work in the Xbase64 library.
+Information for MDX files has been gathered by searching the internet +and by examining the structure of known good MDX index files.

+ +

MDX Index File Characteristics

+ +

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

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

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

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

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

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

MDX indices support unique or non unique keys.

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

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

+ + +

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

Numeric keys are stored as twelve byte BCD values. +

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

MDX File Internals

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

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

+ +The first four pages contain: +

Bytes 0 - 543 contain general file information. +

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

+ +Pages five and beyound: +

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

+ +

Interior and Leaf Nodes

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

+ +

+

+

TDX Indices

+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.

+ +TDX files are built on the MDX index logic and supports the following functionality: +

Complex Key Expressions +

Filters +

Unique / Non-unique keys +

Ascending / Descending keys +

Max of 47 unique temporary index tags +

+ +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.

+ +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. +

+ +

+ + -- cgit v1.2.3

Expression Handling

Overview

Internal fuctioning

Expression Return Types

Expression Functions

Expression Components

Expression Literals

Expression Operators

Example Expressions

Example program

Index Overview

Overview

Tags

Index processing design

Index updates

Index File Types

Index/Tag Methods

Internal Data Storage

NDX Indices

NDX Index File Characteristics

NDX File Internals

NDX Header Node

Interior and Leaf Nodes

NDX Interior Node and Leaf Node Structure

KeyRec Structure

MDX Indices

MDX Index File Characteristics

MDX File Internals

Interior and Leaf Nodes

TDX Indices