SetSort
method (DataWindows)
Description
Specifies sort criteria for a DataWindow control or
DataStore.
Applies to
|
DataWindow type |
Method applies to |
|---|---|
|
PowerBuilder |
DataWindow control, DataWindowChild object, DataStore |
Syntax
PowerBuilder
|
1 |
integer dwcontrol.SetSort ( string format ) |
|
Argument |
Description |
|---|---|
|
dwcontrol |
A reference to a DataWindow control, DataStore, or |
|
format |
A string whose value is valid sort criteria for the A column number must be preceded by a pound |
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 |
|
# 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:
|
1 |
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:
|
1 |
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:
|
1 2 3 4 |
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:
|
1 2 3 4 |
string null_str SetNull(null_str) dw_main.SetSort(null_str) dw_main.Sort( ) |
See also