SetFilter – PB Docs 150

SetFilter method (DataWindows)


Specifies filter criteria for a DataWindow control or DataStore.


DataWindow type

Method applies to


DataWindow control, DataWindowChild object, DataStore


Server component

Web ActiveX

DataWindow control, DataWindowChild object



[Web DataWindow server component]

[Web ActiveX]




The name of the DataWindow control, DataStore,
or child DataWindow in which you want to define the filter.


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.


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

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.


This statement defines the filter expression for
dw_Employee as the value of format1:

The following statements define a filter expression
and set it as the filter for dw_Employee. With this filter,
only those rows in which the cust_qty column exceeds 100
and the cust_code column exceeds 30 are displayed. The
final statement calls Filter to apply the filter:

The following statements define a filter so that
emp_state of dw_Employee displays only if it is
equal to the value of var1 (in this case ME for Maine). The filter
expression passed to SetFilter is emp_state = ME:

The following statements define a filter so that
column 1 must equal the value in min_qty and column 2 must
equal the value in max_qty to pass the filter. The resulting
filter expression is:

The sample code is:

The following example sets the filter expression
to null, which causes PowerBuilder to display the Specify Filter
dialog box. Then it calls Filter, which applies
the filter expression the user specified:

See Also

Document get from Powerbuilder help
Thank you for watching.
Was this article helpful?
Notify of
Inline Feedbacks
View all comments
Would love your thoughts, please comment.x