HELP
An object that allows the user to
conditionally retrieve records from a data
set.

USE
Use From DataSet to find and retrieve from a
data set either one record or all records
that meet the constraints of a logical
expression formula.  If the record retrieved
meets the constraints of the query
expression, the record is output on the Rec
output pin.

The default expression in the Formula
field is 1, (true).  Thus, either the first
record found (One), or all records in the
data set (All) will be output.

If you want to test values in record
fields, you must use the form Rec.A for field
A, Rec.B for field B, and so forth.  For
example, the expression:

Rec.A<10

tests each record to see if field A is
less than ten.  If Get records:  One is
specified, the first record in the dataset
with field A less than 10 will be output on
Rec.  If Get records:  All is specified, all
records with field A less than 10 will be
output.  Note that the entire record will be
output.

The following control pins may be added:

* File Name - This control pin allows the
user to change the name of the file from
which the records will be read.

* Rewind - This control pin "rewinds" the
From DataSet file so that it can be re-read
from the beginning of the file.

* Formula - This control pin allows the user
to change the formula which is used to
determine which records read from the file
will be output by the device.

LOCATION
I/O ==> From DataSet

OPEN VIEW PARAMETERS

* From DataSet - Click on the name field to
display a dialog box, then select the name of
the file that contains the DataSet.

* Get Records - Select One or All:

 * If One is selected, the first record found
in the data set that meets the constraints of
the selection formula will be output, and
From DataSet will stop executing.  When One
is selected, the output shape is always a
scalar.

 * If All is selected, all records found in
the data set that meet the constraints of the
selection formula will be output.  The output
shape will always be an array.  From DataSet
will stop executing when it reaches the end
of the file.

* Formula - Enter a mathematical expression
to test the records in the data set.  Either
the first One, or All records that satisfy
the expression will be output, depending on
the Get Records selection.  The default
expression is 1 (true).

NOTES
You may use any valid mathematical expression
in the conditional formula.  You may add
additional inputs for use in the expression,
just as for a Formula object.  If you want to
test values in record fields, express them as
Rec.A, Rec.B, and so forth.  The expression
can be fairly complex, for example:

Rec.A > Rec.B AND Rec.C < 2.3

You must observe the normal stipulations
for determining True or False for conditional
expressions:

* For any relational test (for example,
equality between two operands), if one
operand is an array, the other must be either
a scalar or an array of the same size and
shape.  If the first operand is equal to the
second, the result is True; otherwise it is
False.

* If both operands are of type Coord, they
must have all of their independent variables
and dependent variables match exactly for the
result to be True.  If independent variables
do not match, an error is returned.  Complex,
PComplex, and Spectrum operands must have
both parts match for the operation to return
True.  Enums are converted to Text for
comparison.

* Arrays must have all the respective values
of both operands equal for the operation to
return True.

You may wish to bring in a DataSet (an
array of records) from a file, edit it, and
then save it back to the file.  This can be
accomplished with a From DataSet, a Record
Constant using the Default Value input pin,
and a To DataSet.  See Record Constant for
more information.

You may add an EOF output pin to this
object.  When the object executes and there
are no records meeting the query expression
constraints, or you are already at the end of
the DataSet, this pin will fire.  Otherwise,
an End of file with no Data Found error will
result when this condition occurs.

If you have multiple From DataSet objects
reading from the same file, they will share
the file pointer.  That is, all of the
objects read sequentially through the file,
no matter how many objects there are reading
the file.  See From File for more detail.

SEE ALSO
Build Record, Record Constant, To DataSet,
and UnBuild Record.
