MOVE

This option causes operand2 to be rounded.

ROUNDED is ignored if operand2 is not numeric or if the source operand has the same or less precision digits than the target operand.

See also Example 1 - Various Samples of MOVE Statement Usage.

operand1
operand2

operand1 is the source operand whose value is moved to the target operand operand2.

For the rules for data transfer and information on data conversion and transfer compatibility, see the section Data Transfer in the Programming Guide.

If operand2 is a dynamic variable, its length may be modified by the MOVE operation. The current length of a dynamic variable can be ascertained by using the system variable *LENGTH. For general information on the dynamic variable, see the section Using Dynamic and Large Variables in the Programming Guide.

A MOVE statement with multiple target operands is identical to the corresponding individual MOVE statements:

MOVE #SOURCE TO #TARGET1 #TARGET2

is identical to

MOVE #SOURCE TO #TARGET1 
MOVE #SOURCE TO #TARGET2

Without the SUBSTRING option, the whole content of a field is moved.

The SUBSTRING option allows you to move only a certain part of an alphanumeric/ Unicode or a binary field. After the field name (operand1) in the SUBSTRING clause, you specify first the starting position (operand3) and then the length (operand4) of the field portion to be moved.

If the underlying field format of operand1 is

• alphanumeric/Unicode (A) or binary (B), then the values supplied with operand3 or operand4 are considered as byte numbers;

• Unicode (U), then the values supplied with operand3 or operand4 are considered as number of Unicode code units; that is, as double-bytes.

For example, to move the 5th to 12th position inclusive of the value in a field #A into a field #B, you would specify:

MOVE SUBSTRING(#A,5,8) TO #B

If operand1 is a dynamic variable, the specified field portion to be moved must be within its current length; otherwise, a runtime error will occur.

Also, you can move a value of an alphanumeric/Unicode or binary field into a certain part of the target field. After the field name (operand2) in the SUBSTRING clause you specify first the starting position (operand5) and then the length (operand6) of the field portion into which the value is to be moved.

If the underlying field format of operand2 is

• alphanumeric/Unicode (A/U) or binary (B), then the values supplied with operand5 or operand6 are considered as byte numbers;

• Unicode (U), then the values supplied with operand3 or operand4 are considered as number of Unicode code units; that is, as double-bytes.

For example, to move the value of a field #A into the 3rd to 6th position inclusive of a field #B, you would specify:

MOVE #A TO SUBSTRING(#B,3,4)

If operand2 is a dynamic variable, the specified starting position (operand5) must not be greater than the variable's current length plus 1; a greater starting position will lead to a runtime error, because it would cause an undefined gap within the content of operand2.

If operand3/operand5 or operand4/operand6 is a binary variable, it may be used only with a length of less than or equal to 4.

If you omit operand3/operand5, the starting position is assumed to be 1. If you omit operand4/operand6, the length is assumed to range from the starting position to the end of the field.

If operand2 is a dynamic variable and the specified starting position (operand5) is the variable's current length plus 1, which means that the MOVE operation is used to increase the length of the variable, operand6 must be specified in order to determine the new length of the variable.

Note:
MOVE with the SUBSTRING option is a byte-by-byte move (that is, the rules described under Rules for Arithmetic Assignment in the Programming Guide do not apply).

This option is used to move individual fields contained in a data structure to another data structure, independent of their position in the structure.

A field is moved only if its name appears in both structures (this includes REDEFINEd fields as well as fields resulting from a redefinition). The individual fields may be of any format. The operands can also be views.

Note:
The sequence of the individual moves is determined by the sequence of the fields in operand1.

See also Example 2 - MOVE BY NAME Statement.

If the data structures contain arrays, these will internally be assigned the index (*) when moved; this may lead to an error if the arrays do not comply with the rules for assignment operations with arrays; see the section Processing of Arrays in the Programming Guide.

See also Example 3 - MOVE BY NAME with Arrays.

This option allows you to move the contents of fields in a group to another group, regardless of the field names.

The values are moved field by field from one group to the other in the order in which the fields are defined (this does not include fields resulting from a redefinition).

The individual fields may be of any format. The number of fields in each group must be the same; also, the level structure and array dimensions of the fields must match. Format conversion is done according to the rules for arithmetic assignment; see the section Rules for Arithmetic Assignments in the Programming Guide. The operands can also be views.

See also Example 4 - MOVE BY POSITION.

If an edit mask is specified for operand2, the value of operand1 will be placed into operand2 using this edit mask.

The edit mask can be considered as an input edit mask for operand2, that is used to specify at which positions in the alphanumeric/Unicode contents of operand1 the significant input data for operand2 can be found.

If the edit mask refers more characters or digits than existent in operand2, it is truncated accordingly. The length of operand1 may not be smaller than the length of the input value represented by the edit mask. If operand1 is longer than the edit mask length, all the overhanging data is ignored.

Under the pre-condition not to have an operand1 length larger than the edit mask length, you may regard a

MOVE EDITED operand1 TO operand2 (EM=value)

operation like the execution of

STACK TOP DATA operand1
INPUT operand2 (EM=value)

See also Example 1 - Various Samples of MOVE Statement Usage.

For details on edit masks, see the session parameter EM in the Parameter Reference.

For details on Unicode edit masks, see the session parameter EMU in the Parameter Reference.

If an edit mask is specified for operand1, the edit mask will be applied to operand1 and the result will be moved to operand2.

The edit mask can be considered as an output edit mask for operand1, that is used to create an alphanumeric/Unicode string with the layout and length described by the edit mask. Besides data characters or digits originating from operand1, you may include additional decoration characters into the output string.

If the edit mask refers more characters or digits than existent in operand1, it is truncated accordingly. The length of the created output string (resulting from operand1 value after the edit mask has been applied) must not exceed the length of operand2.

Under the pre-condition not to have an operand2 length smaller than the edit mask length, you may regard a

MOVE EDITED operand1 (EM=value) TO operand2

operation like a

WRITE operand1 (EM=value)

that does not write the output to the screen, but fills it into variable operand2.

See also Example 1 - Various Samples of MOVE Statement Usage.

For details on edit masks, see the session parameter EM in the Parameter Reference.

For details on Unicode edit masks, see the session parameter EMU in the Parameter Reference.

This option is used to cause the values to be moved to be left- or right-justified in operand2.

MOVE LEFT/RIGHT JUSTIFIED cannot be used if operand2 is a dynamic variable.

With MOVE LEFT JUSTIFIED, any leading blanks in operand1 are removed (blanks and binary zeros are removed) before the value is placed left-justified into operand2. The remainder of operand2 will then be filled with blanks. If the value is longer than operand2, the value will be truncated on the right-hand side.

With MOVE RIGHT JUSTIFIED, any trailing blanks in operand1 are truncated (blanks and binary zeros are removed) before the value is placed right-justified into operand2. The remainder of operand2 will then be filled with blanks. If the value is longer than operand2, the value will be truncated on the left-hand side.

See also Example 1 - Various Samples of MOVE Statement Usage.

When you use MOVE LEFT/RIGHT JUSTIFIED in conjunction with PM=I, the move is performed in the following steps:

1. If operand1 is not of alphanumeric/Unicode format, the value is converted to alphanumeric/Unicode format.

2. Any trailing blanks in operand1 are removed (blanks and binary zeros are removed).

3. In the case of LEFT JUSTIFIED, any leading blanks in operand1 are also removed (blanks and binary zeros are removed).

4. The value is reversed, and then moved to operand2.

5. If applicable, the remainder of operand2 is filled with blanks, or the value is truncated (see above).

This option is used to convert Unicode fields with potentially unnormalized content into the "Unicode Normalization Form C" (NFC). This composite form of a Unicode string does not contain combining sequences for characters which are available as pre-composed characters. See also: http://www.unicode.org/reports/tr15/#Canonical_Composition_Examples ("Normalization Forms D and C Examples").

Example:

MOVE NORMALIZED #SCR TO #TGT

operand1 contains the Unicode string to be converted.

operand2 receives the converted Unicode string.

This option converts a character string, encoded in one code page, into the equivalent character string of another code page.

Note:
Natural uses the International Components for Unicode (ICU) library for Unicode conversion. For more information, see the ICU User Guide at http://userguide.icu-project.org/.

operand1 contains the string to be converted.

As operand2, you specify the code page of operand1.

Can only be supplied if operand1 is of format A or B. See Note 1 and 3.

operand3 receives the converted string.

If the conversion result does not fit into the target field, the result is padded or truncated, respectively, and as padding character the blank of the resulting code page is used.

If the target field is defined as a dynamic variable, no padding or truncation is needed, since the length of the dynamic variable is automatically adjusted to the length of the conversion result.

As operand4, you specify the code page of operand3.

Can only be supplied if operand3 is of format A or B. See Note 1 and 3.

If you omit this clause, a Natural error message is returned if an error occurs.

If you specify the keyword GIVING, operand5 returns 0 or the Natural error code instead of the Natural error message.

If the target gets truncated, no Natural error message is given, but when the keyword GIVING is used, operand5 will contain an appropriate error code to indicate truncation.

The source operand contains the value to be moved.

All digits of a numeric operand including leading zeros are moved.

The target operand is not reset before the execution of the MOVE ALL operation. This is of particular importance when using the UNTIL option since data previously in operand2 is retained if not explicitly overlaid during the MOVE ALL operation.

The UNTIL option can be used to limit the MOVE ALL operation to a given number of positions in operand2. operand3 is used to specify the number of positions. The MOVE ALL operation is terminated when this value is reached.

If operand7 is greater than the length of operand2, the MOVE ALL operation is terminated when operand2 is full.

The UNTIL option may also be used to assign an initial value to a dynamic variable: if operand2 is a dynamic variable, its length after the MOVE ALL operation will correspond to the value of operand7. The current length of a dynamic variable can be ascertained by using the system variable *LENGTH.

For general information on dynamic variables, see Usage of Dynamic Variables.

Note:
The UNTIL option is not allowed when a SUBSTRING clause is used for the target operand.

The SUBSTRING clause enables you to select a fixed segment of the source or target variable in a MOVE ALL statement - whereas, without the SUBSTRING clause, the whole content of the source or target variable is processed.

operand3 and operand4 describe the start position and length of the operand1 segment used as source value. operand5 and operand6 describe the start position and length of the operand2 segment which is filled by the operation. If the start position (operand3 or operand5) is omitted, then position 1 is assumed by default. If the substring length (operand4 or operand6) is omitted, then the remaining length of the field is assumed.

If SUBSTRING is used for the source field, the start value and length (operand3 and operand4) must describe a data segment which is completely inside operand1.

If SUBSTRING is used for the target field the following rules apply:

• If operand2 is a fixed length variable, the range described by the start-value and length (operand5 and operand6) has completely to reside within the field extent.

• If operand2 is a dynamic length variable, the start value (operand5) can either point into or immediately behind the current field length (*LENGTH + 1). When the end of the SUBSTRING range is within the allocated field data, the operation is processed in the same way as for a fixed length field. When the SUBSTRING end exceeds the current field size, the dynamic variable is expanded to this extent.

See also Examples of SUBSTRING Clause Usage below.