Expression Handling

Chapter Updated 04/28/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 TypeXBase Type
CHARxbString
NUMERICxbDouble
DATExbDate
LOGICALxbBool


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 NameReturn TypeDescription
ABSNCalculate absolute value of numeric expression
ALLTRIMCTrim leading andtrailing whitespace from a string
ASCNReturn ASCII code for first character in a string
ATNReturn starting position of a string within a string
CDOWCRetun character weekday name for a date
CHRCConvert numeric expression to a character
CMONTHCReturn month name for a date
CTODDReturn date from a character date input
DATEDReturn system date
DAYNReturn the day of the month from a date
DELCReturn record deletion status for a record
DELETEDLReturn record deletion status for a record<
DESCEND1Clipper DESCEND function
DOWNReturn number of day of week
DTOCCReturn character date from input date
DTOSCReturn character CCYYMMDD date from input date
EXPNReturn exponent value
IIFCImmediate If
INTNConvert number to integer, truncate any decimals
ISALPHALCheck if string begins with alpha character
ISLOWERLCheck if string begins with lower case alpha character
ISUPPERLCheck if string begins with upper case character
LEFTCReturn left characters from a string
LENNReturn lenght of string
LOGNCalculate logarithm
LOWERCConvert upper case to lower case
LTRIMCTrim left side of a string
MAXNReturn higher of two values
MINNReturn lesser of two values
MONTHNReturn number of month for a given date
RECNONReturn current rec number for a given table
RECCOUNTNReturn number of records in a given table
REPLICATECRepeat character expression N times
RIGHTCReturn right characters from as tring
RTRIMCTrim right side of string
SPACECGenerate a string of N spaces
SQRTNCalculate square root
STODDConvert 8 byte CCYYMMDD date to date
STRCConvert number to character string
STRZEROCConvert number to character string with leading zeroes. Clipper Function.
SUBSTRCExtract portion oif one string from another string
TRIMCTrim left and right sides of a string
UPPERCConver lower case to upper case
VALNConvert numeric characters to number
YEARNReturn 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

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


Expression Operators

TypeOperatorPrecedenceResultNotes
Parens()12
Numeric Operator+ (unary)11N
Numeric Operator- (unary)11N
Numeric Operator--X10N
Numeric Operator++X10N
Numeric Operator**9N
Numeric Operator^9N
Numeric Operator%8N
Numeric Operator*8N
Numeric Operator/8N
Numeric Operator+ Addition7N
Numeric Operator- Subtraction7N
Numeric OperatorX--6N
Numeric OperatorX++6N
String Operator+5CConcatonate 1
String Operator-5CConcatonate 2
Relational Operator=4LN,C,D
Relational Operator#, <>, !=4N,C,D
Relational Operator<4LN,C,D
Relational Operator>4LN,C,D
Relational Operator<=4LN,C,D
Relational Operator>=4LN,C,D
Relational Operator$4LN,C,D
Relational Operator==Clipper operator, not implemented yet
Logical OperatorNOT3LEvaluated after all math and relational operators
Logical Operator.NOT.3LEvaluated after all math and relational operators
Logical OperatorAND2LEvaluated after all math and relational operators
Logical Operator.AND.2LEvaluated after all math and relational operators
Logical OperatorOR1LEvaluated after all math and relational operators
Logical Operator.OR.1LEvaluated 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.