Capstone A: the record layout
The capstones build the thing most COBOL actually does: read a file of fixed-width records, check it, total it and report on it. Project A does that in three lessons over one customer file, and the first lesson is the layout, because every later bug in a fixed-width system is a bug in the layout first.
The project
A file of customers, one record per line, no separators: every field is at a fixed position and every record is the same length. The record has four fields and thirty-seven bytes:
position length field picture
1 6 CUST-ID X(6) C00001
7 20 CUST-NAME X(20) Ada Lovelace
27 2 CUST-REGION X(2) N1
29 9 CUST-AMOUNT 9(7)V99 0001234.56
Lesson 128 reads the file and rejects what does not fit the layout; lesson 129 prints the report with subtotals by region. Both programs on those pages write this data file themselves when it is not there, so each page is one build and one run with no other file to prepare.
The record layout
A fixed-width record is a group item whose children are elementary items in order. The position of a field is the sum of the lengths before it and nothing else: there are no separators, no alignment and no padding except the padding a MOVE adds to a short value.
That is why the layout is written down before the program. A name of twenty characters holds Ada Lovelace and ten spaces, and a program that reads the name into PIC X(18) silently loses the last two spaces; a program that reads a nine-character amount into PIC 9(7)V9 silently reads the wrong number and shifts everything after it.
The copybook
The record description lives in a file of its own, a copybook, so that the program that writes the file and the program that reads it cannot disagree about it. Save this as custrec.cpy:
01 CUSTOMER-REC.
05 CUST-ID PIC X(6).
05 CUST-NAME PIC X(20).
05 CUST-REGION PIC X(2).
05 CUST-AMOUNT PIC 9(7)V99.
The copybook holds no PROGRAM-ID and no divisions: it is a fragment of a DATA DIVISION, included with COPY custrec. where the record is needed. The COPY lesson has the search rules and the extension; the capstone C project uses the same mechanism for an interface between two programs.
The six spaces before 01 are the fixed-format area A convention kept by habit. They are legal in free format and harmless; a copybook written for a compiler from 1985 has them.
A program that proves the width
The layout is a claim about bytes, and a claim about bytes is worth checking with the compiler rather than with a ruler. This program declares the same record, fills it with a known customer and prints the length of the record and of one field:
IDENTIFICATION DIVISION.
PROGRAM-ID. LAYOUT.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 CUSTOMER-REC.
05 CUST-ID PIC X(6).
05 CUST-NAME PIC X(20).
05 CUST-REGION PIC X(2).
05 CUST-AMOUNT PIC 9(7)V99.
PROCEDURE DIVISION.
MOVE "C00001" TO CUST-ID
MOVE "Ada Lovelace" TO CUST-NAME
MOVE "N1" TO CUST-REGION
MOVE 1234.56 TO CUST-AMOUNT
DISPLAY "id [" CUST-ID "]"
DISPLAY "name [" CUST-NAME "]"
DISPLAY "region [" CUST-REGION "]"
DISPLAY "amount [" CUST-AMOUNT "]"
DISPLAY "record " LENGTH OF CUSTOMER-REC " bytes"
DISPLAY "amount " LENGTH OF CUST-AMOUNT " bytes"
DISPLAY CUSTOMER-REC
STOP RUN.
cobc -x -free -Wall -o layout layout.cob
./layout
id [C00001]
name [Ada Lovelace ]
region [N1]
amount [0001234.56]
record 37 bytes
amount 9 bytes
C00001Ada Lovelace N1000123456
Three facts come out of that run and each one is the layout again. The name prints with ten spaces, because twenty characters is its width and the value is ten. The amount prints as nine digits with the decimal point implied by the picture, not stored in the field. And the whole record prints as one thirty-seven-character string, which is what the file holds and what the next lesson reads.
The last line is also the proof that the fields are adjacent: there is no space between C00001 and the name, and none between the region and the amount, because the record has no separators to put there. A reader who wants to see a record split it with reference modification, which is the topic of lesson 038.
The sample data
Six good records and two bad ones, saved as customers.dat. The two bad lines are the input of the next lesson: one has a region that is not in the list, and one is shorter than the record, which a fixed-width reader pads with spaces until the amount is no longer a number.
C00001Ada Lovelace N1000123456
C00002Grace Hopper N1000234567
C00003Alan Turing S2000045678
C00004Katherine Johnson S2000567890
C00005Edsger Dijkstra E3000078901
C00006Barbara Liskov E3000123456
C00007Bad Region X9000010000
C00008Short
head -1 customers.dat | wc -c
wc -l customers.dat
38
8 customers.dat
Thirty-eight bytes for a thirty-seven-byte record, because the newline is a byte on disk and not part of the record. The line sequential organisation is exactly this: the record as the program sees it, and a newline the runtime adds and removes.
The last line of the file is C00008Short, eleven characters where the record has thirty-seven. Written by a program it would have been padded; typed into a file it is short, and the reader is the one that pads it. That is a real difference between a fixed-width file from a mainframe and a text file edited by hand, and the next lesson shows what the padding does to the last field.
Exercises
- Add a field CUST-BRANCH PIC X(3) between the region and the amount. Which positions do the region and the amount have now, and how long is the record?
- Change the name to PIC X(15) and keep the data file. What does the reader see in the region field, and why?
- Give the copybook a SYNC on the amount and print LENGTH OF the record again. Why must a file record not have it?
- Write the six good records with a program that uses WRITE ... FROM a literal, and compare the file with cmp against the one on this page.
Questions
A new set of questions in a new order every time. Choose one answer for each, then check.
-
How long is the customer record on this page?
Answer
37 bytes
Six plus twenty plus two plus nine is thirty-seven, and LENGTH OF prints it.
-
Where does the newline of a line sequential file live?
Answer
On disk after each record, and the runtime removes it on READ
A thirty-seven-byte record takes thirty-eight bytes on disk.
-
Why is the record description kept in a copybook?
Answer
So the writer and the reader of the file use one description
The COPY lesson and capstone C show the same reason for an interface.
-
What does a short line in a fixed-width file do to the last field?
Answer
The reader pads the record with spaces, and a numeric last field stops being numeric
The next lesson rejects the short line for exactly that reason.
-
What does this program print?
IDENTIFICATION DIVISION. PROGRAM-ID. Q5. DATA DIVISION. WORKING-STORAGE SECTION. 01 R. 05 A PIC X(3). 05 B PIC X(2). 05 C PIC 9(4). PROCEDURE DIVISION. DISPLAY LENGTH OF R " " LENGTH OF C. STOP RUN.Answer
9 4
Three plus two plus four is nine for the record, four for the numeric field.
-
What does this program print?
IDENTIFICATION DIVISION. PROGRAM-ID. Q6. DATA DIVISION. WORKING-STORAGE SECTION. 01 R. 05 A PIC X(3) VALUE "AB ". 05 B PIC X(3) VALUE "CD ". PROCEDURE DIVISION. DISPLAY R(1:2) R(4:2). STOP RUN.Answer
ABCD
The first two bytes are AB and bytes four and five are CD.
-
What does this program print?
IDENTIFICATION DIVISION. PROGRAM-ID. Q7. DATA DIVISION. WORKING-STORAGE SECTION. 01 S PIC X(6) VALUE "ABCDEF". PROCEDURE DIVISION. DISPLAY S(2:3) "-" S(6:1). STOP RUN.Answer
BCD-F
Three characters from position two are BCD, and position six is F.
-
What does this program print?
IDENTIFICATION DIVISION. PROGRAM-ID. Q8. DATA DIVISION. WORKING-STORAGE SECTION. 01 A PIC 9(5)V99 VALUE 12.5. PROCEDURE DIVISION. DISPLAY "[" A "]". STOP RUN.Answer
[00012.50]
A numeric DISPLAY keeps every digit the picture declares.
-
Why check LENGTH OF instead of counting the picture by hand?
Answer
The compiler knows the alignment and the picture, and a hand count is where the bugs are
The layout program is the check, not the prose.
-
Which part of the project does lesson 127 build?
Answer
The record layout, the copybook and the sample data
Reading and validation come in 128, the report in 129.
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. The data file was written by the same program with WRITE ... FROM; the listing above is the file it produced.
Article author: Arthur Isaev