MOVE Statement

Procedure Definition Language Statements › MOVE Statement

MOVE Statement

The MOVE statement transfers data from a source to a target. The MOVE statement does not modify the value of the source and the original data remains in the source after it is moved to the target.

The statement MOVE TO Numeric Field has the following format:

MOVE {alphanumeric_expression| numeric_expression | NULL}  TO numeric_field ...

The statement MOVE TO Alpha Field has the following format:

MOVE {alphanumeric_expression| numeric_field | numeric_literal | group | NULL}  TO alphanumeric_field ...

The statement MOVE TO Group has the following format:

MOVE group1 TO group2{BY NAME| POSITION} [USING {$EDIT| $STRING } [RULES]]

MOVE (MOVE TO Numeric Field)

Moves a value to an elementary numeric field according to the following rules:

If both the source and target are numeric fields, the value is moved by alignment of an implicit decimal point, with truncation of low‑order decimal digits (when necessary). If high order significant digits are lost, an overflow error condition is raised and the error procedure is executed (see the Error Procedure topic in this chapter.

If the target is a date field, then the source cannot be an alphanumeric

When a value from an alphanumeric source is moved to a non‑date numeric target, the value of the alphanumeric source is first converted to numeric by applying the $NUMBER function to the alphanumeric item (see the $NUMBER function). If the source contains non‑numeric characters, an execution‑time error occurs.

If the source is the keyword NULL or evaluates to the null value, the target field must be nullable. It is set to the null value.

MOVE (MOVE TO Alpha Field)

Moves a value to an elementary alphanumeric field according to the following rules:

If both the source and target are alphanumeric fields, the value is moved as follows:
If both source and target are the same length, an exact copy is made.
If the length of the value of the source is longer than the target, truncation occurs on the right.
If the target is longer than the length of the value of the source, then the result is padded on the right with blanks.
If the target is a variable length field, then the length of the target becomes the length of the source, up to the maximum length defined for the variable length field.
If the source is a variable length field, then its length is the length of the current value. This length is compared with the target as described above and is padded or truncated.
If the source is a non‑alpha group, it is treated as an alphanumeric field whose length is the same as the size of the group. However, subordinate numeric fields are not converted. The hexadecimal values are simply moved.

You cannot specify restricted groups. For more information, see the Restrictions on Non‑Alpha Groups topic in the "Procedure Definition Language Concepts and Language Elements" chapter.

PDF can convert low values moved to an alphanumeric field in a panel with the $LOW function (or by some other means) to special characters. For a description of the Input Fill Character, see the Creating Panel Definitions Guide.

When low values are moved to an alphanumeric panel field, CA Ideal considers the field EMPTY. The next TRANSMIT fills this EMPTY field with the Output Fill Character when it is next displayed.

When a value from a non‑date numeric source is moved to an alphanumeric target, the data in the numeric source is first converted to alphanumeric by applying the $STRING function (see the section on the $STRING function in "Symbolic Debugger commands" chapter). If you do not want to use the $STRING rules, you can specify a $EDIT function in a numeric expression as the source. Use the default PIC or specify one of the other edit patterns. See the section on $EDIT in the "Symbolic Debugger commands" chapter).

If the conversion results in a value that is longer than the target field after any leading blanks were removed, digits are truncated from the right to fit. For example, if NUM is a three‑digit numeric field and STR is a two‑character alphanumeric field, the expression results in STR having a value of '12' if NUM has a value of 123. If, however, NUM has a value of 12 or 1, STR has a value of '12' or '1' respectively.

MOVE NUM TO STR

You cannot move an arithmetic expression or numeric function to an alphanumeric target without first moving it to a numeric target.

You cannot move a value directly from a date type source to an alphanumeric target. Use the $DATE function as an alphanumeric expression to convert the date field as part of the MOVE.

If the source is the keyword NULL or evaluates to the null value, the target field must be nullable. It is set to the null value. If a null value expression is moved to a target that is not nullable, it causes a runtime error.

MOVE (MOVE TO Group)

Moves data from one group to another. The following rules apply:
Both the source and the target must be groups.
Moving a value from each field in the source group to a field in the
target group is subject to the rules for moving values described in the Move TO Alpha and Move TO Group formats.
When values are moved from a non‑alpha group to an alpha target, the default is to convert numeric data to alphanumeric by applying a STRING function. You can specify that a $EDIT function to use instead. See the following options USING $EDIT RULES and USING $STRING RULES.

BY NAME

Moves the value from each field in the source group to an identically named field in the target group, if one exists. OCCURs in the respective groups (if any) must be compatible. Only values from fields that have the same names are subordinate to the respective groups and are elementary are moved. Redefinitions in the sending group are not eligible sources; however, redefinitions in the receiving group are eligible targets. A compile‑time error message is issued if the number of occurrences does not match. A runtime error occurs if the number of occurs depending on or parameter field occurrences does not match.

