Expression Handling

Chapter Updated 11/21/23

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.