Sort method (DataWindows)

Description

Sorts the rows in a DataWindow control or DataStore using
the DataWindow’s current sort criteria.

Controls

DataWindow type	Method applies to
PowerBuilder	DataWindow control, DataWindowChild object, DataStore object
Web	Client control, server component
Web ActiveX	DataWindow control, DataWindowChild object

Syntax

Argument	Description
dwcontrol	A reference to a DataWindow control, DataStore, or child DataWindow

Return Values

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.

Web DataWindow client control

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.

Examples

See Also

• GroupCalc

• SetSort

---