Click above to get retro games delivered to your door ever month!

N_XFILTER()
Create client-server filter

Syntax
N_XFILTER([<cFilterExpression> [,@<aComparators>]])

RDD Syntax
SET SERVER FILTER TO <cFilterExpression>

Arguments
<cFilterExpression> consists of several simple comparison clauses, 
optionally grouped together by && (.AND.) or || (.OR.).

You may not use parentheses, nor any functions except UPPER(fieldname).

Do not use any alias-> clauses.  All fields being compared must be in the 
current area.

RaSQL permits the following operators:  =, >, <, >=, <=, !=.

<cFilterExpression> may include &macro substitution, just as any string 
literal may.  In addition,  it can include substitution variables in the 
form of @memvar or @n where n is the entry number in the @<aComparators> 
array.   Substitution variables are similar to &macro except that the value 
should be of the same data type as the field being compared.  If you specify 
@memvar, then the memvar must actually exist and may not be declared LOCAL 
or STATIC.

You need @<aComparators> only if  you use the @n substitution variable 
construction.  It is an array of values that RaSQL will substitute in the 
filter expression where ever you specified @n, where n refers to the entry 
number in the array. 

If  you use the RDD syntax, you can only use @memvar substitution variables; 
not @n.

See Examples for illustrations on the uses of substitution variables.

Returns
N_XFILTER(expression) returns .T. or .F. depending on whether  RaSQL could 
parse the expression correctly.
N_XFILTER() with no parameters returns the current filter expression.

Remarks
Similar to the SET FILTER command except that the server, rather than the 
workstation, performs record filtering.  In addition, it is a "smart" filter 
in that Btrieve, where applicable, will examine the current index to 
determine whether further searching will be useful; the normal SET FILTER 
always will continue searching to EOF.  Together, these features can result 
in significant performance improvements on a network.

Evaluation of the filter expression is simple left-to-right.  You may no use 
parantheses, nor any functions except for UPPER(fieldname).

You must separate all clauses in the filter expression by a space.  For 
example STATE='NY'.AND.AGE>40 is valid for SET FILTER, but not for 
N_XFILTER.  Instead specify STATE = 'NY' .AND. AGE > 40.

If you include @memvar or @<aComparator> in the filter and if any of the 
values changes later, the changed values will not affect the current filter 
until you reissue N_XFILTER.

As with the SET FILTER command, you should issue GOTO TOP (or N_XGOTOTOP() 
if not using the RDD) after N_XFILTER to position the record pointer on the 
first logical record.

Examples

*compare to literal
* Function syntax shown followed by RDD syntax
N_XFILTER([STATE = 'NY'])
SET SERVER FILTER TO STATE = "NY"

* compare to memvar
mState := "NY"
N_XFILTER("STATE = @mState")
SET SERVER FILTER TO STATE = @mState

* compound expression
mAge := 40
N_XFILTER("STATE = @mState .AND. AGE > @mAge")
SET SERVER FILTER TO STATE = @mState ;
            .AND. AGE > @mAge

* same expression using <aComparator>
N_XFILTER("STATE = @1 .AND. AGE > @2",{"NY",40})

* UPPER is the only function permitted
N_XFILTER("UPPER(STATE) = @1 .AND. AGE > @2", ;
           { "NY" , 40 }}