SetSort – PB Docs 150

SetSort method (DataWindows)


Specifies sort criteria for a DataWindow control or DataStore.


DataWindow type

Method applies to


DataWindow control, DataWindowChild object, DataStore


Client control, server component

Web ActiveX

DataWindow control, DataWindowChild object



[Web DataWindow client control and Web ActiveX]

[Web DataWindow server component]




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


A string whose value is valid sort criteria
for the DataWindow (see Usage). 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 the sort criteria.

Return Values

Returns 1 if it succeeds and –1 if an error occurs.


A DataWindow object can have sort criteria specified as part
of its definition. SetSort overrides the definition,
providing new sort criteria for the DataWindow. However, it does
not actually sort the rows. Call the Sort method
to perform the actual sorting.

The sort criteria for a column have one of the forms shown
in the following table, depending on whether you specify the column
by name or number.

Table 9-10: Examples for specifying sort order

Syntax for sort order


columnname order

“emp_lname A”

“emp_lname asc, dept_id desc”

# columnnumber order

“#3 A”

The following table shows the recognized values for order.
These values are case insensitive. For example, as, s, AS,
or S all specify a case-sensitive
sort in ascending order.

Table 9-11: Recognized values for sort order

Order value

Resulting sort order

a, asc, ascending, ai, i

Case-insensitive ascending

d, desc, descending, di

Case-insensitive descending

as, s

Case-sensitive ascending


Case-sensitive descending

If you omit order or specify an unrecognized
string, the sort is performed in ascending order and is case insensitive.
You can specify secondary sorting by specifying criteria for additional
columns in the format string. Separate each column specification
with a comma.

To let the user specify the sort criteria for a DataWindow
control, you can pass a null string to the SetSort method.
PowerBuilder displays the Specify Sort Columns dialog with the sort
specifications blank. Then you can call Sort to
apply the user’s criteria. You cannot pass a null string
to the SetSort method for a DataStore object.


This statement sets the sort criteria for dw_employee
so emp_status is sorted in ascending order and within each
employee status, emp_salary is sorted in descending order:

If emp_status is column 1 and emp_salary
is column 5 in dw_employee, then the following statement
is equivalent to the sort specification above:

This example defines sort criteria to sort the status
column in ascending order and the salary column in descending order
within status. Both sorts are case sensitive. After assigning the
sort criteria to the DataWindow control dw_emp, it sorts

The following example sets the sort criteria for
dw_main to null, causing PowerBuilder to display the Specify
Sort Columns dialog so that the user can specify sort criteria.
The Sort method applies the criteria the user specifies:

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