For example, if the source group is

Level          Field               Occur
1              A
  2             B                  2
  2             C                  2

and the target group is,

Level            Field               Occur
1                X
  2              Y                    2
    3              B 
    3              C

then the statement,

MOVE A TO X BY NAME

moves the values of the Bs and Cs in the source group to fields with corresponding names in the target group.

BY POSITION

Moves the value of the first elementary field in the source group item to the first elementary field in the target group item, regardless of its name; the second to the second, and so on. The group structures must be compatible as follows:

Structures must have the same number of elementary fields.

OCCURs values must be identical and at the same relative level.

Test structures for compatibility with the following steps:

Remove any OCCURs values from the high level group entries in both the source and target.
Remove any fields or groups with REDEFs in both the source and target. If a group is removed, all its subordinate fields are also removed.
Remove each subordinate group entry except any that have OCCURs.
Renumber the levels for the fields that are left.

Note: No field values are moved unless the structures that remain after this test is applied are compatible.

USING $EDIT RULES

In a group move only, specifies to convert numeric fields to alphanumeric by applying a $EDIT function with an edit pattern of PIC 9(n), where n is the number of integer places in the field. The default uses a $STRING conversion.

USING $STRING RULES (Default)

In a group move only, performs numeric conversion using the $STRING rules.

Examples

MOVE QUANTITY_ORDERED * UNIT_PRICE TO CHARGE

MOVE CURRENT_AMOUNT TO AMOUNT_RQRD
MOVE $NUMBER (PAY_AMT) TO PAY_AMT_NUMERIC
MOVE ((Y + Z)*W)/(A ‑ B) TO Z
MOVE A + ($REMAINDER(M,N) ‑ $ROUND(J,1))/3.6 TO L
MOVE $STRING (X,Y,Z) TO ALPHA

Examples: MOVE BY NAME

Structures:

    Level  Field   Type  Int   Chars   Occur   Value/Comments
1)   1      A      
     2      B                           3
     3      C      X           2        4
     3      D      X           2
     3      E      X           2

    Level  Field   Type  Int   Chars   Occur   Value/Comments
2)   1      X
     2      C       X           2       4
     2      D       X           2

Statement a:

MOVE B(1) TO X BY NAME

Result a:

The values of all occurrences of C(1,n) and D(1) in structure 1 are moved to C and D in structure 2 (B is a group).

Statement b:

MOVE A TO X BY NAME

Result b:

Invalid MOVE because structures 1 and 2 do not match. The number of subscripts for C in structure 1 is 2, and the number for C in structure 2 is 1.

Example

Structures:

    Level  Field   Type  Int   Chars   Occur   Value/Comments
1)    1      A      
      2      B                           3
      3      C      X           2        5
      3      D      X           2
      3      E      X           2

    Level  Field   Type  Int   Chars   Occur   Value/Comments
2)    1      X
      3     C       X           2       4
      3     D       X           2

Statement:

MOVE B(1) TO X BY NAME

Result:

Invalid MOVE because OCCUR of 5 for C in structure 1 and OCCUR of 4 for C in structure 2 cause the structures not to match.

Example

Structures:

    Level  Field   Type  Int   Chars   Occur   Value/Comments
1)    1      A      
      2      B                           3
      3      C      X           1        4
      3      D      X           1
      3      E      X           1

    Level  Field   Type  Int   Chars   Occur   Value/Comments
2)   1      AA
     2      BB      X           1
     3      E       X           1       3
     4      C                           4
     2      D       X                   3

Statement a:

MOVE A TO BB BY NAME

Result a:

Moves only the values of all occurrences of C because it is the only elementary field that has the same name in both structures. Although E is part of BB, it is not moved because it is a group.

Statement b:

MOVE A TO AA BY NAME

Result b:

Moves the values of all occurrences of C and D because both C and D are the only elementary fields that have the same names in both structures.

Examples: MOVE BY POSITION

This first example of MOVE BY POSITION illustrates the rules by which data structures are tested for compatibility using the rules outlined in the description of MOVE BY POSITION. Subsequent examples are simpler and their explanations assume the reader understands the rules illustrated in this first detailed example.

Structures:

    Level  Field   Type  Int   Chars   Occur   Value/Comments
1)  2      A                            2      REDEFINED Y
    3      B      X           5         5
    3      C      X           5
    3      D                                   REDEFINES C
    4      E      X           2
    4      F      X           3
    3      G      N           2

    Level  Field   Type  Int   Chars   Occur   Value/Comments
2)    2      M                          2      REDEFINES Q
      3      N
      4      O      X           5       5
      4      P      X           4              REDEFINES P
      4      Q      X           4       
      4      R      X           1

