Commands and Statements Commands and Statements

Command SET FILTER Foundation

Specifies or removes a filter condition for a work area.

Syntax
SET FILTER TO [<lFilter>] [IN <nWorkArea> | <cAlias> ]
Scope
thread-local, current workarea
Parameters
<lFilter>
<Filter> is a logical expression which sets a filter condition for the current work area. If no argument is specified, the filter condition is removed for the current work area.
IN <nWorkArea>
<nWorkArea> is a positive integer specifying the ordinal number of the work area being selected.
IN <cAlias>
This argument is either a literal alias name or a character expression containing the alias name in parentheses. The alias name indicates the work area whose files are to be closed.
Description

The file command SET FILTER defines a filter condition which determines the logical visibility of records in the current work area. When the expression in <lFilter> provides the value .T. (true), the data record is visible. Those records which do not match the filter condition (<lFilter> returns the value .F. (false)) are not logically visible, and are skipped during all file operations that move the record pointer. Exceptions are the command GOTO and all commands that allow a RECORD option when the RECORD is specified. Using GOTO or the RECORD option, records can be accessed which do not match the filter condition.

After a filter condition has been defined using SET FILTER, the data record pointer must be moved at least once to guarantee that the current record matches the filter condition. This is generally done by a call to GO TOP, which positions the record pointer to the first data record matching the filter condition. When no matching record is available, the record pointer is set to the "Phantom" record and the function Eof() returns the value .T. (true) (for DBF files, this corresponds to the record pointer position LastRec()+1).

The functions DbSetFilter() and DbClearFilter() are the functional equivalents of the command SET FILTER.

When a filter contains a character expression and the exact equals operator (==) is not used in the filter expression, the filter condition can filter different records depending on the setting of SET LEXICAL ON | OFF and SET EXACT ON | OFF.

Examples
SET FILTER 
// In the example, a filter condition is defined for a customer file 
// based on the telephone area code. The names of the customers 
// in two states are then listed. 

PROCEDURE Main 
   USE Customer INDEX CustA NEW 

   SET FILTER TO Trim( AreaCode ) $ "303,970,719,307" 

   GO TOP 
   ? "Customers in Colorado and Wyoming" 

   LIST LName,FName TO FILE Customer.lst 

   CLOSE Customer 
RETURN
Feedback

If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please use this form to report a documentation issue.