move

The EGL move statement copies data, either byte by byte or by name. The latter operation copies data from the named items in one structure to the same-named items in another.

The following general rules apply:

• If the source value is an item, literal, or constant, the default is to copy data byte by byte. If the source value is a form, record, or record array, the default is to copy items by name.

• Moves are checked for item-to-item compatibility. The rules for truncation, padding, and type conversion are the same as those detailed for the assignment statement; however, the overall behavior of the move statement is different from that of the assignment statement.

• When you are working with dynamic arrays, the last element in the array is determined by the array's current size. The move statement never adds an element to an array; to expand a dynamic array, use the array-specific functions appendElement or appendAll, as described in Arrays.

source

One of these:

• An array of any kind

• A record (including an element of a record array)

• A form

• An item with or without a substructure

• A literal or constant

target

One of these:

• An array of any kind

• A record (including an element of a record array)

• A form

• An item with or without a substructure

byName (the default if the source is a form, record, or record array)

When you specify byName, data is written from each item in the source to a same-named item in the target:

• In the simplest case, the source is a form or record or an item with a substructure, but does not include an item array and is not itself an array element. These rules apply--
  • If the target is a form, a record, or an item with a substructure (and if no arrays are involved), the value of each subordinate item in the source structure is copied to the same-named item in the target structure. The operation occurs in the order in which the items appear in the source structure. The operation is not valid if two or more items in the source or target structure have the same name.

  • If the target is an array of records or structure items, the operation is equivalent to a series of move statements that each assigns the same content to successive elements of the target array. Specifically, the named areas in the source substructure are copied to successive elements of the target array, into the same-named areas in the substructure of each element.

  • If the target is a data item, an array of data items, an item without a substructure, or an array of items that are each without a substructure, the operation is not valid.

• A less simple case is best introduced by example.

  Consider an array of 10 records, each element of which includes the following structure items:

    empnum  CHAR(3);
    empname CHAR(20); 

  You can move that array to a form or record that includes the following set of structure items:

    empnum CHAR(3)[10];
    empname CHAR(20)[10];

  The effect is as follows:

  • Moves the value of item empnum in the first record-array element to the first element of the structure-item array empnum

  • Moves the value of item empname in the first record-array element to the first element of the structure-item array empname

  • Does a similar operation for each element of the source array

  The equivalent operation occurs if the source is a single record that has a substructure like this:

    10 mySubStructure[10]
      15 empnum  CHAR(3);
      15 empname CHAR(20);    

  The general rule is as follows: When multiply occurring items are in source and target but the structure of the source is different from the structure of the target, the operation acts as if array indexes were assigned to the elementary items in both source and target.

• If the source is an element of a record array or of a structure-item array whose elements each have a substructure, these rules apply--
  • If the target is a form, a record, or an item with a substructure, the value of each subordinate item in the source structure is copied to the same-named item in the target structure. The operation occurs in the order in which the items appear in the source structure. The operation is not valid if two or more items in the source or target structure have the same name.

  • If the target is an array of records or structure items, the source is treated as an array in which the specified element is the first element, and previous elements are ignored. The operation is equivalent to a series of move statements that each assigns content to successive elements of the target array. Specifically, the named areas in the source substructure of each successive element of the source array are copied to successive elements of the target array, into the same-named areas in the substructure of each target element.

    Either the target array or the array that begins with the source element 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 target is a data item, an array of data items, an item without a substructure, or an array of items that are each without a substructure, the operation is not valid.

• If the source is a record array or a structure-item array whose elements each have a substructure, these rules apply--
  • If the target does not include an array and is a form, a record, or an non-array item with a substructure, the first element of the source array is considered but subsequent elements are ignored. The value of each subordinate item in the first element is copied to the same-named item in the target structure. The operation occurs in the order in which the items appear in the source structure. The operation is not valid if two or more items in the source or target structure have the same name.

  • If the target is an array of records or structure items, the operation is equivalent to a series of move statements that each assigns content to successive elements of the target array. Specifically, the named areas in the source substructure of each successive element of the source array are copied to successive elements of the target array, into the same-named areas in the substructure of each target element.

    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 target is a data item, an array of data items, an item without a substructure, or an array of items that are each without a substructure, the operation is not valid.

• If the source is a literal, a constant, an item without a substructure, or an array of such items, an error occurs.

An item whose name is an asterisk (*) is not available as a source item, but any named items in a substructure of that item are available.

An example is as follows:

  move myRecord01 to myRecord02 byName;

for all (the default if the source is an item, literal, or constant)

The purpose of for all is to assign values to all elements in a target 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 an internal 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 a record array (or an element of one), the target must be a record array. If the source is a data-item array (or an element of one), the target must be either a data-item array or a structure-item array. If the source is a structure-item array (or an element of one), the target must be either a data-item array or a structure-item 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 next statement moves "abc" to elements 7, 8, and 9 in target:

    move "abc" to target[7] for 3

• The next statement moves elements 2, 3, and 4 from source into elements 7, 8, and 9 in target:

    move source[2] to target[7] for 3

The source can be an item, literal, constant, record, array, or element of an array:

• 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 is an element of an array, that element is the first in a set of elements to be copied.

• If the source an array, the first element of that array is the first in a set of elements to be copied.

The target can be a record, array, or element of an array:

• If the target is an element of an array, that element is the first in a set of elements that receives data.

• If the target is an array, the first element of that array is the first in a set of elements to receive 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 data-item array (or an element of one), the target must be either a data-item array or a structure-item array. If the source is a structure-item array (or an element of one), the target must be either a data-item array or a structure-item array.

Related reference
Arrays
Assignments