ILE COBOL Language Reference

Reference Modification

Reference modification resembles the use of substringing in other computer languages. Reference modification defines a data item by specifying a starting position and length for the item.

Format
 
>>-+-data-name-1-----------------------------------------+------>
   '-FUNCTION--function-name-1--+----------------------+-'
                                |    .------------.    |
                                |    V            |    |
                                '-(----argument-1-+--)-'
 
>--(--leftmost-character-position:--+--------+--)--------------><
                                    '-length-'
 
 
data-name-1
Must refer to a data item whose implicit or explicit usage is DISPLAY, DISPLAY-1, or NATIONAL. Data-name-1 can be qualified or subscripted.

+-------------------------------IBM Extension--------------------------------+

Must not refer to a Boolean data item.

Must not refer to an item that is defined using the TYPE clause.

+----------------------------End of IBM Extension----------------------------+

function-name-1
Must be an alphanumeric, DBCS, or national function including its arguments.

For more information, see Intrinsic Functions.

argument-1
Argument-1 must be an identifier, literal (other than a figurative constant), or arithmetic expression.
leftmost-character-position
Must be an arithmetic expression. The evaluation of the leftmost-character-position must result in a positive nonzero integer that is less than or equal to the number of characters in the data item referenced by data-name-1 or function-name-1.
length
Must be an arithmetic expression.

The sum of leftmost-character-position and length minus the value one must be less than or equal to the number of characters in the data item referenced by data-name-1 or function-name-1. If length is omitted, then the length used is equal to the number of characters in the data item referenced by data-name-1 or function-name-1 plus one minus the leftmost-character-position. The evaluation of length must result in a positive nonzero integer.

Note:
If the arithmetic expression creates a fixed-point non-integer, truncation occurs, resulting in an integer. If the arithmetic expression creates a floating-point non-integer, rounding occurs, resulting in an integer.

+-------------------------------IBM Extension--------------------------------+

For DBCS or national data items, position and length refer to the number of double byte characters.

+----------------------------End of IBM Extension----------------------------+

Reference modification is generally allowed anywhere an identifier referencing an alphanumeric, DBCS, or national data item is allowed.

+-------------------------------IBM Extension--------------------------------+

A data item of class date-time cannot be reference modified.

+----------------------------End of IBM Extension----------------------------+

Each character of a data item referenced by data-name-1 or function-name-1 is assigned an ordinal number incrementing by one from the left-most position to the right-most position. The left-most position is assigned the ordinal number of one. If the data description entry for data-name-1 contains a SIGN IS SEPARATE clause, the sign position is assigned an ordinal number within that data item.

Reference modification creates a unique data item which is a subset of the data item referenced by data-name-1 or by function-name-1 and its arguments. This unique data item is considered an elementary item without the JUSTIFIED clause.

When data-name-1 is reference-modified, the unique data item has the same class and category as that defined for the data item referenced by data-name-1; however, if the category of data-name-1 is numeric, numeric-edited, alphanumeric-edited, or external floating-point, the unique data item has the class and category alphanumeric.

When a function is reference-modified, the unique data item has the class and category of alphanumeric, DBCS, or national depending on the function arguments.

If length is not specified, the unique data item created extends from and includes the character identified by the leftmost-character position up to and including the right-most character of the data item referenced by data-name-1 or function-name-1.

Related Information:

Evaluation of Operands

Reference modification for an operand is evaluated as follows:

Reference Modification Example

This example transfers the first 25 characters in the variable whole-name to the variable last-name.

MOVE whole-name(1:25) TO last-name

Range Errors

An out-of-range reference modification component, such as a leftmost-character-position of zero, causes system message to be generated. This is the same message that signals errors in subscript ranges and character-string boundaries. (This message is generated only when the RANGE option is specified on the CRTCBLMOD or CRTBNDCBL command.)

Restrictions on Reference Modification

+-------------------------------IBM Extension--------------------------------+

The INDICATORS phrase does not support reference modification.

+----------------------------End of IBM Extension----------------------------+

The following restrictions apply to the statements listed:

Statement
Restriction

STRING
You cannot reference modify identifier-3.

UNSTRING
You cannot reference modify identifier-1.

START
You can reference modify last occurrence of data-name-1 only.


[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]