Xbase++ - Function DbSetFilter()

Sets a filter condition for a work area.

DbSetFilter( <bFilter>, [<cFilter>] ) --> NIL

<bFilter> is a code block defining the filter condition for a work area as a logical expression.

The optional argument <cFilter> contains the logical filter expression of the code block as a character string.

The return value of DbSetFilter() is always NIL.

The database function DbSetFilter() defines a logical filter condition for a work area. This filter condition determines the logical visibility of records. When the expression in <bFilter> returns the value .T. (true), a record is visible. records which do not match the filter condition ( <bFilter> returns .F. (false)), are not logically visible and are skipped during all file operations that move the record pointer. An exception is the function DbGoto() which can access records that do not match the filter condition. When DbSetFilter() is used without the alias operator, the filter condition is defined for the current work area.

When the argument <cFilter> is included, it must contain the same logical expression as <bFilter>, but in the form of a character string. If <cFilter> is not specified, later calls to the function DbFilter() will return a null string (""). If <cFilter> is specified, calls to DbFilter() will return the character string <cFilter>.

After a filter condition is defined with DbSetFilter(), the record pointer must be moved at least once to guarantee that the current data record matches the filter condition. This is usually done by calling the function DbGoTop() to position the record pointer on the first data record matching the filter condition. If no matching record is available, the record pointer is set on the "phantom" record and the function Eof() returns the value .T. (true) (for DBF files that corresponds to record pointer position LastRec()+1).

The command SET FILTER can be used instead of DbSetFilter(). SET FILTER is effective only in the current work area.

When a filter depends on 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 SET LEXICAL ON | OFF.

DbSetFilter()


// In the example, a filter condition is defined for 
// a customer file based on the telephone area code. 
// Then the names of the customers from two states 
// (four area codes) are listed in a file. 

PROCEDURE Main 
   USE Customer INDEX CustA ALIAS Cu NEW 

   DbSetFilter( {|| Trim( AREACODE ) $ "303,970,719,307" }, ; 
                   'Trim( AREACODE ) $ "303,970,719,307"') 
   DbGoTop() 
   ? "Customers in Colorado and Wyoming" 

   LIST Cu->LastName,Cu->FirstName TO FILE Customer.lst 

   CLOSE Cu 
RETURN

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.

Function DbSetFilter() Foundation