MOVE

Command:

MOVE

Syntax:

MOVE <source-data> TO <target-variable>.

Description:

The MOVE statement copies the contents of a literal or variable, source-data, to the contents of the target-variable.

In the cases of an alphanumeric to alphanumeric, an alphanumeric to numeric, or a numeric to alphanumeric MOVE, if the length of the source-data contents is greater than the length of target-variable, target-variable is populated with the source-data characters from left to right, and the remaining source characters are discarded.

In the case of a numeric to numeric MOVE, if the length of the contents of source-data is greater than the length of target-variable, target-variable is populated as follows:

· Digits to the right of the decimal point are populated in target-variable from left to right, and remaining digits in the source-data decimal are discarded, for example:

If var1 is defined as PIC 9.99,

MOVE 5.432 TO var1

will place 5.43 in var1.

· Digits to the left of the decimal point are populated in target-variable from right to left, and remaining higher digits in the source-data are discarded, for example:

If var1 is defined as PIC 9.99,

MOVE 65.432 TO var1

will place 5.43 in var1.

Besides simple moves, MOVE also allows a group item to be moved to another group item, or a group item to be moved to an elementary item. MOVE also permits both source and target variables to use positional string referencing; refer to the section titled Manipulating CobolScript Variables in Chapter 8 for further details.

Example Usage:

Simple MOVE:

MOVE var1 TO var2.

MOVE with positional referencing of source variable:

MOVE var1(1:2) TO var3.

MOVE with positional referencing of target variable:

MOVE `test` TO var5(start_position:length).

See Also:

SET

Sample Program:

MOVE.CBL

Variables

Variables are information holders. In CobolScript, variables come in five basic forms, each of which has its own characteristics and utility. These five forms are:

· Elementary data items, which can be either numeric or alphanumeric;

· Group-level data items;

· FILLER variables, which are really a special category of elementary data item;

· REPLICA variables;

· OCCURS clause variables.

No matter what the form, a variable must first be defined in a program, and then, as the term variable implies, the variable’s contents can be assigned and reassigned throughout the body of a program. In CobolScript, these value assignments are done with VALUE clauses and assignment statements. VALUE clauses are optional components of elementary data item variable definitions that establish an initial value for a variable; assignment statements are any procedure statements that modify a variable’s contents.

A variable definition must follow certain rules of syntax, which are described below for each of the variable forms. A variable definition may be placed anywhere within a CobolScript program, meaning that variable definitions are not restricted to the Data Division as they are in COBOL. However, you should not define the same variable more than once within a program.

In CobolScript, variable names are not case sensitive, so WS-VAR, ws-var, and Ws-Var will all be treated internally as the same variable. For this reason, only one of these names should be defined in a program. Similarly, two variables that have the same alphanumeric name and differ only by underscore and dash separators within the variable name, such as WS-VAR and WS_VAR, will be treated interchangeably by certain CobolScript commands and should not both be defined in a single program.

The Elementary Data Item

An elementary data item (also referred to as a ‘subvariable’ or just ‘elementary item’) is any basic numeric or alphanumeric variable. An elementary data item cannot have subvariable components. The syntax of a normal elementary data item variable definition is:

<level-number> <variable-name> PIC <picture-clause> [VALUE <value-literal>].

The level-number is a one- or two-digit number from 1 to 99. Think of the level number as representing the outline position of a variable; the lower the level number, the higher the variable’s rank in the outline, with 1 being the highest level. So long as you have defined at least one variable with a level of 1 in your program, the variables with level numbers greater than 1 will all be subvariables. This is best illustrated with an example:

1 text_input PIC X(40).

1 group_variable.

2 components.

3 component_1 PIC X(12).

3 component_2 PIC $,999.99.

2 val_1 PIC 99.

1 input_1 PIC X(25).

In the variable definitions above, text_input is both an elementary data item, because it doesn’t have any subvariables beneath it, and is a level 1 variable. The variable group-variable is a group-level data item (explained in the subsequent section), which has two subvariables, components and val_1. The variable components is a group item itself, and has two subvariables, each of which are elementary items. The variable val_1 is an elementary data item, as is input_1.

The variable-name of an elementary data item is the name that will be used throughout the program to reference this particular variable.

