Apollo API (Apollo Engine) > xBase Expression Engine

Program functions and symbols used to manipulate xBase data are part of the xBase programming syntax developed for DOS based computers. The programming language used to manipulate xBase files in DOS is not well suited to Windows application development. However, many of the xBase functions contained within the xBase programming language exist within every index file and therefore xBase functions must be supported in order to properly manage these files.

Index expressions used in index files or "tags" are often constructed using xBase syntax to describe the index order. For example, the telephone book's white pages would be indexed on an expression:

"UPPER(LASTNAME)"

The "UPPER()" function is used to standardize the characters in the sort key, otherwise lowercase characters would always come after uppercase characters. A company named "abc cleaners" would appear after "Zeus Tailors". See Sort order for more on collation and sorting options.

Note: A tag is basically one or more indexes that are contained within a single index file such as CDX or NSX)

Any xBase data engine that purports to deal with xBase files and xBase indexes (of any dialect) must be able to understand and apply many of the standard xBase functions. Other xBase operations (such as setting filters and queries) and defining the terms of conditional indexes use xBase syntactical structures as well. In addition, the functions that manipulate xBase dates are unique to xBase date formats so an xBase data engine should be able to deal with these functions as well.

Note: Apollo does not allow the evaluation of xBase expressions directly from the programming language calling it. Instead, evaluation of traditional expressions is carried out indirectly by passing the expression as a string to Apollo's evaluation engine, which evaluates the expression and returns the result (see the sx_Eval* functions for details).

If you require the result of an xBase expression in your program, use the sx_Eval* functions to evaluate the required expression. For example, if you want the result of the DTOS() function on an xBase date field, do the following:

sDate = sx_EvalString( "DTOS(hiredate)" )

In addition to passing results of expressions back to your program, the evaluation engine is also used to manage standard xBase expressions used in constructing key expressions for indexes, setting filters, and defining conditions. Any function that requires an xBase expression must have the expression passed as a string to the function either as the contents of a string variable or as a literal string.

sExpr = "UPPER(country) = 'GERMANY'"

lRecNum = sx_Query( sExpr )

-or-

lRecNum = sx_Query( "UPPER(country) = 'GERMANY'" )

Note: Embedded literal values must be delimited with double quotes.

If values contained in program variables are to be passed as part of the expression, the variables must be embedded within the expression string by using a string concatenation operator. For example, if the country was solicited from the user and stored in variable sUser, the expression above would be constructed as follows:

sExpr = "upper(country) = '" + UpperCase(sUser) + "'"

lRecNum = sx_Query( sExpr )

Note: The maximum allowable length of any xBase expression is 255 characters.

Operators

Operators used in xBase expressions are standard in every xBase dialect.

Alias Operator

AliasName->sx_FieldName or AliasName.Field

String Operators

+ Joins two strings. Trailing spaces in the strings are placed at the end of each string.

- Joins two strings and removes trailing spaces from the string preceding the operator and places them at the end of the string following the minus sign operator.

Numeric Operators

+ Addition

- Subtraction

* Multiplication

/ Division

^ Exponentiation (or **)

Relational Operators

= Equal to

== Exactly equal to

<> Not equal to

# Not equal to

!= Not equal to

< Less than

> Greater than

<= Less than or equal to

>= Greater than or equal to

$ Is contained in

Logical Operators

.AND. Both expressions are true

.OR. Either expression is true

.NOT. Either expression is false

Notice the periods surrounding the operators.

Evaluation Order

When more than one type of operator appears in an xBase expression, the order of evaluation is as follows:

alias name

string

numeric

relational

logical

Expressions containing more than one operator are evaluated from left to right. Parentheses are used to change the evaluation order. If parentheses are nested, the innermost set is evaluated first.

Numeric operators are evaluated according to generally accepted arithmetic principles:

operators contained in parentheses

exponentiation

multiplication and division

addition and subtraction

Order of evaluation may be altered with parentheses:

3+4*5+6 = 29

(3+4)*5+6 = 41

(3+4)*(5+6) = 77

Logical operators are evaluated as .NOT. first, .AND. second, and .OR. last. Logical evaluation order may also be altered with parentheses. In multiple conditional expressions that contain the .NOT. operator, always use parentheses to enclose the .NOT. operator with the expression to which it applies. For example, a conditional expression such as

dtos(eventdate) = dtos(date()) .and. .not. status = 'H'

seems innocent enough but according to the rules of precedence it would be evaluated as

.not.(dtos(eventdate) = dtos(date()) .and. status = 'H').

The correct form of the expression is

(dtos(eventdate) = dtos(date())) .and. (.not. status = 'H')).