setSortFields( ) method

Specifies or clears the record fields on which to automatically sort the record objects for a table reference after you have set its autoSort property to true (the default).

This method enables or disables automatic sorting based on record fields only for supported JSDO operations. See the description of the autoSort property for more information.

Return type: null

Applies to: progress.data.JSDO class, table reference property (JSDO class)

Syntax

jsdo-ref.setSortFields ( sort-fields )
jsdo-ref.table-ref.setSortFields ( sort-fields )

jsdo-ref

A reference to the JSDO. You can call the method on jsdo-ref if the JSDO has only a single table reference.

table-ref

A table reference on the JSDO.

sort-fields

An array of string values set to the names of record fields on which to sort the record objects, with an optional indication of the sort order for each field. This array can have the following syntax:

Syntax:

[ "field-name[:sort-order]" [ , "field-name[:sort-order]" ] ... ]

field-name

The name of a field in the record objects of the specified table reference. Any field-name must already exist in the JSDO schema and must have a scalar value (cannot be an array field).

sort-order

An indication of the sort order for the field, which can have one of the following case-insensitive values:

• ASC — Sorts ascending.
• ASCENDING — Sorts ascending.
• DESC — Sorts descending.
• DESCENDING — Sorts descending.

The default sort order is ascending.

When the automatic sort occurs, the record objects are sorted and grouped by each successive field-name in the array, according to its JavaScript data type and specified sort-order. Fields are compared using the >, <, and = JavaScript operators. All string fields can be compared with or without case sensitivity depending on the caseSensitive property setting. However, note that date fields are compared as dates, even though they are represented as strings in JavaScript.

If you set the sort-fields parameter to null, or you specify an empty array, the method clears all sort fields. Automatic sorting for the table reference can then occur only if there is an existing sort function setting using the setSortFn( ) method.

Example

In the following code fragment, assuming the autoSort property is set to true on dsCustomer.eCustomer (the default), after the fill( ) method initializes JSDO memory, the record objects for eCustomer are sorted by the Country field ascending, then by the State field within Country ascending, then by the Balance field within State descending. At a later point, the foreach( ) method then loops through these record objects, starting with the first record in eCustomer sort order:

dsCustomer = new progress.data.JSDO( { name: 'dsCustomer' });
dsCustomer.eCustomer.setSortFields( [ "Country", "State", "Balance:DESC" ] );
dsCustomer.fill();
. . .
dsCustomer.eCustomer.foreach( function( customer ){ . . . } );

See also:

autoSort property, caseSensitive property, setSortFn( ) method, sort( ) method