Statement:

MOVE A TO M BY POSITION

Result:

This is a valid move. The structures are tested for compatibility with the following steps:

Removes any OCCURs values from group entries in both the source and target. After applying 1., the OCCUR values 2 in structure 1 and 2 in structure 2 are removed.
Removes any fields or groups with REDEFs in both the source and target. If a group is removed, all its subordinate fields are also removed. After applying 2., the fields D, E and F in structure 1 and Q in structure 2 are removed.
Removes each subordinate group entry except any that has OCCURs. After applying 3., the field N in structure 2 is removed.

Finally, the levels are renumbered for the remaining fields. After applying 4., the result is:

    Level  Field   Type  Int   Chars   Occur   Value/Comments
1)   1      A      
     2      B       X           5        5
     2       C      X           5
     2       G      N           2

    Level  Field   Type  Int   Chars   Occur   Value/Comments
2)   1      M
     2      O       X           5       5
     2      P       X           4
     2      R       X           1

The move is now formed as follows: The values of all occurrences of B are moved to O, the value of C is moved to P, the value of G is moved to R.

If field O had an OCCURs of 4 instead of 5 after the test for compatibility, the structures would not match and the MOVE statement would be invalid.

Example

Structures:

    Level  Field   Type  Int   Chars   Occur   Value/Comments
1)   1      A      
     2      B       N           2
     2      C       X           3
     2      D       X           3

    Level  Field   Type  Int   Chars   Occur   Value/Comments
2)   1      E
     2      F       N           2
     2      G                   
     3      H      X           3
     3      I      X           3

Statement:

MOVE A TO E BY POSITION

Result:

Valid MOVE BY POSITION: The value of B moves to F, the value of C moves to H, the value of D moves to I (G is a group).

Example
(Invalid Move)

Structures:

    Level  Field   Type  Int   Chars   Occur   Value/Comments
1)   1      A      
     2      B       N           3
     2      C       X           2      2
     2      D       X           2      2

    Level  Field   Type  Int   Chars   Occur   Value/Comments
2)   1      E
     2      F       N           3
     2      G                           2
     3      H       X           2
     3      I       X           2

Statement:

MOVE A TO E BY POSITION

Result:

Invalid move because of different structure. Although there are the same number of elementary fields, the depth of the structure in E is 3 and that of A is only 2. Altering structure E according to the rules does not alter the structure since G (a lower‑level group) has an OCCURs clause.

Example

    Level  Field   Type  Int   Chars   Occur   Value/Comments
1)   1      A
     2      B        X          3
     2      C        X          3
2)   1      D 
     2      E                   2
      3     F        X          3
      3     G        X          3

Statement:

MOVE A TO E(1) BY POSITION

Result:

Valid MOVE statement: The value of B moves to F(1) and the value of C moves to G(1). Even though E is a repeating group, the subscript indicates that only the value of the first occurrence of the group participates in the move. This, in effect, makes the two structures compatible.

Non‑Alpha to Alpha Group Move

The following examples show group moves of non‑alpha groups to alphanumeric structures:

Structures:

    Level  Field      Type  Int   Chars   Occur   Value/Comments
1)   1     NUM_DATE
     2     NUM_YY      U     Z     2               86
     2     NUM_MM      U     Z     2               02
     2     NUM_DD      U     Z     2               09
     1     NUM_SSN                      
     2     SSN1        U     Z     3               36
     2     SSN2        U     Z     2               8
     2     SSN3        U     Z     4               22

    Level  Field      Type  Int   Chars   Occur   Value/Comments
2)   1     GROUP_DATE   
     2     ALPHA_YY    X           2
     2     ALPHA_MM    X           2
     2     ALPHA_DD    X           2
     1     ALPHA_DAT   X           6
     1     WORK_SSN
     2     SSN1        X           3
     2     SSN2        X           2
     2     SSN3        X           4
     1     ALPHA_SSN   X           11

Statements:

MOVE NUM_DATE TO GROUP_DATE BY POSITION USING $EDIT RULES
       :Result is 860209
MOVE NUM_DATE TO GROUP_DATE BY POSITION USING $STRING
       :Result is 86 2 9
MOVE NUM_DATE TO ALPHA_DAT
       :Result is 860209
MOVE NUM_SSN TO WORK_SSN BY NAME USING $EDIT
       :Result is 036080022
MOVE $EDIT(WORK_SSN,PIC='XXX‑XX‑XXXX') TO ALPHA_SSN
       :Result is 036‑08‑0022

Note: The numeric fields in the groups NUM_DATE and NUM_SSN are defined as unsigned, zoned decimals so that, when their hexadecimal values are copied into the corresponding alpha fields, the results represent the original values. This is not the case if the fields are signed numerics or are in binary or packed internal format.