Reference Modification

Reference modification is a syntax for referencing a portion (substring) of a data item. The reference defines a temporary, unique data item. Reference modification may be used anywhere in the Procedure Division.

Note: This manual entry includes code examples and highlights for first-time users following the General Rules section.

General Format

data-name ( leftmost-position : [length] )

Syntax Rules

  1. leftmost-position and length are arithmetic expressions.
  2. Unless otherwise specified, reference modification is allowed anywhere a data item of the class alphanumeric is permitted.
  3. data-name may be qualified or subscripted. Reference modification is done after both qualification and subscripting.

General Rules

  1. Each character of the data item referenced by data-name is assigned an ordinal number starting at one for the leftmost position and incrementing by one for each character in the item.
  2. Reference modification for an operand is evaluated as follows:
    1. If subscripting is specified, the reference modification is evaluated immediately after the evaluation of the subscripts.
    2. If subscripting is not specified, the reference modification is evaluated at the time subscripting would have been evaluated if subscripts had been specified.
  3. Reference modification creates a unique data item which is a subset of data-name. This unique data item is defined as follows:
    1. The evaluation of leftmost-position specifies the leftmost character of the unique data item relative to the start of data-name. Evaluation of leftmost-position must result in an integer greater than zero and less than or equal to the number of characters contained in data-name.
    2. The evaluation of length specifies the size of the unique data item. The evaluation of length must result in a positive integer. The sum of leftmost-position and length must be less than or equal to the number of characters contained in data-name, plus one. If length is not specified, the unique data item extends through the rightmost character of data-name.
  4. The unique data item is considered an elementary data item without the JUSTIFIED clause. It has the same class and category as data-name except that categories numeric, numeric edited, and alphanumeric edited are treated as class and category alphanumeric.
  5. If the reference modification start or length parameter is out of range for the item it references, a runtime error occurs. How the runtime responds depends on the value of the WARNINGS configuration variable. By default, the runtime attempts to correct the error (see rule 6, below), and the warning message Reference modifier range error is displayed or sent to the error file. This error is an intermediate runtime error that can trigger the execution of installed error procedures.
  6. By default, the runtime silently corrects reference modification range errors by applying the following rules:
    • A start reference less than 1 is treated as 1. For example, var(0:3) is treated as var(1:3).
    • A length reference less than 0 is treated as 0. Moving a zero-byte item is equivalent to moving spaces to the destination item. A zero-byte destination is not affected by the move. In a STRING statement, a length of zero for a string source is treated as 1, not 0.
    • A start plus length reference that is past the end of the item is treated as meaning to the end of the item. For example, if the var is a PIC X(5) item, var(4:23) is treated as var(4:2).

    The WARNINGS runtime configuration variable provides some control over how the runtime handles reference modification range errors.

CAUTION:
Reference modification is allowed on source-item and dest-item of a Format 1 MOVE statement. However, when reference modification is used, source-item and dest-item should not reference the same item (or memory location). See general rule 7 of the MOVE Statement in Procedure Division.

Code Examples

Reference modification is akin to substringing in other programming languages. Reference modification is very useful for referencing a component part of a composite string. For example, it might be used to reference the area code digits of a 10-character string containing a phone number (area code + seven digits): 

01  PHONE-NUMBER  PIC 9(10) VALUE 3017728134.
{ . . . }
PHONE-NUMBER (1:3).
*The reference modification begins at position 1
*of string PHONE-NUMBER and has a length of 3.
*The reference modification value = "301"

For the following code examples, assume these data items: 

01 ACCOUNT-CODE PIC X(20) VALUE "AB700648xSMITHxxCLA1".
01 ACCOUNT-NAME PIC X(6)  VALUE ALL SPACES.
01 ACCT-CLASS-1 PIC X(4)  VALUE "CLA1".

Code example 1: 

MOVE ACCOUNT-CODE (10:6) TO ACCOUNT-NAME.
*This reference modification selects the 
*characters that form the name portion of 
*ACCOUNT-CODE.  The reference starts at position 
*10 and has a length of 6 characters.
*The ACCOUNT-CODE substring = "SMITHx"

Code example 2: 

IF ACCOUNT-CODE (17:) = ACCT-CLASS-1 THEN
*When the reference modification does not 
*include a length, the reference begins at the 
*value specified and extends to the end of the 
*data item.
*The ACCOUNT-CODE substring = "CLA1"

Highlights For First-time Users

  1. Reference modification may be used anywhere in the program where an alphanumeric data item may be referenced.
  2. A reference modification does not create a persistent data item. Unless the result of the reference modification is assigned to a compatible data object, you can refer to the value of the reference modification later in the program only by repeating the reference modification.
  3. The reference-modified data item is treated as an alphanumeric field.
Parent topic: Data Names