UNSTRING with delimiters
UNSTRING is the other half of STRING: it takes one field and cuts it at a delimiter, writing the pieces into a list of receivers. It is the statement a COBOL program uses for a CSV line, a fixed header or anything else that arrives as one field.
Splitting a line
A line of four comma-separated values and four receiving fields, each with the length its piece needs:
IDENTIFICATION DIVISION.
PROGRAM-ID. SPLIT.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 LINE-F PIC X(24) VALUE "ADA,LOVELACE,LONDON,1815".
01 NAME-1 PIC X(10) VALUE SPACES.
01 NAME-2 PIC X(10) VALUE SPACES.
01 CITY-F PIC X(10) VALUE SPACES.
01 YEAR-F PIC X(6) VALUE SPACES.
01 CNT-F PIC 9(2) VALUE 0.
01 LEN-F PIC 9(2) VALUE 0.
PROCEDURE DIVISION.
UNSTRING LINE-F DELIMITED BY ","
INTO NAME-1 NAME-2 CITY-F YEAR-F
COUNT IN LEN-F
TALLYING IN CNT-F
END-UNSTRING.
DISPLAY "1 [" NAME-1 "]".
DISPLAY "2 [" NAME-2 "]".
DISPLAY "3 [" CITY-F "]".
DISPLAY "4 [" YEAR-F "]".
DISPLAY "count " CNT-F " last len " LEN-F.
STOP RUN.
cobc -x -free -Wall -o split split.cob
./split
1 [ADA ]
2 [LOVELACE ]
3 [LONDON ]
4 [1815 ]
count 04 last len 04
Each piece is padded on the right into its receiver, exactly as a MOVE would, so the fields have the spaces of their pictures and not the length of the pieces. The comma itself is consumed: it is a delimiter, not data, and it never appears in a receiver.
COUNT IN and TALLYING IN
The two counters answer different questions. COUNT IN receives the number of characters moved into the last receiver filled, which is 4 for 1815; with a single receiver the same clause gives the length of the piece, which is how a program measures a token. TALLYING IN receives the number of receivers filled, which is 4 here.
Both counters start at whatever they hold and are added to. A field that is used for two lines without a MOVE 0 between them reports the total of both, which is useful when the question is "how many fields in the file" and a bug when it is "how many in this line".
Fewer fields than receivers
A line from a file is not always the line the program expects, and the statement says so through the counter rather than through an error:
IDENTIFICATION DIVISION.
PROGRAM-ID. PARTIAL.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 LINE-F PIC X(16) VALUE "RED;GREEN".
01 C1-F PIC X(6) VALUE SPACES.
01 C2-F PIC X(6) VALUE SPACES.
01 C3-F PIC X(6) VALUE "KEEP".
01 CNT-F PIC 9(2) VALUE 0.
PROCEDURE DIVISION.
UNSTRING LINE-F DELIMITED BY ";"
INTO C1-F C2-F C3-F
TALLYING IN CNT-F
END-UNSTRING.
DISPLAY "1 [" C1-F "] 2 [" C2-F "] 3 [" C3-F "]".
DISPLAY "count " CNT-F.
STOP RUN.
cobc -x -free -Wall -o partial partial.cob
./partial
1 [RED ] 2 [GREEN ] 3 [KEEP ]
count 02
The third receiver was never touched, so it still holds what the program put there, and the count of two is the only signal that the line had two fields. A program that checks the count before it uses C3-F avoids reading a value from the previous line, which is the same bug as a missing field in a parsed record.
Several delimiters
Real files mix their separators, and the OR form takes a list:
IDENTIFICATION DIVISION.
PROGRAM-ID. MULTI.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 LINE-F PIC X(20) VALUE "RED,GREEN;BLUE".
01 C1-F PIC X(6) VALUE SPACES.
01 C2-F PIC X(6) VALUE SPACES.
01 C3-F PIC X(6) VALUE SPACES.
01 CNT-F PIC 9(2) VALUE 0.
PROCEDURE DIVISION.
UNSTRING LINE-F DELIMITED BY "," OR ";"
INTO C1-F C2-F C3-F
TALLYING IN CNT-F
END-UNSTRING.
DISPLAY "[" C1-F "][" C2-F "][" C3-F "]".
DISPLAY "count " CNT-F.
STOP RUN.
cobc -x -free -Wall -o multi multi.cob
./multi
[RED ][GREEN ][BLUE ]
count 03
Three delimiters work the same way, and DELIMITED BY ALL "," OR ALL ";" treats a run of separators as one, which is what a hand-edited file needs. The statement also takes ON OVERFLOW for the other kind of surprise: more fields than receivers, in which case the count is the only warning and the rest of the line is lost.
The next lesson takes a substring by position instead of by delimiter, which is the tool for a fixed-width field.
Exercises
- Split the line into ten receivers and print the count. How many are filled, and what do the others hold?
- Add MOVE 0 TO CNT-F before a second UNSTRING on the same line and print the count twice. What does the second count show without the move?
- Use COUNT IN with a single receiver to measure each of the four pieces. Which piece is the longest?
- Give the line a trailing comma and run the program. What is the count, and what is in the last receiver?
Questions
A new set of questions in a new order every time. Choose one answer for each, then check.
-
What does UNSTRING do with the delimiter?
Answer
It consumes it, so it never appears in a receiver
DELIMITED BY names the separators, so the pieces between them are what arrive in the receivers.
-
What does COUNT IN receive?
Answer
The number of characters moved into the last receiver filled
COUNT measures the piece, and with one receiver it is the length of that piece; TALLYING counts the receivers.
-
What does TALLYING IN receive?
Answer
The number of receivers that were filled
It counts the pieces that found a receiver, which is the field count of the line.
-
A line has two fields and the statement names three receivers. What happens?
Answer
The two pieces are stored, the third receiver is untouched, and the count is two
The statement fills what the line provides, and the count is how the program learns that the third value is not there.
-
What does this program print?
IDENTIFICATION DIVISION. PROGRAM-ID. Q1. DATA DIVISION. WORKING-STORAGE SECTION. 01 LINE-F PIC X(24) VALUE "ADA,LOVELACE,LONDON,1815". 01 NAME-1 PIC X(10) VALUE SPACES. 01 NAME-2 PIC X(10) VALUE SPACES. PROCEDURE DIVISION. UNSTRING LINE-F DELIMITED BY "," INTO NAME-1 NAME-2 END-UNSTRING. DISPLAY "[" NAME-1 "][" NAME-2 "]". STOP RUN.Answer
[ADA ][LOVELACE ]
The first two pieces are ADA and LOVELACE, each padded to the ten bytes of its receiver.
-
What does this program print?
IDENTIFICATION DIVISION. PROGRAM-ID. Q2. DATA DIVISION. WORKING-STORAGE SECTION. 01 LINE-F PIC X(16) VALUE "RED;GREEN". 01 C1-F PIC X(6) VALUE SPACES. 01 C2-F PIC X(6) VALUE SPACES. 01 C3-F PIC X(6) VALUE "KEEP". 01 CNT-F PIC 9(2) VALUE 0. PROCEDURE DIVISION. UNSTRING LINE-F DELIMITED BY ";" INTO C1-F C2-F C3-F TALLYING IN CNT-F END-UNSTRING. DISPLAY "[" CNT-F "]". STOP RUN.Answer
[02]
Two pieces were found and two receivers filled, so the counter is two.
-
What does this program print?
IDENTIFICATION DIVISION. PROGRAM-ID. Q3. DATA DIVISION. WORKING-STORAGE SECTION. 01 LINE-F PIC X(24) VALUE "ADA,LOVELACE,LONDON,1815". 01 YEAR-F PIC X(6) VALUE SPACES. 01 LEN-F PIC 9(2) VALUE 0. PROCEDURE DIVISION. UNSTRING LINE-F DELIMITED BY "," INTO YEAR-F COUNT IN LEN-F END-UNSTRING. DISPLAY "[" YEAR-F "][" LEN-F "]". STOP RUN.Answer
[ADA ][03]
The first piece is ADA, and the counter holds the three characters that were moved into the receiver.
-
What does this program print?
IDENTIFICATION DIVISION. PROGRAM-ID. Q4. DATA DIVISION. WORKING-STORAGE SECTION. 01 LINE-F PIC X(20) VALUE "RED,GREEN;BLUE". 01 C1-F PIC X(6) VALUE SPACES. 01 C2-F PIC X(6) VALUE SPACES. 01 C3-F PIC X(6) VALUE SPACES. 01 CNT-F PIC 9(2) VALUE 0. PROCEDURE DIVISION. UNSTRING LINE-F DELIMITED BY "," OR ";" INTO C1-F C2-F C3-F TALLYING IN CNT-F END-UNSTRING. DISPLAY "[" C1-F "][" C2-F "][" C3-F "][" CNT-F "]". STOP RUN.Answer
[RED ][GREEN ][BLUE ][03]
Either delimiter ends a piece, so three pieces are found and the counter is three.
-
What does this program print?
IDENTIFICATION DIVISION. PROGRAM-ID. Q5. DATA DIVISION. WORKING-STORAGE SECTION. 01 LINE-F PIC X(24) VALUE "ADA,LOVELACE,LONDON,1815". 01 NAME-1 PIC X(10) VALUE SPACES. 01 CNT-F PIC 9(2) VALUE 0. PROCEDURE DIVISION. UNSTRING LINE-F DELIMITED BY "," INTO NAME-1 TALLYING IN CNT-F. UNSTRING LINE-F DELIMITED BY "," INTO NAME-1 TALLYING IN CNT-F. DISPLAY "[" NAME-1 "][" CNT-F "]". STOP RUN.Answer
[ADA ][02]
The counter is added to, not reset, so two statements that each fill one receiver leave it at two.
-
A CSV line has five fields and the program names four receivers with no ON OVERFLOW. What happens?
Answer
The fifth piece is lost and only the count shows that the line was longer
The statement fills the receivers it has and stops; without the error clause the loss is silent.
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