HELP
An object that allows you to modify a field
of an existing record.

USE
Use Set Field to modify the value of a field
of an existing record.  The Set Field object
is actually an assignment object that assigns
the value specified by the right-hand
expression to the field specified by the
left-hand expression.  The value in the right
hand expression can evaluate to a scalar, an
array, another record, or a field in a
record.

Set Field is a short-cut for un-building a
record, changing one field, and re-building
the data into a record.  Note that the output
terminal name must match the name of the
input record to be modified.  Also, the left
and right-hand expression results must match
in type and shape.  You cannot use Set Field
to change the "schema" (type and shape) of
the input record.

LOCATION
Data ==> Access Record ==> Set Field

OPEN VIEW PARAMETERS
* Left-hand expression -- The left-hand
expression allows a subset of Formula
mathematical syntax, which allows you to
specify a field of a record.  The A.B dot
syntax, as well as a subset of the A[2]
sub-array syntax, is supported to specify a
particular field of the record to be changed.
See "Notes" below for further details of the
allowed syntax.

* Right-hand expression -- The right-hand
expression allows any mathematical expression
that is allowed in a Formula object.  This
expression has access to all input
containers, global variables, and functions.
The right-hand expression is evaluated and
the resulting value is stored in the field of
the record specified by the left-hand
expression.

NOTES
The name of the record output pin must match
the name of the input record to be modified,
and the left-hand expression must begin with
that name.  For example, if the record pins
are named Rec, the left-hand expression must
be something like Rec.A or Rec[1].  The
left-hand expression must be a single
expression that specifies which field of the
input container is to be modified.

There may be confusion over the names of
inputs, outputs, and record fields.  For
example, if the name of the record input pin
and the record output pin is Rec (they must
match), the expression Rec.A specifies the A
field in the input record.  On the other
hand, the expression A*2 refers to the A data 
input of the Set Field object.  Thus, 
Rec.B=A*2 sets the B field of the output 
record equal to twice the value of the 
A data input.  On the other hand,
Rec.B=Rec.A sets the B field of the output
record equal to the value of the A field of
the input record.

The complete input record container is
output on the record output pin, but the
specified field is modified.  For example,
suppose the input Rec is a record with two
fields x and y, where x is a Text scalar with
value "hello" and y is a Real scalar with the
value 1.2.  If the left-hand expression
specifies Rec.y, and the right-hand
expression evaluates to 5.6, the output
container will be a record with two fields x
and y, where x is a Text scalar with value
"hello" and y is a Real scalar with the value
5.6.

The field specified by the left-hand
expression and the result of the right-hand
expression must match in type and shape
("schema").  That is, the operation of the
Set Field object cannot change the schema of
the input record -- only the data in the
specified field can be changed.  For example,
suppose input Rec is a record with two fields
x (a Text scalar) and y (a Real scalar).  If
the left-hand expression specifies Rec.y, the
right-hand expression must result in either a
Real scalar, or something that can promote to
a Real scalar.  Otherwise, an error will
result.

Record arrays require special attention.
A record array is an array consisting of
individual record elements, each consisting
of fields.  You can use Set Field to change
one field of one element in a record array.
For example, if you create a record 1D array
and you want to change the f field of the
third record element of the array, specify
Rec[2].f (for a zero-based array) in the
left-hand expression.  In this case, the
result of the right-hand expression is placed
in the f field of the third element of the
record 1D array.  None of the other fields of
Rec[2] are changed, nor are any fields of the
other record elements of the array (for
example, Rec[0].f and Rec[1].f).

On the other hand, you can use Set Field
to modify a particular field in every record
element of a record array.  For example,
suppose you specify Rec.f in the left-hand
expression where Rec is a record 1D array
with n elements.  In this case, the result of
the right-hand expression is copied into
every Rec[x].f field, where x is from 0
through n-1.  In other words, the f field is
changed in every record element of the array.

The left-hand expression must be a single
expression specifying which part of the input
record is to be modified.  For example, Rec+2
and sine(Rec) are not valid as left-hand
expressions.  Also global variables are not
allowed in the left-hand expression.

The syntax allowed for the left-hand
expression is limited:

* The A.B dot sub-record syntax may be used
any number of times for record of record
containers (there is no limit on recursion).
Suppose that record A has a field b, which is
itself a record.  The record field b has a
field c, which is a record containing field
d.  To specify that lowest level field d, you
can use A.b.c.d as the left-hand expression.

* The A[x] sub-array syntax is more limited,
and may be used only once, before the last
dot.  For example, A.b.c[1].d is valid as a
left-hand expression, but A[2].b.c.d and
A[2].b[2].c are not allowed.  Also, A[1] and
A.b.c[1:2] are not allowed.  However, the
A[x] sub-array syntax, supported before the
last dot, does support the "colon and
asterisk" syntax.  For example 
A[1:2].b and a.b.c[2:*].d are valid 
left-hand expressions.

Note the difference between A[1].b and
A.b[1].  The first is a record 1D with a
field b.  The second is a scalar record
containing a field b, which is a 1D array.

SEE ALSO
Build Record, Formula, Get Field, Record
Constant, SubRecord, and UnBuild Record.
