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 object |
Syntax
PowerBuilder
integer dwcontrol.Sort ( )
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:
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:
dw_depts.SetRedraw(false) dw_depts.Sort() dw_depts.GroupCalc() dw_depts.SetRedraw(true)
See also
