DbSetFilter Function

Set a filter condition.

Namespace: XSharp.RT
Assembly: XSharp.RT (in XSharp.RT.dll) Version: 2.19

Syntax

 FUNCTION DbSetFilter(
	cbCondition,
	cCondition
) AS LOGIC CLIPPER

[ClipperCallingConventionAttribute(new string[] { ... })]
public static bool DbSetFilter(
	Usual cbCondition = default,
	Usual cCondition = default
)

Request Example View Source

Parameters

cbCondition (Optional): Type: Usual
A code block that expresses the filter condition in executable form.
cCondition (Optional): Type: Usual
An optional character value that expresses the filter condition in textual form.
If cCondition is omitted, the DBFilter() function will return an empty string for the work area.

Return Value

Type: Logic
TRUE if the current record meets the filter condition; otherwise, FALSE.

Remarks

DBSetFilter() sets a logical filter condition. By default, this function operates on the currently selected work area.
It can be made to operate on an unselected work area by specifying it within an aliased expression 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 can 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.
DBSetFilter() performs the same function as the SET FILTER command.
For more information, refer to the SET FILTER command.

Tip
If the RDD you are using supports optimization, use SET OPTIMIZE to control whether the RDD will optimize the filter search based on the available orders in the work area.

Tip
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 (for example, 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.

Tip

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 (for example, 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:

Copy

1USE employee NEW
2DBSetFilter({|| Age < 40}, "Age < 40")
3DBGoTop()

Reference

Functions, Globals and Defines

XSharp.RT Namespace

DbClearFilter

DbFilter

SetFilter(Usual, Usual)

VoDbSetFilter(Usual, String)