Synergex.SynergyDE.Select.RestrictedAlphaEnumerator

Base enumerator class for Select

namespace Synergex.SynergyDE.Select
public class RestrictedAlphaEnumerator

The RestrictedAlphaEnumerator class is the base enumerator class for AlphaEnumerator, containing the non-control members of AlphaEnumerator objects. The primary function of the RestrictedAlphaEnumerator class is to inhibit enumerator controls during implicit enumeration (via FOREACH).

Using a FOREACH statement with a Select object creates and maintains the enumerator class object internally, and it is hidden.

You can access a RestrictedAlphaEnumerator class object from FOREACH statement controls by using the Select.GetEnum() method. The RestrictedAlphaEnumerator class allows access to the current record but not the enumerator itself. The following properties and methods can be used with the RestrictedAlphaEnumerator and AlphaEnumerator classes.

Properties

Current

public Current

Implements a get method that returns the current record and a set method that updates the current record by effectively doing a WRITE to the file, which unlocks the record on completion. (a)

CurrentRDLEN

public CurrentRDLEN

Implements a get method that returns the %RDLEN of the current record. (int)

CurrentReadCount

public CurrentReadCount

Implements a get method that returns the number of READ operations made to retrieve the current record. (int)

IsLocked

public IsLocked

Implements a get method that returns a nonzero value if the current record was acquired with a lock and is currently locked, or returns 0 if it is not currently locked. (int)

TotalReadCount

public TotalReadCount

Implements a get method that returns the total number of READ operations made to retrieve all records up to the current record. (int)

GetCTInfo

public GetCTInfo

Retrieves the change tracking information for the current record. If there isn’t a current record or the current record isn’t being tracked, returns ^NULL. (@CTInfo)

Methods

CurrentRFA

public CurrentRFA(rfa), void

Returns the RFA or GRFA of the current record (a6 or a10), depending on whether rfa is passed as an a6 or a10, respectively.

DeleteCurrent

public DeleteCurrent(), void

Deletes the current record. If the current record is not locked, a “No current record” error (E_NOCURR) is generated.

SparseUpdate

public varargs SparseUpdate(field1, ...), void

Works in conjunction with SparseRecord() to limit the amount of data transferred to xfServer when updating a record. Field1, etc., is one or more specific fields to update in the record, separated by commas. (MISMATCH n)

Discussion

The set method of the Current property requires the file to be opened for update and the current record to be locked, or else an “Invalid operation for file type” error ($ERR_FILOPT) and “No current record” error ($ERR_NOCURR) will be generated. When Select.SparseRecord() has been used on the Select object, using the set method will generate an “Invalid operation: Using Current method with a sparse record not allowed, use SparseUpdate” error ($ERR_INVOPER).

Both get and set methods (of the Current property) generate a “No current record” error if the enumerator is in its initial position or in its final position.

Locked records that do not match the selection criteria are always skipped, so handling a lock in that condition is not necessary.

To reduce network write traffic, you can use SparseUpdate() (usually with Select.SparseRecord()) instead of the Current property to update only the specified fields or only the fields specified by SparseRecord() that have changed from the current record. For example, given the following:

sobj = new Select(from, wobj)
sobj.SparseRecord(fld1, fld2, fld3)

your SparseUpdate() calls could be any of the following:

SparseUpdate() Calls
Call	What’s updated
enum.SparseUpdate(rec)	Fields specified by SparseRecord() that have changed in the current record
enum.SparseUpdate(fld3)	Only fld3 if changed in the current record; fld1 and fld2 are not updated even if their values have changed
enum.SparseUpdate(fld2, fld3)	Only fld2 and fld3 if changed in the current record
enum.SparseUpdate(fld2, fld3, fld4)	Fld2 and fld3 if they are changed in the current record, and fld4 (explicitly, as it was not specified by SparseRecord())
enum.SparseUpdate(rec, fld4)	Fields specified by SparseRecord() that have changed in the current record, and fld4 (explicitly, as it was not specified by SparseRecord())

When using the FOREACH statement, you can use Select.GetEnum().SparseUpdate().

SparseUpdate() can also be used without SparseRecord(), in which case the entire record is checked. You can designate specific fields to update in the record (for example, SparseUpdate(fld1), where only changes made to fld1 in the record will be updated), or you can specify the entire record (for example, SparseUpdate(rec), where any changes made anywhere within record rec will be updated). When SparseUpdate() is used on the entire record instead of the Current set property, the only difference is with xfServer: only the changes that are made to the record are transferred to the server.

You can gather performance statistics by using the CurrentReadCount() property to query the effectiveness of certain selections. Using optimization correctly can improve performance, and analyzing these statistics and tuning the Where clause appropriately can lead to better optimization.

record
    aenum, @RestrictedAlphaEnumerator   ;Must be declared outside FOREACH 
    .                                   ; to access after exiting compound statement
    .
    .
    foreach rec in new Select(from, where)
      begin
        .
        .
        .
        aenum = Select.GetEnum()
        n = aenum.CurrentReadCount   ;n returned with number of I/Os used 
                                     ; to retrieve the current record
      end
    n = aenum.CurrentReadCount       ;n returned with number of I/Os used
    m = aenum.TotalReadCount         ; to determine selection complete, 
                                     ; m returned with total number I/Os

TotalReadCount behaves slightly differently with static cursors. For a single-table query, the initial TotalReadCount when an enumerator is created reflects the total number of reads required to add all entries in the cursor (which might not be equal to the number of records in the result set, depending on whether the records were read individually or in blocks). For each subsequent iteration over the result set, CurrentReadCount will be 1, and this value will be added to TotalReadCount. For joins, TotalReadCount behaves similarly, although CurrentReadCount will typically be 1 per table in the join. (The actual value may vary based on whether a record is different between subsequent rows.)