DBSETFILTER()
 Set a filter condition
------------------------------------------------------------------------------
 Syntax

     DBSETFILTER(<bCondition>, [<cCondition>]) --> NIL

 Arguments

     <bCondition> is a code block that expresses the filter condition in
     executable form.

     <cCondition> stores the filter condition as a character string for
     later retrieval by the DBFILTER() function.  If you omit this optional
     parameter, the DBFILTER() function will return an empty string for the
     work area.

 Returns

     DBSETFILTER() always returns NIL.

 Description

     DBSETFILTER() sets a logical filter condition for the current work area.
     When a filter is set, records which do not meet the filter condition are
     not logically visible.  That is, database operations which act on
     logical records will not consider these records.

     The filter expression supplied to DBSETFILTER() evaluates to true (.T.)
     if the current record meets the filter condition; otherwise, it should
     evaluate to false (.F.).

     The filter expression may be a code block (<bCondition>) or both a code
     block and equivalent text (<cCondition>).  If both versions are
     supplied, they must express the same condition.  If the text version is
     omitted, DBFILTER() will return an empty string for the work area.

     DBSETFILTER() performs the same function as the standard SET FILTER
     command.  For more information, refer to the SET FILTER command.

 Notes

     .  Logical records: DBSETFILTER() affects the logical visibility
        of records (see above).

     .  Side effects: Setting a filter condition is only guaranteed to
        restrict visibility of certain records as described above.  The
        filter expression is not necessarily evaluated at any particular
        time, by any particular means, or on any particular record or series
        of records.  If the filter expression relies on information external
        to the database file or work area, the effect is unpredictable.  If
        the filter expression changes the state of the work area (e.g., by
        moving to a different record or changing the contents of a record),
        the effect is unpredictable.

     .  Evaluation context: When the filter expression is evaluated,
        the associated work area is automatically selected as the current
        work area before the evaluation; the previously selected work area is
        automatically restored afterward.

 Examples

     .  This example limits data access to records in which the Age
        field value is less than 40:

        USE Employee NEW
        DBSETFILTER( {|| Age < 40}, "Age < 40" )
        DBGOTOP()

 Files   Library is CLIPPER.LIB.