Filter

Description

Displays rows in a DataWindow that pass the current filter criteria. Rows that do not meet the filter criteria are moved to the filter buffer.

Applies to

DataWindow type

Method applies to

PowerBuilder

DataWindow control, DataWindowChild object, DataStore object

Web

Server component

Web ActiveX

DataWindow control, DataWindowChild object

Syntax

PowerBuilder

integer dwcontrol.Filter ( ) 

Web DataWindow server component

short dwcontrol.Filter ( )

Web ActiveX

number dwcontrol.Filter ( )

Argument

Description

dwcontrol

A reference to a DataWindow control, DataStore, or child DataWindow

Returns

Returns 1 if it succeeds and -1 if an error occurs. The return value is usually not used.

If dwcontrol is null, in PowerBuilder and JavaScript the method returns null.

Usage

Filter causes all rows to be retrieved and then it applies the filter. Even when the Retrieve As Needed option is set, the Filter method retrieves all rows before applying the filter.

Filter uses the current filter criteria for the DataWindow. To change the filter criteria, use the SetFilter method. The SetFilter method is equivalent to using the Filter command on the Rows menu of the DataWindow painter. If you do not call SetFilter to assign or change criteria before calling the Filter method, the DataWindow will default to use the criteria in the object definition.

When the Retrieve method retrieves data for the DataWindow, PowerBuilder applies the filter that was defined for the DataWindow object, if any. You only need to call Filter after you change the filter criteria with SetFilter or if the data has changed because of processing or user input.

Filter has no effect on the DataWindows in a composite report.

NoteFiltering and groups When you filter a DataWindow with groups, you might need to call GroupCalc after you call Filter.

For information on removing the filter or letting the user specify a filter expression, see SetFilter.

Examples

Example 1

This statement displays rows in dw_Employee based on its current filter criteria:

dw_Employee.SetRedraw(false)

dw_Employee.Filter()

dw_Employee.SetRedraw(true)

See also