Synergex.SynergyDE.Select.OrderBy

WTSupported in traditional Synergy on Windows
WNSupported in Synergy .NET on Windows
USupported on UNIX
VSupported on OpenVMS
namespace Synergex.SynergyDE.Select
public sealed class OrderBy

The OrderBy class is a collection of static methods for ordering a selection, either by key or non‑key fields, when the selection is created. The AscendingKey() and DescendingKey() methods specify the order in which a selected key is traversed, thereby affecting the order of the final output, where no post‑selection ordering is done. The Ascending() and Descending() methods enable you to order selected records by any field(s) regardless of whether they are defined keys, where the ordering process takes place after the entire selection has been done.

Important

Once created, any object used by the Select (From, Where, NoCaseWhere, On, OrderBy, and Sparse) must remain in contact with the same record(s) specified in the From object(s) as well as fields referenced in the Where, NoCaseWhere, On, OrderBy, and Sparse objects that are contained in the record(s). In other words, you can’t create one of these objects and pass it to another routine unless that routine has direct access to the original record. If this is not the case, an InvalidOperationException or $ERR_INVOPER error (“Where operator requires at least one field reference”) will result when creating the Select object. On the other hand, all data references outside a From object’s record are copied during the object’s creation and are not required to remain in contact with the original data.

Methods

Ascending

public static varargs Ascending(field1, ...), @OrderBy

Declares a list of fields (MISMATCH n), separated by commas, by which the selected records will be sorted in ascending order upon being returned.

AscendingKey

public static AscendingKey(krf), @OrderBy

Processes the selection in ascending order by key of reference (n).

Descending

public static varargs Descending(field1, ...), @OrderBy

Declares a list of fields (MISMATCH n), separated by commas, by which the selected records will be sorted in descending order upon being returned.

DescendingKey

public static DescendingKey(krf), @OrderBy

Processes the selection in descending order by key of reference (n).

Operators

The logical and operator (&& or .AND.) is supported and is equivalent to its Synergy counterpart. See Expressions for more information about this operator.

Discussion

The AscendingKey() and DescendingKey() methods specify the key of reference for the Where object selection if the key of reference has not been explicitly specified by Where.Keynum(). If a key of reference is specified by both Where.Keynum() and either AscendingKey() or DescendingKey(), it must be the same key or an InvalidOperationException or $ERR_INVOPER error (“Keynum(#) doesn’t match OrderBy key #”) will be generated. If the specified key of reference is a segmented key, and the segments are individually ordered differently, the order is determined by the key optimization level. If no optimization occurs, the order is determined by the first key segment. (See Optimization and ordering for ISAM files for more detailed information.)

When Ascending() or Descending() is used, the entire selection is read from the specified file when the AlphaEnumerator object is created (on Select.GetEnumerator() or FOREACH). Changes to the file after making the selection may not be reflected in the records retrieved, especially if a record that matches the selection criteria is updated or inserted.

The fields specified by Ascending() and Descending() must be in the record specified in the From class object. If they are not, an InvalidOperationException or $ERR_INVOPER error (“Field reference not entirely part of specified record”) will be generated at runtime.

You can combine multiple fields in your sort criteria using the .AND. operator. For example,

sobj = new Select(from, wobj, 
&  OrderBy.Descending(fld1).and.OrderBy.Ascending(fld2))