MOVE

This option causes operand2 to be rounded.

ROUNDED is ignored if operand2 is not numeric.

If operand2 is of format N or P and operand2 is specified more than once, ROUNDED is ignored for target operands with seven positions after the decimal point.

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

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 (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 (A) 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 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 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 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 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 format, the value is converted to alphanumeric format.

2. Any trailing blanks in operand1 are removed.

3. In the case of LEFT JUSTIFIED, any leading blanks in operand1 are also 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 http://icu.sourceforge.net/userguide/.

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.

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.

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.