- byName
- When you specify byName, data is written from
each field in the source to a same-named field in the target. The operation
occurs in the order in which the fields are in the source.
Source and target
can be as follows:
- source
- One of these:
- A dynamic array of fixed records; but the array is valid only if the target
is not a record
- A record
- A fixed record
- A structure field with a substructure
- A structure-field array with a substructure; but this array is valid only
if the target is not a record
- A dataTable
- A form
A fixed-structure field whose name is an asterisk (*) is not available
as a source field, but any named fields in a substructure of that field are
available.
- target
- One of these:
- A dynamic array of fixed records; but this array is valid only if the
source is not a record
- A record
- A fixed record
- A structure field with a substructure
- A structure-field array with a substructure; but this array is valid only
if the source is not a record
- A dataTable
- A form
An example statement is as follows:
move myRecord01 to myRecord02 byName;
The operation is not valid in any of these cases:
- Two or more fields in the source have the same name;
- Two or more fields in the destination have the same name;
- The source field is either a multidimensional structure-field array or
a one-dimensional structure-field array whose container is an array; or
- The target field is either a multidimensional structure-field array or
a one-dimensional structure-field array whose container is an array.
The operation works as follows:
- In a simple case, the source is a fixed structure but is not itself an
array element, and the same is true of the target. These rules apply--
- If no arrays are involved, the value of each subordinate field in the
source structure is copied to the same-named field in the target structure.
- If an array of structure fields is being copied to an array of structure
fields, the operation is treated as a move for all:
- The elements of the source field are copied to successive elements of
the target field
- If the source array has fewer elements than the target array, processing
stops when the last element of the source array is copied
- In another case, the source or target is a record. The fields of the source
are assigned to the same-named fields in the target.
- A less simple case is best introduced by example. The source is an array
of 10 fixed records, each of which includes these structure fields:
10 empnum CHAR(3);
10 empname CHAR(20);
The target is a fixed structure that
includes these structure fields:
10 empnum CHAR(3)[10];
10 empname CHAR(20)[10];
The operation copies the value of field empnum in the first
fixed record to the first element of the structure-field array empnum; copies
the value of field empname in the first fixed record to the first element
of the structure-field array empname; and does a similar operation for each
fixed record in the source array.
The equivalent operation occurs if
the source is a single fixed record that has a substructure like this:
10 mySubStructure[10]
15 empnum CHAR(3);
15 empname CHAR(20);
- Finally, consider the case in which the source is a fixed record that
includes these structure fields:
10 empnum CHAR(3);
10 empname CHAR(20)[10];
The target is a form, fixed record, or structure field that
has the following substructure:
10 empnum char(3)[10];
10 empname char(20);
The value of field empnum is copied from the source to
the first element of empnum in the target; and the value of the first element
of empname is copied from the source to the field empname in the target.
- byPosition
- The purpose of byPosition is to copy data from
each field in one structure to the field at the equivalent position in another.
Source
and target can be as follows:
- source
- One of these:
- A dynamic array of fixed records; but the array is valid only if the target
is not a record
- A record
- A fixed record
- A structure field with a substructure
- A structure-field array with a substructure; but this array is valid only
if the target is not a record
- A dataTable
- target
- One of these:
- A dynamic array of fixed records; but this array is valid only if the
source is not a record
- A record
- A fixed record
- A structure field with a substructure
- A structure-field array with a substructure; but this array is valid only
if the source is not a record
- A dataTable
When you move data between a record and a fixed structure,
only the top-level fields of the fixed structure are considered. When you
move data between two fixed structures, only the lowest-level (leaf) fields
of either structure are considered.
The operation is not valid if the
source or target field is a multidimensional structure-field array, or a one-dimensional
structure field array whose container is an array.
The operation works
as follows:
- In a simple case, the source is a fixed structure but is not itself an
array element, and the same is true of the target. These rules apply--
- If no arrays are involved, the value of each leaf field in the source
structure is copied to the leaf field in the target structure at the corresponding
position.
- If an array of structure fields is being copied to an array of structure
fields, the operation is treated as a move for all:
- The elements of the source field are copied to successive elements of
the target field
- If the source array has fewer elements than the target array, processing
stops when the last element of the source array is copied
- In another case, the source or target is a record. The top-level or leaf
fields of the source (depending on the source type) are assigned to the top-level
or leaf fields in the target (depending on the target type).
- A less simple case is best introduced by example. The source is an array
of 10 fixed records, each of which includes these structure fields:
10 empnum CHAR(3);
10 empname CHAR(20);
The target is a fixed structure that
includes these structure fields:
10 empnum CHAR(3)[10];
10 empname CHAR(20)[10];
The operation copies the value of field empnum in the first
fixed record to the first element of the structure-field array empnum; copies
the value of field empname in the first fixed record to the first element
of the structure-field array empname; and does a similar operation for each
fixed record in the source array.
The equivalent operation occurs if
the source is a single fixed record that has a substructure like this:
10 mySubStructure[10]
15 empnum CHAR(3);
15 empname CHAR(20);
- Finally, consider the case in which the source is a fixed record that
includes these structure fields:
10 empnum CHAR(3);
10 empname CHAR(20)[10];
The target is a form, fixed record, or structure field that
has the following substructure:
10 empnum char(3)[10];
10 empname char(20);
The value of field empnum is copied from the source to
the first element of empnum in the target; and the value of the first element
of empname is copied from the source to the field empname in the target.
- for all
- The purpose of for all is to assign values to
all elements in a target array.
Source and target can be as follows:
- source
- One of these:
- A dynamic array of records, fixed records, or primitive variables
- A record
- A fixed record
- A structure field with or without a substructure
- A structure-field array with or without a substructure
- A primitive variable
- A literal or constant
- target
- One of these:
- A dynamic array of records, fixed records, or primitive variables
- A structure-field array with or without a substructure
- An element of a dynamic or structure-field array
The move statement in this
case is equivalent to multiple assignment statements,
one per target array element, and an error occurs if an attempted assignment
is not valid. For details on validity, see Assignments.
If a
source or target element has a fixed structure, the move statement
treats that structure as a field of type CHAR unless the top level of the
structure specifies a different primitive type. When for all is
in use, the move statement gives no consideration
to substructure.
If the source is an element of an array, the source
is treated as an array in which the specified element is the first element,
and previous elements are ignored.
If the source is an array or an
element of an array, each successive element of the source array is copied
to the sequentially next element of the target array. Either the target array
or the source array can be longer, and the operation ends when data is copied
from the last element having a matching element in the other array.
If
the source is neither an array nor an element of an array, the operation uses
the source value to initialize every element of the target array.
- for count
- The purpose of for count is to assign
values to a sequential subset of elements in a target array. Examples are
as follows:
The operation works as follows:
- If the source is neither an array nor an element of an array, the operation
uses the source value to initialize elements of the target array.
- If the source an array, the first element of that array is the first in
a set of elements to be copied. If the source is an element of an array, that
element is the first in a set of elements to be copied.
- If the target is an array, the first element of that array is the first
in a set of elements to receive data. If the target is an element of an array,
that element is the first in a set of elements that receives data.
The
count value indicates how many target elements are to receive
data. The value can be any of these:
- An integer literal
- A variable that resolves to an integer
- A numeric expression, but not a function invocation
The move statement is equivalent to
multiple assignment statements, one per target array
element, and an error occurs if an attempted assignment is not valid. For
details on validity, see Assignments.
If a source or target element
has an internal structure, the move statement treats
that structure as a field of type CHAR unless the top level of that structure
specifies a different primitive type. When for count is
in use, the move statement gives no consideration
to substructure.
When the source and target are both arrays, either
the target array or the source array can be longer, and the operation ends
after the first of two events occurs:
- Data is copied between the last elements for which the operation is requested;
or
- Data is copied from the last element having a matching element in the
other array.
When the source is not an array, the operation ends after the
first of two events occurs:
- Data is copied to the last element for which the operation is requested;
or
- Data is copied to the last element in the array.
If the source is a record array (or an element of one), the target
must be a record array. If the source is a primitive-variable array (or an
element of one), the target must be either a primitive-variable array or a
structure-field array. If the source is a structure-field array (or an element
of one), the target must be either a primitive-variable array or a structure-field
array.