Reference modification
Reference modification is the COBOL name for a substring: a field, a pair of parentheses, a start position and a length. It is the tool for a fixed-width record, where every field is at a position the specification gives and no delimiter exists.
A window into a field
Ten letters, and three windows into them:
IDENTIFICATION DIVISION.
PROGRAM-ID. REFMOD.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 TEXT-F PIC X(10) VALUE "ABCDEFGHIJ".
01 PART-F PIC X(4) VALUE SPACES.
01 TAIL-F PIC X(6) VALUE SPACES.
PROCEDURE DIVISION.
DISPLAY "whole [" TEXT-F "]".
DISPLAY "3 to 6 [" TEXT-F(3:4) "]".
DISPLAY "8 on [" TEXT-F(8:) "]".
MOVE TEXT-F(2:4) TO PART-F.
DISPLAY "moved [" PART-F "]".
MOVE TEXT-F(5:6) TO TAIL-F.
DISPLAY "tail [" TAIL-F "]".
MOVE "X" TO TEXT-F(1:1).
DISPLAY "after [" TEXT-F "]".
STOP RUN.
cobc -x -free -Wall -o refmod refmod.cob
./refmod
whole [ABCDEFGHIJ]
3 to 6 [CDEF]
8 on [HIJ]
moved [BCDE]
tail [EFGHIJ]
after [XBCDEFGHIJ]
The start position is one-based, so (3:4) is the third character and four characters in all: CDEF. A window with the length left out runs to the end of the field, so (8:) is HIJ. The window is not a new field: the last statement wrote one character into the first position of the original, and the original changed.
Reading and writing through the window
A reference-modified field may sit on either side of a MOVE, and the rules of the move apply to the window and not to the whole field: a four-character window into a four-character receiver is a copy, and a single character moved in replaces one byte.
That makes the statement the tool for editing a fixed layout. A code that lives in positions 10 to 13 is RECORD-F(10:4) on both sides, and a program that changes it writes MOVE "NEW " TO RECORD-F(10:4) without rebuilding the rest of the record. What it must not do is write a longer value into a shorter window: the extra characters are cut, silently, exactly as a MOVE into a short field is.
The bounds of a literal window
A start and a length written as literals are known at compile time, and the compiler checks them. A window that reaches past the end of the field is an error:
IDENTIFICATION DIVISION.
PROGRAM-ID. BOUNDS.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 TEXT-F PIC X(10) VALUE "ABCDEFGHIJ".
PROCEDURE DIVISION.
DISPLAY "[" TEXT-F(5:10) "]".
STOP RUN.
cobc -x -free -Wall -o bounds bounds.cob
bounds.cob:9: error: length of 'TEXT-F' out of bounds: 10
7 |
8 | PROCEDURE DIVISION.
9 > DISPLAY "[" TEXT-F(5:10) "]".
10 | STOP RUN.
11 | <EOF>
Five plus ten is fifteen in a field of ten. The message names the length that does not fit and the field, and it is one of the few COBOL errors that points at a mistake a reader can also see without running the program.
A start that is computed
When the start comes from a field, the compiler cannot check it, and the run does not either:
IDENTIFICATION DIVISION.
PROGRAM-ID. RUNTIME2.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 TEXT-F PIC X(10) VALUE "ABCDEFGHIJ".
01 PART-F PIC X(4) VALUE SPACES.
01 START-F PIC 9(2) VALUE 9.
PROCEDURE DIVISION.
MOVE TEXT-F(START-F:4) TO PART-F.
DISPLAY "[" PART-F "] hex " FUNCTION HEX-OF(PART-F).
STOP RUN.
cobc -x -free -Wall -o runtime2 runtime2.cob
./runtime2
[IJ ] hex 494A0000
Nine plus four is thirteen in a field of ten, and the program reads the two characters that exist and two bytes that follow the field. The hex is the honest view: 49 4A are I and J, and 00 00 are the storage of the next field, all zeroes. Nothing was reported, and the value is wrong.
The lesson is the same as the one about the loop counter: the program has to check a position it computed before it uses it, with an IF on the start and the length, or with a window that is a field of its own. A reference modification is fast and exact inside the field and undefined beyond it.
Exercises
- Print TEXT-F(10:1) and TEXT-F(11:1) in separate programs. Which one builds, and which one does not?
- Move "XYZ" into TEXT-F(9:4). What does the field hold, and did the build say anything?
- Use a reference modification to print the second half of the field without writing the number 6 anywhere. Which form of the window allows that?
- Take the computed start from a field and make it 8 instead of 9. What does the hex show, and why are there no zeroes in it?
Questions
A new set of questions in a new order every time. Choose one answer for each, then check.
-
What does
TEXT-F(3:4)select?Answer
Four characters starting at the third
The first number is a one-based start and the second is a count, so three and four is CDEF in ABCDEFGHIJ.
-
What does
TEXT-F(8:)select?Answer
Everything from the eighth character to the end
An omitted length runs to the end of the field; the start alone is enough.
-
Can a reference-modified field be the target of a MOVE?
Answer
Yes: a move into the window writes those bytes of the field
The window denotes real storage, so it can be read and written like a field of its width.
-
What happens when a computed start and length reach past the end of the field?
Answer
The program reads or writes the storage after the field, with no error
The compiler checks literals only; a computed position is the program responsibility, and GnuCOBOL does not check it at run time.
-
What does this program print?
IDENTIFICATION DIVISION. PROGRAM-ID. Q1. DATA DIVISION. WORKING-STORAGE SECTION. 01 TEXT-F PIC X(10) VALUE "ABCDEFGHIJ". PROCEDURE DIVISION. DISPLAY "[" TEXT-F(3:4) "]". STOP RUN.Answer
[CDEF]
The window starts at the third character and is four long, so it is C, D, E and F.
-
What does this program print?
IDENTIFICATION DIVISION. PROGRAM-ID. Q2. DATA DIVISION. WORKING-STORAGE SECTION. 01 TEXT-F PIC X(10) VALUE "ABCDEFGHIJ". PROCEDURE DIVISION. DISPLAY "[" TEXT-F(8:) "]". STOP RUN.Answer
[HIJ]
The window starts at the eighth character and has no length, so it runs to the end of the ten-byte field.
-
What does this program print?
IDENTIFICATION DIVISION. PROGRAM-ID. Q3. DATA DIVISION. WORKING-STORAGE SECTION. 01 TEXT-F PIC X(10) VALUE "ABCDEFGHIJ". 01 PART-F PIC X(4) VALUE SPACES. PROCEDURE DIVISION. MOVE TEXT-F(2:4) TO PART-F. DISPLAY "[" PART-F "]". STOP RUN.Answer
[BCDE]
Four characters from the second are B, C, D and E, copied into a receiver of exactly that size.
-
What does this program print?
IDENTIFICATION DIVISION. PROGRAM-ID. Q4. DATA DIVISION. WORKING-STORAGE SECTION. 01 TEXT-F PIC X(10) VALUE "ABCDEFGHIJ". PROCEDURE DIVISION. MOVE "X" TO TEXT-F(1:1). DISPLAY "[" TEXT-F "]". STOP RUN.Answer
[XBCDEFGHIJ]
The one-byte window covers the first character, so the move replaces A and leaves the other nine bytes.
-
What is the first line of the compiler output for this program?
IDENTIFICATION DIVISION. PROGRAM-ID. Q5. DATA DIVISION. WORKING-STORAGE SECTION. 01 TEXT-F PIC X(10) VALUE "ABCDEFGHIJ". PROCEDURE DIVISION. DISPLAY "[" TEXT-F(5:10) "]". STOP RUN.Answer
error: length of 'TEXT-F' out of bounds: 10
Five plus ten reaches past the ten-byte field, and the compiler names the field and the length that does not fit.
-
What does this program print?
IDENTIFICATION DIVISION. PROGRAM-ID. Q6. DATA DIVISION. WORKING-STORAGE SECTION. 01 TEXT-F PIC X(10) VALUE "ABCDEFGHIJ". 01 PART-F PIC X(4) VALUE SPACES. 01 START-F PIC 9(2) VALUE 9. PROCEDURE DIVISION. MOVE TEXT-F(START-F:4) TO PART-F. DISPLAY FUNCTION HEX-OF(PART-F). STOP RUN.Answer
494A0000
The window starts at the ninth byte, so two letters are inside the field and the two bytes after it are read as zeros.
The code on this page was built with cobc (GnuCOBOL) 3.2.0 and run on Alpine Linux 3.24.3 (x86_64) in a Docker container.
Article author: Arthur Isaev