JavaScript method: SCFile.setOrderBy()

This method causes any subsequent doSelect() call on a SCFile object to fetch only the specified fields by the specified sort sequences of the SCFileObject. If setOrderBy() has not been called, a subsequent doSelect() will use the default sort sequence.

Syntax

SCFile_object.setOrderBy(sortFields, sortSeqs);

Arguments

The following arguments are valid for this method:

Argument	Data type	Description
sortFields	Array	A javascript array of field name string, for example, newArray ("name","company").
sortSeqs	Array	A javascript array of sort sequenence specification. It is either a SCFILE_ASC, or SCFILE_DSC. For example, new Array(SCFILE_ASC, SCFILE_DSC); SCFILE_ASC is a constant for specifying sort by ascending order, and SCFILE_DSC for specifying sort by descending order.

Required properties

This method requires two parameters of the data type of array. The two arrays must be of the same length. Calling setOrderBy() with parameters of uneven length of arrays or non-array data results in failure return status. 

Return values

Returns RC_SUCCESS if successful and RC_ERROR on failure.

The following conditions cause a setOrderBy() failure:

• Calling setOrderBy() on an uninitialized SCFile
• Calling setOrderBy() with an invalid argument type (not an array) for either argument.
• Calling setOrderBy() with wrong number of arguments.
• Calling setOrderBy() with two arrays of different length.
• Calling setOrderBy() with one (or more) invalid fields. (The method performs a basic validation on the field names to ensure they exist in the DBDICT.

A warning is written to SM.log file.

If the sort sequence specifications in the sortSeq array is of non-recognizable constant, SCFILE_ASC is assumed.

Limitations:

• Fields used in setOrderBy() should not be within an array in the dbdict.
• Fields from a join file should not be within a structure in the dbdict.

Example

1. var sortOrder = [SCFILE_DSC];
2. var sortOrder = new Array(1);
sortOrder[0] = SCFILE_DSC;

This example does the following:

• Takes two fields, name and company, from the operator table, and sorts the company field by descending order, then the name field by ascending order.
• On failure returns a RC_ERROR status code.

This example requires the following sample data:

• Records in the operator table that have various company and name fields.

function runOrderByTest( table, fields, sortOrder)
{
  var timeBefore = new Date();
  var fCount = 0;
  print( "doSelect select column OrderBy test : Start time is: " +  timeBefore );
  var fRec = new SCFile( table); 
  var setOrderByRC = fRec.setOrderBy( fields, sortOrder);

  if ( setOrderByRC != RC_SUCCESS )
  {
    print( "ERROR: setOrderBy failed, RC=" + RCtoString( setOrderByRC ) ); 
    return RC_ERROR;
  }
  var selectRC = fRec.doSelect( "true" );
  if ( selectRC != RC_SUCCESS ) 
  {
    print( "ERROR: doSelect OrderBy failed, RC=" + RCtoString( selectRC ) );
    return RC_ERROR;
  }

  do
  {
    fCount++;
  }
  while (fRec.getNext() == RC_SUCCESS);

  var timeAfter = new Date();
  print( "doSelect select column Orderby test: table processed = " + table );
  print( "doSelect select column Orderby test: fields processed = " + fields );
  print( "doSelect select column Orderby test: sort order = " + sortOrder);
  print( "doSelect select column Orderby test: count = " + fCount );
  print( "doSelect select column Orderby test: End time is " + timeAfter );
  print( "doSelect select column Orderby test: Elapsed time is " + (timeAfter - timeBefore) + " milliseconds" );

  return RC_SUCCESS;
}

var table = "operator";
var fields = new Array("company", "name");
var sortOrder = new Array(SCFILE_DSC, SCFILE_ASC);
var testRC = runOrderByTest( table, fields, sortOrder);