SortedRecordset class

A SortedRecordset object represents an ordered set of records, much as a label on a Sort statement does in traditional User Language.

Like the other file-oriented objects, you use the following syntax to declare a SortedRecordset object:

%srs is object SortedRecordset - in [ file fname ] [ [ temp | perm ] group gname ] [ fgname ]

For example:

%srtStoogesL is object SortedRecordset in file ftpproc ... %s is object SortedRecordset in foo ... %sk is object SortedRecordset in temp group foo ... %skp is object SortedRecordset in perm group foo

Instantiating SortedRecordset objects

Prior to version 7.6 of the Sirius Mods, the SortedRecordset class contained no native constructor method, and the way to instantiate a SortedRecordset object is to make it the target of a Sort statement. In version 7.6, the RecordsetCursor New method was added, primarily to enable the creation of extension classes of the SortedRecordset class, which the Sort statement constructor cannot do.

Instantiation by the New method and by Sort statement is described below.

• A SortedRecordset New constructor has no parameters and simply instantiates an empty instance of its class. For example:

  %srs is object sortedRecordset in sordId ... %srs = new

  Such a new instance is not of significant value, and in most cases, the best way to instantiate a SortedRecordset instance is to use the Sort statement construction described below. As indicated earlier, however, the New constructor does enable the creation of an extension class of the SortedRecordset class, an example of which is shown in New.
  

• Much like a Recordset object, you can instantiate a SortedRecordset object by making it the target of a Sort statement. For example:

  Sort Records In %recset To %sortedrecset - By Name and Testkey

  The Sort Records and Sort Record Keys statements may instantiate SortedRecordset objects, and they also may specify the number of records sorted (Sort n Records, Sort n Record Keys).

  The In clause of an instantiating Sort statement may reference a Recordset object or a Find statement label. In addition, an On list phrase is supported with both Sort statement forms. This permits easy conversion of old applications: you can sort any existing found set or list and instantiate a SortedRecordset object.

  The revised syntax of the Sort statement is as follows, where any of the Sort “phrases” combined with any In or On phrase may instantiate a SortedRecordset object. Note that a By phrase is also required.

  {Sort Records } {In label } [To %srtrset] By ... {Sort Record Keys } {In %recset} {Sort n Records } {On list } {Sort n Record Keys}

  Here are some examples:

  sort records on lll to %srs by testkey ... srt1: sort records in %rset by testkey ... sort records in %rs to %srs by name ... sort records in a to %s by testkey ... sort 2 records in %r to %s by name ... sort 2 record keys in %r to %sk by name value descending

  While you may still place a label on the Sort statement (and use it as a Jump To target), you may not refer by label to an instantiated SortedRecordset object that is the output of a Sort statement. You must refer to the SortedRecordset object variable. This is described in the next section.

Referencing the records in an object instance

You loop on a SortedRecordset object with the identical For Each Record syntax that you use to loop on a regular Recordset object:

For Each Record In %srs ... Fr In %srs

As with Recordset objects, the In is required.

Freeing a sorted record set

Release Records In may refer to a SortedRecordset object instance, as well as to a Recordset object instance. A SortedRecordset instance specified on a Release statement is discarded, and all CCATEMP pages associated with it are freed.

In addition to the Release statement to discard a SortedRecordset object, you may also use the Discard function (as in, %srecs:discard).

SortedRecordset example

The following short example demonstrates the basic operations with SortedRecordset objects:

begin %recs is object recordSet in file ftptest %srecs is object sortedRecordset in file ftptest * create the recordset fd to %recs end find * sort them sort records in %recs to %srecs by testkey print %srecs:count * loop on the sorted version fr in %srecs pai end for * free the set objects release records in %recs release records in %srecs end

List of SortedRecordset methods

The "List of SortedRecordset methods" shows all the class methods.