STRING with POINTER
A COBOL text field cannot grow. A line assembled from a name, a space and a surname is therefore built in a field that is wide enough from the start, and STRING is the statement that writes the parts one after another and tells the program where it stopped.
STRING builds a line
Two fields with padding of their own, a literal space between them, and a pointer that starts at one:
IDENTIFICATION DIVISION.
PROGRAM-ID. STRING.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 FIRST-F PIC X(6) VALUE "ADA".
01 LAST-F PIC X(8) VALUE "LOVELACE".
01 OUT-F PIC X(20) VALUE SPACES.
01 PTR-F PIC 9(2) VALUE 1.
PROCEDURE DIVISION.
STRING FIRST-F DELIMITED BY SPACE
" " DELIMITED BY SIZE
LAST-F DELIMITED BY SPACE
INTO OUT-F
WITH POINTER PTR-F
END-STRING.
DISPLAY "[" OUT-F "]".
DISPLAY "pointer " PTR-F.
STOP RUN.
cobc -x -free -Wall -o string string.cob
./string
[ADA LOVELACE ]
pointer 13
Without the delimiters the result would be ADA LOVELACE, because the fields are six and eight bytes and the padding is part of them. The delimiter says what part of the sending field to use, and the pointer says where the next write goes.
DELIMITED BY SIZE and SPACE
DELIMITED BY SIZE sends the whole field, padding included; it is what the literal space in the program uses, because a one-byte space is all of itself. DELIMITED BY SPACE sends the field up to its first space, so a padded name arrives without its tail of blanks.
The second form has a trap that costs a day when a name has two words. The city below is a ten-byte field holding NEW YORK, and the space in the middle is the first one the delimiter finds:
IDENTIFICATION DIVISION.
PROGRAM-ID. CITY.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 CITY-F PIC X(10) VALUE "NEW YORK".
01 OUT-F PIC X(10) VALUE SPACES.
01 PTR-F PIC 9(2) VALUE 1.
PROCEDURE DIVISION.
STRING CITY-F DELIMITED BY SPACE
INTO OUT-F
WITH POINTER PTR-F
END-STRING.
DISPLAY "[" OUT-F "]".
DISPLAY "pointer " PTR-F.
STOP RUN.
cobc -x -free -Wall -o city city.cob
./city
[NEW ]
pointer 04
Four positions were written: three letters and a terminator that is not there. The pointer is one past the last character, so it says the next write would go to position four, and the rest of the field is the spaces it had before. A field whose internal spaces are significant needs DELIMITED BY SIZE and a deliberate trim, not the space delimiter.
WITH POINTER
The pointer is a numeric field the program owns. It starts at 1, the first write goes to that position, and after the statement it holds one past the last byte written. That single number is how a program appends in several statements and how it knows the length of what it built.
Two rules follow. The pointer has to be initialised to 1 before the first STRING, because a field of zeros points at position zero and the statement reports an overflow; and it may not point into the middle of a field by accident, so a program that reuses the pointer for a second line sets it again. The length of the line is PTR-F - 1, which is why the value is one more than the reader expects.
ON OVERFLOW
The receiving field can be too small, and the statement stops at its end instead of writing past it:
IDENTIFICATION DIVISION.
PROGRAM-ID. OVERFLOW.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 PART-F PIC X(4) VALUE "ABCD".
01 OUT-F PIC X(6) VALUE SPACES.
01 PTR-F PIC 9(2) VALUE 1.
PROCEDURE DIVISION.
STRING PART-F DELIMITED BY SIZE
PART-F DELIMITED BY SIZE
INTO OUT-F
WITH POINTER PTR-F
ON OVERFLOW DISPLAY "overflow, pointer " PTR-F
END-STRING.
DISPLAY "[" OUT-F "]".
DISPLAY "pointer " PTR-F.
STOP RUN.
cobc -x -free -Wall -o overflow overflow.cob
./overflow
overflow, pointer 07
[ABCDAB]
pointer 07
Six bytes fit, the seventh does not, and the branch runs with the pointer already at seven. The output is a prefix of the intended line, and the program knows it is a prefix because the branch ran. Without the clause the same truncation happens in silence, which is the failure mode of a report column that is one character too narrow.
UNSTRING, which is the next lesson, is the statement that takes a line apart; together the two are the whole of fixed-width text handling in COBOL.
Exercises
- Build the full name with DELIMITED BY SIZE for both fields and print it. How many spaces are between the names now?
- Start the pointer at 11 and string the surname first. What does the output look like, and why?
- Build a line of exactly twenty characters from four fields and print the pointer. What does the pointer hold, and did the overflow branch run?
- String a city with a space in it twice, once with each delimiter, and compare the two lines. Which one is right for an address?
Questions
A new set of questions in a new order every time. Choose one answer for each, then check.
-
What does DELIMITED BY SPACE send?
Answer
The field up to its first space
The space is the delimiter, so the transfer stops there, which is why an internal space truncates the value.
-
What does the pointer hold after a STRING?
Answer
One past the last byte written
The next write goes to the pointer value, so it ends one past the last written byte and the length is one less.
-
When does the ON OVERFLOW branch run?
Answer
When a sending field does not fit the rest of the receiver
The statement writes until the receiver is full, and the branch reports that at least one byte of a part was lost.
-
What does this program print?
IDENTIFICATION DIVISION. PROGRAM-ID. Q1. DATA DIVISION. WORKING-STORAGE SECTION. 01 FIRST-F PIC X(6) VALUE "ADA". 01 LAST-F PIC X(8) VALUE "LOVELACE". 01 OUT-F PIC X(20) VALUE SPACES. 01 PTR-F PIC 9(2) VALUE 1. PROCEDURE DIVISION. STRING FIRST-F DELIMITED BY SPACE " " DELIMITED BY SIZE LAST-F DELIMITED BY SPACE INTO OUT-F WITH POINTER PTR-F END-STRING. DISPLAY "[" OUT-F "]". STOP RUN.Answer
[ADA LOVELACE ]
Both names lose their padding, the literal adds one space, and the twelve written bytes leave eight spaces of the receiver.
-
What does this program print?
IDENTIFICATION DIVISION. PROGRAM-ID. Q2. DATA DIVISION. WORKING-STORAGE SECTION. 01 FIRST-F PIC X(6) VALUE "ADA". 01 LAST-F PIC X(8) VALUE "LOVELACE". 01 OUT-F PIC X(20) VALUE SPACES. 01 PTR-F PIC 9(2) VALUE 1. PROCEDURE DIVISION. STRING FIRST-F DELIMITED BY SPACE " " DELIMITED BY SIZE LAST-F DELIMITED BY SPACE INTO OUT-F WITH POINTER PTR-F END-STRING. DISPLAY "[" PTR-F "]". STOP RUN.Answer
[13]
Twelve bytes were written, so the pointer is one past the last, at thirteen.
-
What does this program print?
IDENTIFICATION DIVISION. PROGRAM-ID. Q3. DATA DIVISION. WORKING-STORAGE SECTION. 01 CITY-F PIC X(10) VALUE "NEW YORK". 01 OUT-F PIC X(10) VALUE SPACES. 01 PTR-F PIC 9(2) VALUE 1. PROCEDURE DIVISION. STRING CITY-F DELIMITED BY SPACE INTO OUT-F WITH POINTER PTR-F END-STRING. DISPLAY "[" OUT-F "]". STOP RUN.Answer
[NEW ]
The first space in the city is the delimiter, so only NEW is written and the receiver keeps its seven spaces.
-
What does this program print?
IDENTIFICATION DIVISION. PROGRAM-ID. Q4. DATA DIVISION. WORKING-STORAGE SECTION. 01 PART-F PIC X(4) VALUE "ABCD". 01 OUT-F PIC X(6) VALUE SPACES. 01 PTR-F PIC 9(2) VALUE 1. PROCEDURE DIVISION. STRING PART-F DELIMITED BY SIZE PART-F DELIMITED BY SIZE INTO OUT-F WITH POINTER PTR-F END-STRING. DISPLAY "[" OUT-F "]". STOP RUN.Answer
[ABCDAB]
Eight bytes are offered to a six-byte receiver, so the first six are written and the second copy is cut.
-
What does this program print?
IDENTIFICATION DIVISION. PROGRAM-ID. Q5. DATA DIVISION. WORKING-STORAGE SECTION. 01 PART-F PIC X(4) VALUE "ABCD". 01 OUT-F PIC X(6) VALUE SPACES. 01 PTR-F PIC 9(2) VALUE 1. PROCEDURE DIVISION. STRING PART-F DELIMITED BY SIZE PART-F DELIMITED BY SIZE INTO OUT-F WITH POINTER PTR-F ON OVERFLOW DISPLAY "overflow, pointer " PTR-F END-STRING. STOP RUN.Answer
overflow, pointer 07
The eighth byte has nowhere to go, so the branch runs with the pointer already one past the end of the six-byte receiver.
-
A program strings a name with DELIMITED BY SPACE and the name is "MARY ANN". What arrives in the receiver?
Answer
MARY, because the space inside the name is the delimiter
The delimiter ends the transfer at the first space, so the second word is never written and the line is wrong without an error.
-
A STRING statement leaves the pointer at 1 because the program forgot to set it. What happens?
Answer
Nothing is written, and the statement reports an overflow
The pointer is a field the program owns; a zero or an unset value is not a valid position, and the statement cannot write there.
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