move

The EGL move statement copies data in any of three ways. The first option copies data byte by byte; the second (called by name) copies data from the named fields in one structure to the same-named fields in another; and the third (called by position) copies data from each field in one structure to the field at the equivalent position in another.

The following general rules apply:
  • If the source value is one of these, the default is to copy data byte by byte--
    • A primitive variable
    • A field that is in a fixed structure
    • A literal
    • A constant

    Otherwise, the default is to copy data by name.

  • Moves are checked for field-to-field 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 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.

Syntax diagram for the move statement

The statement is best understood by reference to the following categories:

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 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 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.

Related reference
Arrays
Assignments

Feedback
(C) Copyright IBM Corporation 2000, 2005. All Rights Reserved.