move

The EGL move statement copies data in one of three ways:

byte by byte
by name, from the named fields in one structure to the same-named fields in another
by position, from each field in one structure to the field at the equivalent position in another

The following general rules apply:

Where appropriate, moves are checked for field-to-field compatibility. (This does not happen on byte-by-byte moves.) The rules for truncation, padding, and type conversion are the same as those detailed for an EGL assignment (see “Assignments”); however, the overall behavior of the move statement is different from that of an assignment.
When you work with dynamic arrays, the last element is determined by the current size of the array. The move statement never adds an element to an array; to expand a dynamic array, use the array-specific functions appendElement() or appendAll(); see “Arrays.”
If a source or target element has a fixed structure, the move statement treats that structure as a CHAR field unless the top level of the structure specifies a different primitive type. When for all or for count is in use, the move statement gives no consideration to substructure.

Syntax

The meaning of source and target varies according to the options for the statement. See the sections below for the different forms of the move statement.

move {justify = left} or move {justify = right}

justify is available for fixed length text type target variables, or fixed length text type arrays only. The justification operation occurs on the target after the source has been moved by the standard EGL operation, including any data type conversion. If a sub-string is specified on the target variable, then the justification modifies only the sub-stringed characters.

move {justify=left} a to b;

If left is specified, any leading blanks in the resulting target operand are removed and the value is shifted left. The source operand is not altered. Any needed characters on the right side of a fixed length target variable are inserted as spaces.

move {justify=right} a to b;

If right is specified, any trailing blanks in the resulting target operand are removed and the value is shifted right. The source operand is not altered. Any needed characters on the left side of a fixed length target variable are inserted as spaces.

move (no qualifier)

If you do not specify a byName or byPosition qualifier for the move statement, EGL moves the information byte-by-byte from the source to the target. The source must be assignment compatible with the target; for details, see “Assignment compatibility in EGL.”

move byName

In this form of the move statement, EGL assigns data from each field in the source to a field of the same name in the target. The operation occurs in the order in which the fields are in the source. The source must be assignment compatible with the target; for details, see “Assignment compatibility in EGL.”

The source or target can be any of the following:

A dynamic array of structured records
A non-structured record
A structured record
A named, structure field with a substructure
A structure field array with a substructure
A dataTable
A form

A structure field whose name is an asterisk (*) is not available as a source field, but any named field in a substructure of that field is available.

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 within an array
The target field is either a multidimensional structure-field array or a one-dimensional structure-field array within 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. The following rules apply:
- If you do not copy any arrays, the value of each subordinate field in the source structure is copied to the same-named field in the target structure.
- If you copy an array of structure fields to an array of structure fields, the operation is treated as a move for all. See "move with arrays" in this topic.
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 structured 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 move operation performs the following actions:
- copies the value of field empnum in the first structured record to the first element of the structure-field array empnum
- copies the value of field empname in the first structured record to the first element of the structure-field array empname
- repeats the process for each structured record in the source array, that is, fields in the second structured record in the source array are copied to the second element of the corresponding structure-field array, and so on.
The equivalent operation occurs if the source is a single structured 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 structured record that includes the following structure fields:
```
  10 empnum  CHAR(3);
  10 empname CHAR(20)[10]; 
```
The target is a form, structured record, or structure field that has the following substructure:
```
  10 empnum CHAR(3)[10];
  10 empname CHAR(20);
```
EGL copies the value of the empnum field from the source to the first element of empnum in the target, and copies the value of the first element of empname from the source to the field empname in the target. The move statement finishes here because no further copying can take place without changing the target empname to an array.

move byPosition

In this form of the move statement, EGL copies data from each field in the source to a field in the equivalent position in the target. EGL copies each field byte by byte, in order of its position in the source. The source must be assignment compatible with the target; for details, see “Assignment compatibility in EGL.”

Source or target can be any of the following kinds of data:

A dynamic array of structured records
A record
A structured record
A structure field with a substructure
A structure field array with a substructure
A dataTable

When you move data between a record and a structured record or field, only the top-level fields of the target are considered. When you move data between two structured records or fields, only the lowest-level (leaf) fields of either 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 within an array.

The operation performs the following actions:

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 you are not copying arrays, EGL copies the value of each leaf field in the source structure to the leaf field in the target structure at the corresponding position.
- If you copy structure fields to an array of structure fields, the operation is treated as a move for all. See "move with arrays" in this topic.
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).

The following example shows a move by position, where equivalent fields in the two records have different names:

record myCustomer type BasicRecord
  customerNumber CHAR(6);
  customerName CHAR(25);
end

record mySavedCustomer type BasicRecord
  savedCustomerNumber CHAR(6);
  savedCustomerName CHAR(25);
end

...

move myCustomer to mySavedCustomer byPosition;

move with arrays

When the target of the move statement is an array, you can assign values to all elements (for all) or a sequential subset of elements (for count).

The source can be one of the following kinds of data:

A dynamic array of records, structured records, or primitive variables
A record
A structured 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

The target can be one of the following kinds of data:

A dynamic array of records, structured 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 with arrays is equivalent to multiple EGL byte by byte copies, one per target array element, and an error occurs if an attempted copy is not valid. For details on validity, see Assignments.

When for all or for count is in use, the move statement ignores substructure.

If the source is an array or an element of an array, each successive element of the source array is copied to the next sequential 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 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 neither an array nor an element of an array, the operation uses the source value to initialize every element of the target 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.

If you use the for count method, the count indicates how many target elements are to receive data. The count can be any of the following values:

An integer literal
A variable that EGL evaluates as an integer
A numeric expression, but not a function invocation

Examples of the for count method are as follows:

The next statement moves "abc" to elements 7, 8, and 9 in the array 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;
```

move withV60Compat

The withV60Compat modifier is used in programs migrated from EGL version 6 and earlier, or from VisualAge® Generator programs. Do not use this modifier with new code.

Use this modifier when the variables that the move statement references are declared in a standalone function, where migration cannot determine the type of the variable. This option provides compatibility for a move statement without a modifier.

The withV60Compat modifier provides the following behavior:

If the source is one of the following values, the statement is treated like an assignment statement:
- A primitive variable
- A field in a fixed structure
- A literal
- A constant
Otherwise, the statement is treated as a move by name.

Compatibility

Table 1. Compatibility considerations for move
Platform	Issue
Rich UI	move is not supported except byName for flexible record.