Synergex.SynergyDE.Select.Sparse

namespace Synergex.SynergyDE.Select
public sealed class Sparse

The Sparse class specifies a partial, or sparse, record.

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.

Constructors

Sparse

public varargs Sparse(field1, ...)

Identifies the field specifications (n) to return in the From record(s). Field1, etc., must be part of a record specified in the From class object. To request all fields, specify “*” (including the quotation marks).

Operators

Sparse supports a logical and operator, which is equivalent to its Synergy counterpart (&& or .AND.), to concatenate Sparse objects at runtime. See Expressions for additional information about this operator.

Discussion

A sparse record is a subset of a record. While the entire record will be read, only the specified fields will be returned, and all other fields will be blanked out. Using Sparse is most effective when you’re using xfServer and only parts of the record(s) are needed. Only those fields specified are transferred across the network, optimizing performance.

Sparse is an alternative to the SparseRecord() method in the Select class. (See SparseRecord.) Select.Sparse differs from Select.SparseRecord() in that Select.Sparse can be constructed dynamically at runtime.

Fields specified in the Sparse constructor must either explicitly or implicitly reference fields in a record specified in a subsequent From object (or From objects if used in a join). If they don’t reference a field in a record, an $ERR_ INVOPER error (“Invalid operation: Field reference not entirely part of a From record”) will be generated.

Specifying a single, alpha parameter consisting of an asterisk in quotation marks (“*”) is the equivalent of SELECT * in SQL and selects all fields. It’s also equivalent to not using Sparse at all; however, it can be useful when constructing at runtime. If you specify “*”, you can’t specify any other parameters.

Using Sparse with no parameters requests that no fields be returned. This is useful only when using the RowEnumerator.Count() method or when constructing a list of fields dynamically where Sparse is the first or leftmost to be concatenated with the logical and operator.

When Select.Sparse is used in conjunction with IOHooks, Sparse is ignored or disabled until I/O hooks on the channel have been disabled or removed. More specifically, when either read or write I/O hooks have been implemented and are part of the IOHooks creation mask and either the Select has specified a Sparse object on creation or SparseRecord has been issued, sparse data functionality is disabled. To re-enable sparse functionality, both the read and write I/O hooks must be removed.

Using Select with a Sparse record without xfServer (i.e., to a local file) provides no real benefit and can negatively affect performance. We recommend using Sparse records only when accessing remote files via xfServer.