Description
Specifies sort criteria for a DataWindow control or DataStore.
Applies to
|
DataWindow type |
Method applies to |
|---|---|
|
PowerBuilder |
DataWindow control, DataWindowChild object, DataStore object |
Syntax
PowerBuilder
integer dwcontrol.SetSort ( string format )
|
Argument |
Description |
|---|---|
|
dwcontrol |
A reference to a DataWindow control, DataStore, or child DataWindow. |
|
format |
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 value
Returns 1 if it succeeds and -1 if an error occurs.
Usage
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.
When the Retrieve method retrieves data for the DataWindow, PowerBuilder applies the sort criteria that were defined for the DataWindow object, if any.
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.
|
Syntax for sort order |
Examples |
|---|---|
|
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.
|
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 |
|
ds |
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.
If you omit order or specify an unrecognized string, the Describe function may obtain the incorrect sort criteria. It is recommended that you set the order value to "A" or "D" (asc, ascending, desc, or descending are not recommended) if you want the Describe function to return the correct sort criteria. For example use setsort("id A,name A") instead of setsort("id,name").
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.
Examples
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:
dw_employee.SetSort("emp_status asc, emp_salary desc")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:
dw_employee.SetSort("#1 A, #5 D")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 dw_emp:
string newsort newsort = "emp_status as, emp_salary ds" dw_emp.SetSort(newsort) dw_emp.Sort( )
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:
string null_str SetNull(null_str) dw_main.SetSort(null_str) dw_main.Sort( )
See also