The elementary data item variable’s type, format, and length are all determined by the value of the picture-clause that immediately follows the PIC keyword. In CobolScript, all elementary item variables are assigned a fixed number of bytes according to the size specified in the picture clause, so you must allocate sufficient space for your variables when you create their picture clauses; otherwise, the variable values will be truncated and information will be lost. A picture clause can be of two basic types: numeric (PIC 9 format) or alphanumeric (PIC X format). The various picture clause formats, and their meaning, are explained fully in Appendix E, CobolScript Picture Clauses.

If you want to initialize the elementary data item variable to a value at the time you define it, you can include the VALUE keyword and follow it with a value-literal to assign to the variable. The value literal must be of a type that matches the picture type of the variable; in other words, a variable with a numeric picture clause must be assigned a numeric value literal, and a variable with an alphanumeric picture clause must be assigned an alphanumeric literal. See the preceding section of this chapter for more information on literals.

These are some example elementary item variable definitions:

1 string_variable PIC X(10) VALUE `abcdefghij`.

1 input_var PIC XX.

1 num_variable PIC $,999.99 VALUE 679.

The Group-Level Data Item

A group-level data item (also referred to as a ‘gldi’ or just ‘group item’) is a hierarchical parent variable that is made up of other variables known as subvariables or component variables. Group items are similar to record variables or data structures in other programming languages; they’re useful because they enable you to reference and transfer whole groups of variables by citing a single, succinct variable name. In CobolScript, group items are also used to define file records. See the Data and Copybook Files section of this chapter for more information on file records.

The syntax of a group-level data item variable definition is:

<level-number> <variable-name>.

<subvariable-definition>.

.

.

.

As in elementary items, the level-number of a gldi indicates the variable’s position in the hierarchy; see the definition of level number for elementary data items for more information.

The variable-name of a group item is the name assigned to the variable, just as in elementary data items.

In group items, no PIC or VALUE clauses are allowed. This is because a gldi’s structure is defined solely by its subvariable-definitions. A group-level data item’s subvariables can be group items themselves, making possible multiple levels of grouping, or the subvariables can be elementary data item variables.

Below is a standard group-level data item variable definition. In this example, group_variable is the group item, and is composed of two elementary items:

1 group_variable.

5 component_1 PIC XXX VALUE `mS1`.

5 component_2 PIC $,999.99.

The FILLER Variable

The FILLER variable is a special type of elementary data item; it should only be used as a subvariable to a group item, because it is always given the name FILLER, and cannot be directly referenced. The syntax of a FILLER variable definition is:

<level-number> FILLER PIC <picture-clause> VALUE <value-literal>.

The level-number and picture-clause are the same as those for a normal elementary data item, except FILLER variables should never be level 1 variables (because they must be subvariables).

A VALUE clause should almost always be specified for a FILLER variable, since FILLERs generally act as constants in a program. In cases where the FILLER variable is just acting as a placeholder, a VALUE clause may not be necessary.

Once defined, FILLER variables can only be referenced and modified indirectly, through references to their parent variable. They should be used in cases where there is no need for a direct reference, such as when a component of a group item remains static throughout the program. In the example below, a FILLER variable is one of three subvariables that comprise the group item variable group_variable:

1 group_variable.

5 component_1 PIC XXX VALUE `mS1`.

5 FILLER PIC X(n) VALUE ` has a dollar value of `.

5 component_2 PIC $,999.99.

Using PIC X(n) with FILLER variables

The special picture clause PIC X(n) can (and generally should) be used with any alphanumeric FILLER variable for which you specify a VALUE clause. PIC X(n) automatically assigns a length to the FILLER variable based on the length of the VALUE clause, so that you don’t have to calculate the variable length yourself when creating the picture clause. For example, in group_variable above, the FILLER variable is automatically assigned a length of 23 characters because the value clause is 23 characters long.

For more information on PIC X(n), see Appendix E, CobolScript Picture Clauses.

Implied PIC X(n) FILLER variables

FILLER variables using PIC X(n) can also be defined with a shorthand notation that eliminates the FILLER keyword, picture clause, and VALUE keyword. This is best illustrated with an example:

1 group_variable.

5 `Enter your name here: `.

In group_variable above, there is a single FILLER variable, with a value of `Enter your name here: `. The above gldi is the exact equivalent of the following:

1 group_variable.

5 FILLER PIC X(n) VALUE `Enter your name here: `.

This shorthand may only be used when the FILLER variable’s value is an alphanumeric that is set off by delimiters.