Sorts the rows in a DataWindow control or DataStore using the DataWindow’s current sort criteria.
DataWindow type |
Method applies to |
|---|---|
PowerBuilder |
DataWindow control, DataWindowChild object, DataStore object |
Web |
Client control, server component |
Web ActiveX |
DataWindow control, DataWindowChild object |
integer dwcontrol.Sort ( )
Web DataWindow client control and Web ActiveX
number dwcontrol.Sort ( )
Web DataWindow server component
short dwcontrol.Sort ( )
Argument |
Description |
|---|---|
dwcontrol |
A reference to a DataWindow control, DataStore, or child DataWindow |
Returns 1 if it succeeds and –1 if an error occurs. If dwcontrol is null, Sort returns null.
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.
Calling Sort causes the page to be reloaded.
If the DataWindow object has retrieval arguments, they must be specified in the HTMLGen.SelfLinkArgs property. For more information, see the HTMLGen.property, the Retrieve method, and the DataWindow Programmers Guide.
All methods that reload the page perform an AcceptText before sending data back to the server. If the method fails (returns -1), this means that pending data changes were not accepted and nothing was sent back to the server. In this situation the ItemError event occurs.
PowerBuilder environment
For use with PowerBuilder ListView and TreeView controls,
see Sort in the PowerScript Reference.
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)
