Expression Handling

Chapter Updated 07/06/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 version 3 through 12 and Clipper 5.

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 base type of CHAR, NUMERIC, DATE, LOGICAL or TIMESTAMP.

An expression return type can be determined with method xbExp::GetReturnType after parsing it.

Beginning with release 4.2.8 there is also a subtype which can be accessed with method xbExp::GetSubType(). For NUMERIC base types, the sub type will be one of XB_EXP_FLOAT, XB_EXP_LONG, XB_EXP_AUTOINCREMENT or XB_EXP_TIME.

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
TIMESTAMP	xbTimeStamp

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.

Function Name	Return Type	Parameters	Description
ABS( num )	N	Field name, numeric value or numeric expression	Calculate absolute value of a numeric expression.
ACOS( num )	N	Field name, numeric value or numeric expression	Calculate the inverse cosine (arccosine) of a number in radians.
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.
ASIN( num )	N	Field name, numeric value or numeric expression	Calculate the inverse sine (arcsine) of a number in radians.
AT( needle, haystack )	N	Field names or string	Return starting position of a string within a string. Returns 0 if not found.
ATAN( num )	N	Field name, numeric value or numeric expression	Return inverse tangent (arctangent) of a number in radians.
ATN2( numSine, numCosine )	N	Field names, numerivc values or numeric expressions	Return inverse tangent (arctanget) of a given point.
CDOW( date )	C	Date field or date expression ie; STOD( "YYYYMMDD" )	Retun character weekday name for a date.
CEILING( num )	N	Field name, numeric value or numeric expression	Round up to nearest integer value.
CENTER( string, num, char)	C	String Expression, new size of centered string, pad character	Return a centered string.
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.
COS( num )	N	Field name, numeric value or numeric expression	Calculate the cosine of an angle in radians.
CTOD( mm/dd/yy )	D	String date in mm/dd/yy format	Convert mm/dd/yy date to a yyyymmdd date.
CTODT( time stamp )	N,TS	One of: MM/DD/YY HH:MM:SS YYYY-MM-DD HH:MM:SS MM/DD/YY HH:MM YYYY-MM-DD HH:MM. MM/DD/YY YYYY-MM-DD HH:MM:SS HH:MM	Convert string to time stamp.
CTOT( time )	N	One of: HH:MM:SS HH:MM	Convert string to time.
DATE()	D	None	Return system date.
DATETIME()	N,TS	None	Return current system date and time as time stamp.
DAY( date )	N	Date field or date expression	Return the day of the month from a date.
DBF()	C	None	Returns the current database file name.
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.
DTODT( date )	N,TS	Date field or date expression	Return a time stamp field from a date input field.
DTOR( num )	N	Degrees	Return radian value of an angle from degrees input.
DTOS( date )	C	Date field or date expression	Return character CCYYMMDD date from input date.
DTTOD( TimeStamp )	N	TimeStamp	TimeStamp to Date.
DTTOT( TimeStamp )	N	TimeStamp	Timestamp to Time.
ELAPSED( time, time ) ELAPSED( string, string )	N	time values	Return difference between two times in seconds.
EMPTY( string )	L	String expression	Returns true if string expression is empty, else returns false.
EXP( num )	N	Field name, numeric value or numeric expression	Return exponent value.
FCOUNT()	N	None	Returns number of fields in current DBF file.
FIELD( num )	N	Field number, first field is 1	Return field name for given field number.
FLDCOUNT()	N	None	Returns number of fields in current DBF file.
FLOOR( num )	N	Field name, numeric value or numeric expression	Round down to nearest integer value.
HTOI( string )	N	None	Hex to integer conversion.
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.
ISBLANK( string )	L	String expression	Check if empty or null.
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.
ITOH( num )	C	Numeric expression	Integer to hex conversion.
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.
LOG10( num )	N	Field name, numeric value or numeric expression	Calculate base 10 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.
MOD( num, num )	N	Field names, numbers or numeric expressions	Return modulus 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.
SECONDS()	N	None	Seconds since midnight (local time).
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}
TIMESTAMP	"CCYY-MM-DD HH:MM:SS
TIME	"HH:MM:SS"

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

Adding New Functions

To add a new function, find a function that is similar to what you need to use as an example and take the following steps.

Add entry to structure xbFuncInfo in the src/include/xbxbase.h file.
Add a method prototype in class xbXBase in the src/include/xbxbase.h file.
Build out the actual function, include in the src/core/xbfuncs.cpp file.
Add a testing routine in the src/test/xb_test_funcs.cpp file.
Update method xbInt16 xbExp::ProcessExpressionFunction() found in the src/core/xbexp.cpp file.
Add a testing routine in the src/test/xb_test_expression.cpp file.
Submit the code updates to the XDB-devel@lists.sourceforge.net mailing list for inclusion in the library.

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.