Sort
method (DataWindows)
Description
Sorts the rows in a DataWindow control or DataStore using the
DataWindow’s current sort criteria.
Applies to
|
DataWindow type |
Method applies to |
|---|---|
|
PowerBuilder |
DataWindow control, DataWindowChild object, DataStore |
Syntax
PowerBuilder
|
1 |
integer dwcontrol.Sort ( ) |
|
Argument |
Description |
|---|---|
|
dwcontrol |
A reference to a DataWindow control, DataStore, or |
Return value
Returns 1 if it succeeds and -1 if an error occurs. If dwcontrol is
null, Sort returns null.
Usage
Sort uses the current sort criteria for the DataWindow. To change
the sort criteria, use the SetSort method. The SetSort method is
equivalent to using the Sort command on the Rows menu of the DataWindow
painter. If you do not call SetSort to set the sort criteria before you
call Sort, Sort uses the sort criteria specified in the DataWindow object
definition.
When the Retrieve method retrieves data for the DataWindow,
PowerBuilder applies the sort criteria that were defined for the
DataWindow object, if any. You need to call Sort only after you change the
sort criteria with SetSort or if the data has changed because of
processing or user input.
For information on letting the user specify sort criteria using the
built-in dialog box, see SetSort.
When you sort a DataWindow on a specified column, rows with null
data remain at the top, regardless of whether you choose ascending or
descending order for your sort criteria. The sort order is performed on a
result set returned from a database, but is not necessarily the same sort
order used by the database (to return the result set) when an ORDER
BY clause is used in a SQL query.
The Sort method uses a typical lexical sort, with symbols, such as a
hyphen or underline, ranked higher than alphanumeric characters. It
compares characters in the same manner as does a dictionary.
When the Retrieve As Needed option is set, the Sort method cancels
its effect. Sort causes all rows to be retrieved so that they are sorted
correctly. It also changes the current row to 1 without causing the
RowFocusChanged or RowFocusChanging events to fire. These events should be
triggered programmatically after the Sort method is called.
Sort has no effect on the DataWindows in a composite report.
Sorting and groups
To sort a DataWindow object with groups or TreeView levels, call
GroupCalc after you call Sort.
PowerBuilder environment
For use with PowerBuilder ListView and TreeView controls, see
the section called “Sort” in PowerScript Reference.
Examples
This example sets dw_employee to be sorted by column 1 ascending and
then by column 2 descending. Then it sorts the rows:
|
1 2 3 4 |
dw_employee.SetRedraw(false) dw_employee.SetSort("#1 A, #2 D") dw_employee.Sort() dw_employee.SetRedraw(true) |
In this example, the rows in the DataWindow dw_depts are grouped
based on department and the rows are sorted based on employee name. If the
user has changed the department of several employees, then the following
commands apply the sort criteria so that each group is in alphabetical
order and then regroup the rows:
|
1 2 3 4 |
dw_depts.SetRedraw(false) dw_depts.Sort() dw_depts.GroupCalc() dw_depts.SetRedraw(true) |
See also