xHarbour Reference Documentation > Function Reference

DbSetFilter()

Defines a filter condition for a work area.

Syntax

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

Arguments

<bFilter>

A code block containing the filter expression. The expression must yield a logical value.

<cFilter>

The filter expression in form of a character string.

Return

The return value is always NIL.

Description

The DbFilter() function defines a filter condition for the current work area in form of the code block <bFilter>. All records in the work area where the filter condition yields .F. (false) are ignored during database navigation. As a result, these records become invisible and are filtered.

Although the second parameter <cFilter> is optional, it is recommended to specify the filter condition a second time as a character string. Otherwise, the DbFilter() function cannot obtain the filter condition and returns a null string (""), despite of a filter condition being active.

It is recommended to move the record pointer once after calling DbSetFilter() to ensure that the current record is not visible when it does not match the filter condition. This is usually done with DbGoTop().

Optimization:  filtering records can be a time consuming task since the filter condition is evaluated for each record during database navigation. This can be optimized when the filter condition matches the index expression of an open index and SET OPTIMIZE ist set to ON.

Info

See also:	DbClearFilter(), DbFilter(), SET DELETED, SET FILTER, SET OPTIMIZE
Category:	Database functions
Source:	rdd\dbcmd.c
LIB:	xhb.lib
DLL:	xhbdll.dll

Example

// The example demonstrates the effect of a filter condition

   PROCEDURE Main
      USE Customer
      INDEX ON Upper(LastName) TO Cust01

      GO TOP
      ? Recno(), Lastname              // result: 28 Abbey

      DbSetFilter( {|| Upper(LastName) > "L" }, ;
                      'Upper(LastName) > "L"'   )

      GO TOP
      ? Recno(), Lastname              // result: 182 MacDonald

      ? DbFilter()                     // result: Upper(LastName) > "L"

      CLOSE Customer
   RETURN