Expression Handling

Chapter Updated 2/9/26

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	Parameters	Description
ABS( num )	N	Field name, numeric value or numeric expression	Calculate absolute value of a numeric expression.
ALLTRIM( string )	C	Field name, string or string expression	Trim leading and trailing whitespace from a string.
ASC( string )	N	Field name, string or string expression	Return ASCII code for first character in a string.
AT( needle, haystack )	N	Field names or string	Return starting position of a string within a string. Returns 0 if not found.
CDOW( date )	C	Date field or date expression ie; STOD( "YYYYMMDD" )	Retun character weekday name for a date.
CHR( int )	C	Integer value or field.	Convert numeric expression to a character.
CMONTH( date )	C	Date field or date expression	Return month name for a date
CTOD( mm/dd/yy )	D	String date in mm/dd/yy format	Convert mm/dd/yy date to a yyyymmdd date.
DATE()	D	None	Return system date.
DAY( date )	N	Date field or date expression	Return the day of the month from a date.
DEL()	C	None	Return record deletion status for a record.
DELETED()	L	None	Return record deletion status for a record.
DESCEND( expression )	1	Valid expression	Clipper DESCEND function. Creates a compliment of the input expression. Originally used for index tags that don't support descending keys.
DOW( date )	N	Date field or date expression	Return number of day of week
DTOC( date )	C	Date field or date expression	Return character date from input date
DTOS( date )	C	Date field or date expression	Return character CCYYMMDD date from input date
EXP( num )	N	Field name, numeric value or numeric expression	Return exponent value
IIF( Evaluation Expression, True Result Response, False Result Response )	C	Valid expression input, equal length true and false values	Immediate If
INT( num )	N	Number	Convert number to integer, truncate any decimals
ISALPHA( string )	L	String expression	Check if string begins with alpha character
ISLOWER( string )	L	String expression	Check if string begins with lower case alpha character
ISNULL( field name )	L	Field name	Check if a database field is null
ISUPPER( string )	L	String expression	Check if string begins with upper case character
LEFT(string, count )	C	Field name, string or string expression, number chars to extract from the left	Return left characters from a string
LEN( string )	N	Field name, string or string expression	Return length of string
LOG( num )	N	Field name, numeric value or numeric expression	Calculate logarithm
LOWER( string )	C	Field name, string or string expression	Convert upper case to lower case
LTRIM( string )	C	Field name, string or string expression	Trim white space from left side of a string
MAX( num, num )	N	Field names, numbers or numeric expressions	Return higher of two values
MIN( num, num )	N	Field names, numbers or numeric expressions	Return lesser of two values
MONTH( date )	N	Date field or date expression	Return number of month for a given date
RECNO()	N	None	Return current rec number for a given table
RECCOUNT()	N	None	Return number of records in a given table
REPLICATE( string, num )	C	String expression, numeric expression	Repeat character expression N times
RIGHT( string, num )	C	String expression, numeric expression	Return right characters from as string
RTRIM( string )	C	String expression	Trim white space from right side of string
SPACE( num )	C	Numeric expression	Generate a string of N spaces
SQRT( num )	N	Numeric expression	Calculate square root
STOD( string )	D	String expression in yyyymmdd format	Convert 8 byte CCYYMMDD date to date
STR( num ) STR( num, len ) STR( num, len, dec )	C	Numeric expression, optional length, optional decimal	Convert number to character string
STRZERO( num ) STRZERO( num, len ) STRZERO( num, len, dec )	C	Numeric expression, optional length, optional decimal	Convert number to character string with leading zeroes.
SUBSTR( string, startpos, len )	C	String expression, starting position, optional length	Extract portion of one string from another string
TRIM( string )	C	Strng expression	Trim white space from left and right sides of a string.
UPPER( string )	C	String expression	Convert lower case to upper case
VAL( string )	N	String expression	Convert numeric characters to number
YEAR( date )	N	Date field or date expression	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	Description
Parens	()	12		Sets precedence
Numeric Operator	+ (unary)	11	N	Numeric unary
Numeric Operator	- (unary)	11	N	Numeric unary
Numeric Operator	--X	10	N	Numeric pre-decrement
Numeric Operator	++X	10	N	Numeric pre-increment
Numeric Operator	**	9	N	Numeric exponentiation
Numeric Operator	^	9	N	Same as **, exponentiation
Numeric Operator	%	8	N	Modulus (Remainder)
Numeric Operator	*	8	N	Numeric multiplication
Numeric Operator	/	8	N	Numeric division
Numeric Operator	+ Addition	7	N	Numeric addition
Numeric Operator	- Subtraction	7	N	Numeric subtraction
Numeric Operator	X--	6	N	Numeric post-decrement
Numeric Operator	X++	6	N	Numeric post-increment
String Operator	+	5	C	Concatonate 1
String Operator	-	5	C	Concatonate 2
Relational Operator	=	4	L	Equals operator
Relational Operator	#, <>, !=	4	L	Not equals operators
Relational Operator	<	4	L	Less than operator
Relational Operator	>	4	L	Greater than operator
Relational Operator	<=	4	L	Less than or equal oerator
Relational Operator	>=	4	L	Greater than or equal operator
Relational Operator	$	4	L	Contains operator
Relational Operator	==			Clipper operator, not implemented yet
Logical Operator	NOT	3	L	Logical NOT
Logical Operator	.NOT.	3	L	Logicial NOT
Logical Operator	AND	2	L	Logical AND
Logical Operator	.AND.	2	L	Logical AND
Logical Operator	OR	1	L	Logical OR
Logical Operator	.OR.	1	L	Logical OR

Example Expressions

FieldName

"SomeText"

'SomeText'

27.4

{01/03/1988}

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

LNAME + ", " + FNAME

STARTDT + 90

DATE() - 7

YEAR( DATE() )

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.