setSortFn( ) method

Specifies or clears a user-defined sort function with 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 a sort function 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.setSortFn ( funcRef )
jsdo-ref.table-ref.setSortFn ( funcRef )

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.

funcRef

A reference to a JavaScript sort function that compares two record objects for the sort and returns a number value. This function must have following signature:

Syntax:

function [ func-name ] ( jsrecord-ref1 , jsrecord-ref2 )

Where func-name is the name of a function that you define external to the setSortFn( ) method parameter list, and jsrecord-ref1 and jsrecord-ref2 are two JSRecord objects that the function compares from the specified table reference. You can then pass func-name to the setSortFn( ) method as the funcRef parameter. Alternatively, you can specify funcRef as the entire inline function definition without func-name.

Your funcRef code determines the criteria by which one of the two input record objects follows the other in the sort order, and returns one of the following values depending on the result:

• 1 — The jsrecord-ref1 object follows (is "greater than") the jsrecord-ref2 object in the sort order.
• -1 — The jsrecord-ref1 object precedes (is "less than") the jsrecord-ref2 object in the sort order.
• 0 — The two record objects occupy the same position (are "equal") in the sort order.

When the JSDO invokes an automatic sort, and a sort function is set using this method, the sort uses this function to determine the sort order for every pair of records that it tests as it iterates through the record objects of the specified table reference.

If you set the funcRef parameter to null, the method clears any sort function definition. Automatic sorting for the table reference can then occur only if there are one or more existing sort fields set using the setSortFields( ) method.

Examples

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 automatically sorted using the results of the external user-defined function, sortOnNameCSensitive( ), whose reference is passed to the setSortFn( ) method. In this case, the function compares the case-sensitive values of the Name fields from each pair of eCustomer record objects selected by the sort. 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.setSortFn ( sortOnNameCSensitive );
dsCustomer.fill();
. . .
dsCustomer.eCustomer.foreach( function( customer ){ . . . } );

function sortOnNameCSensitive ( rec1 , rec2 ) { 
  if (rec1.data.Name > rec2.data.Name) 
    return 1; 
  else if (rec1.data.Name < rec2.data.Name) 
    return -1; 
  else
    return 0;
  }

If you want to compare the Name field in this function using a case-insensitive test, you can use the JavaScript toUpperCase( ) function in the user-defined function. For example, in sortOnNameCInsensitive( ), as follows:

dsCustomer = new progress.data.JSDO( { name: 'dsCustomer' });
dsCustomer.setSortFn ( sortOnNameCInsensitive );
dsCustomer.fill();
. . .
dsCustomer.eCustomer.foreach( function( customer ){ . . . } );

function sortOnNameCInsensitive ( rec1 , rec2 ) { 
  if (rec1.data.Name.toUpperCase() > rec2.data.Name.toUpperCase()) 
    return 1; 
  else if (rec1.data.Name.toUpperCase() < rec2.data.Name.toUpperCase()) 
    return -1; 
  else
    return 0;
  }

See also:

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