SetFilter method (DataWindows)

Description

Specifies filter criteria for a DataWindow control or DataStore.

Controls

DataWindow type	Method applies to
PowerBuilder	DataWindow control, DataWindowChild object, DataStore object
Web	Server component
Web ActiveX	DataWindow control, DataWindowChild object

Syntax

Argument	Description
dwcontrol	The name of the DataWindow control, DataStore, or child DataWindow in which you want to define the filter.
format	A string whose value is a boolean expression that you want to use as the filter criteria. The expression includes column names or numbers. A column number must be preceded by a pound sign (#). If format is null, PowerBuilder prompts you to enter a filter.

Return Values

Returns 1 if it succeeds and –1 if an error occurs.
If no DataWindow object has been assigned to the DataWindow or DataStore, SetFilter returns –1. The
return value is usually not used.

Usage

A DataWindow object can have filter criteria specified as
part of its definition. After data is retrieved, rows that do not
meet the criteria are immediately transferred from the primary buffer
to the filter buffer.

The SetFilter method replaces the existing
filter criteria—if any are defined for the DataWindow object—with
a new set of criteria. Call the Filter method
to apply the filter criteria and transfer rows that do not meet the
filter criteria to the filter buffer.

The filter expression consists of columns, relational operators,
and values against which column values are compared. Boolean expressions
can be connected with logical operators AND and OR.
You can also use NOT, the negation operator.
Use parentheses to control the order of evaluation.

Sample expressions are:

The filter expression is a string and does not contain variables.
However, you can build the string in your script using the values
of script variables. Within the filter string, string constants
must be enclosed in quotation marks (see the examples).

Dictionary or ASCII order

By default, PowerBuilder performs comparisons in dictionary
order. For example, the following expression shows all the rows
in which column 2 begins with A, a, B or b:

To perform comparisons in ASCII order, append “s” to
the format string. For example, the following expression shows only
rows in which column 2 begins with a or b, because the ASCII values
of uppercase letters are lower than the ASCII values of lowercase
letters:

Number format

The formatting that you enter for numbers and currency in
filter expressions display the same way in any country. Changing
the regional settings of the operating system does not modify the
formatting displayed for numbers and currency at runtime.

Escape keyword

If you need to use the % or _ characters
as part of the string, you can use the escape keyword
to indicate that the character is part of the string. For example,
the _ character in the following filter string is part
of the string to be searched for, but is treated as a wildcard:

The escape keyword designates any character
as an escape character (do not use a character that is part of the
string you want to match). In the following example, the asterisk
(*) character is inserted before the _ character
and designated as an escape character, so that the _ character
is treated as part of the string to be matched:

User-specified filters

To let users specify their own filter expression for a DataWindow
control, you can pass a null string to the SetFilter method. PowerBuilder
displays its Specify Filter dialog box with the filter expression
blank. Then you can call Filter to apply the
user’s filter expression to the DataWindow. You cannot
pass a null string to the SetFilter method for
a DataStore object.

Removing a filter

To remove a filter, call SetFilter with
the empty string (“”) for format and
then call Filter. The rows in the filter buffer
will be restored to the primary buffer and positioned after the
rows that already exist in the primary buffer.

Examples

See Also

• Filter

---