Synergex.SynergyDE.Select.From

namespace Synergex.SynergyDE.Select
public sealed class From

The From class defines from which file a selection will be made. It also defines the input record size and provides a template for determining field to record offsets. In addition, the locking behavior can be altered from the locking behavior of the file open.

When changing locking behavior, the new behavior must be supported by the open mode of the file. Adding locking (Q_AUTO_LOCK or Q_MANUAL_LOCK) is ignored if the file is opened for input mode.

Once created, any object used by the Select (From, Where, NoCaseWhere, GroupBy, NoCaseGroupBy, On, OrderBy, NoCaseOrderBy, 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, GroupBy, NoCaseGroupBy, On, OrderBy, NoCaseOrderBy, 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.

For an example, see Examples.

Constructors

From

public From(channel, record)

Specifies the file, by channel (n), from which the selection will be taken and the name of a record, group, or structure (a) that represents the beginning offset and maximum size of the record to be read.

public From(channel, lock, wait, record)

Specifies the file, by channel (n), from which the selection will be taken; specifies the name of a record, group, or structure (a) that represents the beginning offset and maximum size of the record to be read; and sets up locking behavior that overrides the behavior set up for the channel by the Open statement. Lock (n) is a LOCK qualifier lock_spec value (optionally combined with Q_NO_GRFA; see the Discussion below for more information), and wait (n) is a WAIT qualifier wait_spec value.

public From(filename, record)

Opens the specified file by filename (a), defaulting to input mode, from which the selection will be taken and specifies the name of a record, group, or structure (a) that represents the beginning offset and maximum record size of the record to be read.

public From(filename, lock, wait, record)

Opens the specified file by filename (a), defaulting to input mode, from which the selection will be taken; specifies the name of a record, group, or structure (a) that represents the beginning offset and maximum size of the record to be read; and sets up locking behavior. Lock (n) is a LOCK qualifier lock_spec value (optionally combined with Q_NO_GRFA; see the Discussion below for more information), and wait (n) is a WAIT qualifier wait_spec value.

public From(filename, record, open_options)

public From(filename, lock, wait, record, open_options)

Opens the specified file by filename (a), with the open mode specified by the open_options string (a), from which the selection will be taken using the specified open_options string; specifies the name of a record, group, or structure (a) that represents the beginning offset and maximum size of the record to be read; and sets up locking behavior. If open_options doesn’t specify an open mode, input mode is the default. Lock (n) is a LOCK qualifier lock_spec value (optionally combined with Q_NO_GRFA; see the Discussion below for more information), and wait (n) is a WAIT qualifier wait_spec value.

Methods

Dispose

public Dispose(), void

Releases the Select context from the file and, if being managed by the From object, closes the file. (Synergy .NET only)

Because Select (or From) has what . NET considers to be heavy-weight objects with unmanaged resources, we recommend that you always explicitly dispose of Select and From objects rather than waiting for garbage collection.

InnerJoin

public InnerJoin(from, on), @From

Performs an inner join: combines the field values of two files. Each record in the joined files must have a matching field. This method is similar to a SQL92 inner join. See Joining data from multiple sources for more information.

from

The From class object. (@From)

The On class object. (@On)

LeftJoin

public LeftJoin(from, on), @From

Performs a left outer join: returns all values from an inner join as well as all values in the left file that do not match up with the right file. This method is similar to a SQL92 left outer join. See Joining data from multiple sources for more information.

from

The From class object. (@From)

The On class object. (@On)

Discussion

The fields declared in a From class record are the fields used by the Where class methods. The values passed to the lock and wait parameters of the From constructors are the same values used by the OPEN and READ statements. For example,

lock=Q_AUTO_LOCK
wait=-1

See LOCK and WAIT for a complete list of values.

In addition to the lock flags, you can also specify Q_NO_GRFA if you don’t want the Select to calculate a GRFA for each selected record and you don’t plan to use GRFAs. This can improve performance of the Select. When using Q_NO_GRFA with a lock qualifier, you must use a bitwise OR operation. For example,

lock=Q_AUTO_LOCK|Q_NO_GRFA

If a channel is specified but is not open, a “Channel has not been opened” error ($ERR_NOOPEN) will occur.

Specifying a filename and open options rather than a channel enables you to completely manage the open file channel from the Select class. The open_options are specified like they are on the OPTIONS qualifier for the OPEN statement (for example, “IO=mode[:submode]” to specify the open mode and submode). If an open mode is not specified on Windows and UNIX, and the file is an ISAM file, the default open mode is I:I; otherwise, the default is I:S.

A /nonkey_sequential channel always overrides key optimization. It does not determine the best choice, so make sure to check for performance if you use it. Keep in mind that using /nonkey_sequential results in an unordered selection, but you can use OrderBy.Ascending or OrderBy.Descending to order it. (You cannot, however, use OrderBy.AscendingKey or OrderBy.DescendingKey with a /nonkey_sequential channel.)

If channel is not specified, a channel is selected from the free channels, beginning with the channel maximum of 1024 and descending (1023, 1022, etc.) until an available channel is found. This channel is not accessible to any other I/O statement; any other use must be through Select methods. The channel is closed when the From class object is destroyed.

We strongly recommend that you don’t mix channels used for individual I/O operations (e.g., READ and STORE) with channels used with Select.From.

The following example opens the specified filename using the U:I open mode and with exclusive access. When fromObj is destroyed, the file will be closed.

fromObj = new From(filename, rec, "io=u:i/ex")

In Synergy .NET, the file is closed when either the finalizer is executed or the Dispose() method is explicitly called.

The exact time when the finalizer executes is nondeterministic and occurs on a different thread. If closing the file is time critical or if you are using xfServer, you must explicitly call Dispose() on the From object handle. Since this destroys the object (unlike setting a handle to ^NULL), all other references will then be invalid. It is your responsibility to make sure all other handles to the object, including Select objects using the same From object, don’t continue to use the object after it’s been disposed. When creating a From object inline (on the Select statement), the object is disposed when the Select object is disposed. One exception is FOREACH, where the Select object is disposed as well as the enumerator, as shown in the following example:

foreach rec in new Select(new From(myfile, rec, "/io=i:i"),   
  &     (where)(key.gt.100))
  nop