Skip to content
LumenaryAcademy
Practice 60 min

Files and reports

Sequential and indexed files, FILE STATUS, the SORT statement, and printed reports with headings and control breaks.

Code tested · 2AI-draftedAwaiting review by a computer scientist
MotivationH

The batch run

Picture a bank at night. During the day, every deposit, withdrawal and card payment was recorded as a transaction. Overnight, a chain of programs runs in batch: one sorts the day's transactions by account number, another reads them alongside the file of accounts and applies them, another prints statements, another produces reports for the branches and the regulators. Each program reads one or more files from start to finish, writes new files, and hands them to the next step. Nothing waits for a person.

This is the work COBOL was built for, and it still makes up a large part of what COBOL systems do every night. Files are therefore not a side topic in COBOL; they are the centre. This lesson teaches you to define, read and write files, to check every operation, to sort, and to produce the classic printed report with headings, details and totals. Every program here creates its own small files in the current directory and reads them back, so you can run them as they are.

DefinitionsH

Files in three places

Using a file in COBOL involves three parts of the program:

  1. FILE-CONTROL, in the environment division's INPUT-OUTPUT SECTION, has one SELECT entry per file. It gives the file an internal name, says where it lives (ASSIGN TO), how it is organised and accessed, and names a two-character FILE STATUS field.
  2. The FILE SECTION of the data division has an FD (file description) for each file, followed by its record layout. The record area is where READ puts the next record and where WRITE takes it from.
  3. The procedure division uses the I/O verbs: OPEN, READ, WRITE, REWRITE, DELETE, START, CLOSE.

Organisations

OrganisationWhat it isMainframe equivalent
LINE SEQUENTIALA text file: one record per line, ended by a newline (GnuCOBOL and PC compilers)none; a Unix-style text file
SEQUENTIALRecords one after another, read and written in orderA QSAM data set
INDEXEDRecords with a unique key, readable in key order or directly by key; optional alternate keysA VSAM KSDS (key-sequenced data set)
RELATIVERecords addressed by a record numberA VSAM RRDS

Open modes

OPEN INPUT reads; OPEN OUTPUT creates the file, replacing any existing one; OPEN EXTEND appends to the end; OPEN I-O reads and updates in place (indexed and relative files, or rewriting sequential records).

Definition— FILE STATUS

A two-character code that the runtime stores after every operation on a file. The first character gives the class of result: 0 success, 1 end of file, 2 invalid key, 3 permanent error, 4 logic error, 9 implementor-defined.

The codes you will meet most:

StatusMeaning
00Success
10End of file: no next record
22Duplicate key on a WRITE to an indexed file
23Record not found for that key
35OPEN INPUT of a file that does not exist
39The file's attributes (such as record length) conflict with the program's description
41, 42Opening a file that is already open, or closing one that is not

A file with a FILE STATUS clause hands error handling to you: the program carries on, and you must check the code. Without one, a serious I/O error usually stops the run. Professional programs declare a status for every file and check it after every operation that can fail.

Worked examplesH

Reading and writing sequential files

Write, append, read, and handle a missing file

cobol
IDENTIFICATION DIVISION.
PROGRAM-ID. account-file.
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
    SELECT account-file ASSIGN TO "accounts.dat"
        ORGANIZATION IS LINE SEQUENTIAL
        FILE STATUS IS ws-account-status.
    SELECT archive-file ASSIGN TO "archive-2019.dat"
        ORGANIZATION IS LINE SEQUENTIAL
        FILE STATUS IS ws-archive-status.
DATA DIVISION.
FILE SECTION.
FD account-file.
01 account-record.
   05 acct-number        PIC 9(6).
   05 acct-holder        PIC X(20).
   05 acct-balance       PIC S9(7)V99 SIGN IS LEADING SEPARATE.
FD archive-file.
01 archive-record        PIC X(80).
WORKING-STORAGE SECTION.
01 ws-account-status     PIC XX.
01 ws-archive-status     PIC XX.
01 ws-eof-flag           PIC X VALUE "N".
   88 end-of-accounts    VALUE "Y".
01 ws-record-count       PIC 9(5) VALUE 0.
01 ws-total              PIC S9(9)V99 VALUE 0.
01 ws-balance-out        PIC ----,--9.99.
01 ws-total-out          PIC --,---,--9.99.
PROCEDURE DIVISION.
0000-main.
    PERFORM 1000-create-file
    PERFORM 2000-append-one
    PERFORM 3000-list-file
    PERFORM 4000-try-missing-file
    STOP RUN.

1000-create-file.
    OPEN OUTPUT account-file
    MOVE 100201 TO acct-number  MOVE "Leilani Kahale" TO acct-holder
    MOVE 1520.40 TO acct-balance  WRITE account-record
    MOVE 100202 TO acct-number  MOVE "Tomasz Wojcik" TO acct-holder
    MOVE -75.10 TO acct-balance   WRITE account-record
    MOVE 100203 TO acct-number  MOVE "Aiyana Redcloud" TO acct-holder
    MOVE 98000.00 TO acct-balance WRITE account-record
    CLOSE account-file
    DISPLAY "create: status " ws-account-status.

2000-append-one.
    OPEN EXTEND account-file
    MOVE 100204 TO acct-number  MOVE "Farah Haddad" TO acct-holder
    MOVE 310.25 TO acct-balance   WRITE account-record
    CLOSE account-file
    DISPLAY "append: status " ws-account-status.

3000-list-file.
    OPEN INPUT account-file
    PERFORM 3100-read-account
    PERFORM UNTIL end-of-accounts
        ADD 1 TO ws-record-count
        ADD acct-balance TO ws-total
        MOVE acct-balance TO ws-balance-out
        DISPLAY acct-number " " acct-holder ws-balance-out
        PERFORM 3100-read-account
    END-PERFORM
    CLOSE account-file
    MOVE ws-total TO ws-total-out
    DISPLAY ws-record-count " records, total" ws-total-out.

3100-read-account.
    READ account-file
        AT END SET end-of-accounts TO TRUE
    END-READ.

4000-try-missing-file.
    OPEN INPUT archive-file
    IF ws-archive-status NOT = "00"
        DISPLAY "archive: cannot open, status " ws-archive-status
    END-IF.
text
create: status 00
append: status 00
100201 Leilani Kahale         1,520.40
100202 Tomasz Wojcik            -75.10
100203 Aiyana Redcloud       98,000.00
100204 Farah Haddad             310.25
00004 records, total    99,755.55
archive: cannot open, status 35

After the run, accounts.dat is a plain text file, one 36-character record per line:

text
100201Leilani Kahale      +000152040
100202Tomasz Wojcik       -000007510
100203Aiyana Redcloud     +009800000
100204Farah Haddad        +000031025

This is what "the record layout is the file format" means. Six digits of account number, twenty characters of name, then the balance. SIGN IS LEADING SEPARATE asks for the sign as a separate first character instead of folded into the last digit, which makes the file easy for other systems to read; the implied decimal point is, as always, not stored, so 000152040 is 1520.40. A program in any language that knows this layout can read the file.

The read loop has the shape you will write hundreds of times:

  • The priming read. 3000-list-file reads the first record before the loop. The loop then processes the current record and reads the next one at the bottom. When a READ finds no more records, AT END sets the condition name, and the loop's test stops it before it processes a record that does not exist. Putting the read at the top of the loop instead is a classic beginner bug that processes the last record twice.
  • One paragraph does the reading. 3100-read-account is the only place the file is read, so adding a record count, a check of the status or a filter later means changing one paragraph.
  • The missing file did not stop the program. Because archive-file has a FILE STATUS, the open failed with status 35 and the program decided what to do.

Indexed files

An indexed file keeps its records in key order and can fetch one directly by key, like a table in a database with a primary key. On z/OS it is a VSAM key-sequenced data set; on other platforms the COBOL runtime uses a file handler library. The build of GnuCOBOL used to test this course was compiled without an indexed file handler, so the fragments below are described rather than run; GnuCOBOL builds linked with Berkeley DB or VBISAM support them fully.

cobol
SELECT customer-file ASSIGN TO "customers.idx"
    ORGANIZATION IS INDEXED
    ACCESS MODE IS DYNAMIC
    RECORD KEY IS cust-id
    ALTERNATE RECORD KEY IS cust-email WITH DUPLICATES
    FILE STATUS IS ws-cust-status.

ACCESS MODE is SEQUENTIAL (in key order), RANDOM (by key) or DYNAMIC (both). The key verbs:

cobol
*> Read one record directly by its key
MOVE 100203 TO cust-id
READ customer-file
    INVALID KEY      DISPLAY "no customer " cust-id
    NOT INVALID KEY  PERFORM 2100-show-customer
END-READ

*> Position at the first key >= a value, then read forward in key order
MOVE 500000 TO cust-id
START customer-file KEY IS >= cust-id
    INVALID KEY SET no-more-customers TO TRUE
END-START
READ customer-file NEXT RECORD
    AT END SET no-more-customers TO TRUE
END-READ

*> After reading a record with the file open I-O: change it, or remove it
REWRITE customer-record
DELETE customer-file RECORD

INVALID KEY runs when the key is not found (status 23) or, on a WRITE, already exists (status 22). Most new systems keep such data in a relational database instead, but indexed files remain common in existing COBOL applications, especially in CICS online programs that need fast lookups by key.

ComputationC

Sorting and a control-break report

Reports are where COBOL's data division shines. Each kind of printed line, whether a heading, a detail line or a total line, is declared as a record with FILLER text and edited fields, so the layout is visible in the source as a row of columns. The procedure division just moves values into the fields and prints the line.

The classic report structure is the control break. The input is sorted by one or more keys (here, region). The program prints one detail line per record, and each time the key changes it "breaks": it prints a subtotal for the group that just ended and resets the counter. At the end it prints the last group's subtotal and a grand total. The SORT statement does the sorting, through a sort work file declared with SD instead of FD:

cobol
IDENTIFICATION DIVISION.
PROGRAM-ID. sales-report.
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
    SELECT sales-in     ASSIGN TO "sales-in.dat"
        ORGANIZATION IS LINE SEQUENTIAL.
    SELECT sales-sorted ASSIGN TO "sales-sorted.dat"
        ORGANIZATION IS LINE SEQUENTIAL.
    SELECT sort-work    ASSIGN TO "sort-work.tmp".
DATA DIVISION.
FILE SECTION.
FD sales-in.
01 in-record             PIC X(27).
FD sales-sorted.
01 sale-record.
   05 sale-region        PIC X(8).
   05 sale-branch        PIC X(12).
   05 sale-amount        PIC 9(5)V99.
SD sort-work.
01 sort-record.
   05 sort-region        PIC X(8).
   05 sort-branch        PIC X(12).
   05 sort-amount        PIC 9(5)V99.
WORKING-STORAGE SECTION.
01 ws-eof                PIC X VALUE "N".
   88 end-of-sales       VALUE "Y".
01 ws-current-region     PIC X(8).
01 ws-region-total       PIC 9(7)V99 VALUE 0.
01 ws-grand-total        PIC 9(8)V99 VALUE 0.
01 heading-1.
   05 FILLER             PIC X(25) VALUE "QUARTERLY SALES BY BRANCH".
01 heading-2.
   05 FILLER             PIC X(10) VALUE "REGION".
   05 FILLER             PIC X(14) VALUE "BRANCH".
   05 FILLER             PIC X(10) VALUE "    AMOUNT".
01 detail-line.
   05 dl-region          PIC X(10).
   05 dl-branch          PIC X(14).
   05 dl-amount          PIC ZZZ,ZZ9.99.
01 total-line.
   05 FILLER             PIC X(2)  VALUE SPACES.
   05 tl-label           PIC X(20).
   05 tl-amount          PIC Z,ZZZ,ZZ9.99.
PROCEDURE DIVISION.
0000-main.
    PERFORM 1000-write-unsorted-input
    SORT sort-work
        ON ASCENDING KEY sort-region sort-branch
        USING sales-in
        GIVING sales-sorted
    PERFORM 2000-print-report
    STOP RUN.

1000-write-unsorted-input.
    OPEN OUTPUT sales-in
    MOVE "West    Valparaiso  0412050" TO in-record  WRITE in-record
    MOVE "East    Mombasa     0388000" TO in-record  WRITE in-record
    MOVE "West    Lima        0520075" TO in-record  WRITE in-record
    MOVE "East    Arusha      0295040" TO in-record  WRITE in-record
    MOVE "North   Tromso      0150000" TO in-record  WRITE in-record
    MOVE "East    Kampala     0177525" TO in-record  WRITE in-record
    CLOSE sales-in.

2000-print-report.
    DISPLAY heading-1
    DISPLAY heading-2
    OPEN INPUT sales-sorted
    PERFORM 2100-read-sale
    IF NOT end-of-sales
        MOVE sale-region TO ws-current-region
    END-IF
    PERFORM UNTIL end-of-sales
        IF sale-region NOT = ws-current-region
            PERFORM 2200-region-break
        END-IF
        MOVE sale-region TO dl-region
        MOVE sale-branch TO dl-branch
        MOVE sale-amount TO dl-amount
        DISPLAY detail-line
        ADD sale-amount TO ws-region-total
        PERFORM 2100-read-sale
    END-PERFORM
    PERFORM 2200-region-break
    MOVE "GRAND TOTAL" TO tl-label
    MOVE ws-grand-total TO tl-amount
    DISPLAY total-line
    CLOSE sales-sorted.

2100-read-sale.
    READ sales-sorted
        AT END SET end-of-sales TO TRUE
    END-READ.

2200-region-break.
    MOVE SPACES TO tl-label
    STRING "Total " ws-current-region DELIMITED BY SIZE INTO tl-label
    MOVE ws-region-total TO tl-amount
    DISPLAY total-line
    DISPLAY " "
    ADD ws-region-total TO ws-grand-total
    MOVE ZERO TO ws-region-total
    MOVE sale-region TO ws-current-region.
text
QUARTERLY SALES BY BRANCH
REGION    BRANCH            AMOUNT
East      Arusha          2,950.40
East      Kampala         1,775.25
East      Mombasa         3,880.00
  Total East              8,605.65
 
North     Tromso          1,500.00
  Total North             1,500.00
 
West      Lima            5,200.75
West      Valparaiso      4,120.50
  Total West              9,321.25
 
  GRAND TOTAL            19,426.90

How it works:

  • SORT ... USING ... GIVING opens the input file, sorts all its records on the keys (region, then branch within region), writes the sorted file and closes everything, in one statement. Instead of USING and GIVING you can name an INPUT PROCEDURE that selects or changes records with RELEASE as they go into the sort, and an OUTPUT PROCEDURE that receives them in order with RETURN, so a report can be printed straight from the sort without an intermediate file.
  • The break test compares each record's region with ws-current-region. When they differ, 2200-region-break prints the subtotal, adds it to the grand total, resets the region total and remembers the new region.
  • The final break. After the loop, the last group has not been closed yet, so the program performs the break once more before printing the grand total. Forgetting it is the most common control-break bug: the report silently omits the last group's subtotal.
  • The columns line up because every line record is designed to the same widths: the amount column ends at position 34 in the heading, detail and total lines alike.

A real report would be written to a print file rather than displayed: WRITE print-line AFTER ADVANCING 1 LINE moves down one line before printing, AFTER ADVANCING PAGE starts a new page, and the program counts lines to print page headings and page numbers. On the mainframe the print file is a data set that goes to a printer, an archive or, these days, more often a PDF or a document-management system. COBOL also has a Report Writer feature (REPORT SECTION) that declares headings, footings and control breaks and generates this logic for you; it is used in some shops, available for IBM mainframes through a separate precompiler, and supported directly by GnuCOBOL 3.2.

ExplanationH

Files in professional practice

On a mainframe, files are data sets with names like PAYROLL.PROD.EMPLOYEE.MASTER, and their physical shape is part of their definition: a record format such as FB (fixed-length, blocked) or VB (variable-length, blocked), a logical record length (LRECL) and a block size. The COBOL program does not name the data set. Its SELECT ... ASSIGN TO EMPMAST refers to a DD name, and the job's JCL connects that DD name to an actual data set when the program runs (lesson 7 shows how). The same program can therefore read the test file on Monday and the production file on Tuesday without being recompiled. Many batch files are kept as generation data groups, a series of numbered versions of the same file, so that each night's run creates a new generation and the previous ones stay available for reruns and audits.

Batch programs are written to be checked as well as run. Three habits are nearly universal:

  • Control totals. A program counts the records it reads and writes and adds up key amounts, and it prints those totals at the end. The next step, or an operator, or an automated check compares them with the totals produced by the step before. If 1,204,331 transactions went into the sort and 1,204,330 came out, someone finds out why before statements are printed.
  • A status check after every I/O. Shops usually have a standard paragraph that every file operation performs afterwards, which logs the file name, the operation and the status, and ends the run cleanly (with a non-zero return code) on anything unexpected.
  • Restartability. A job that processes millions of records may take hours. Long-running programs write checkpoints, or are designed so that a failed step can simply be rerun from its input files, which is one reason batch steps rarely update their input in place.
Common misconceptionsH

Common misconceptions

Misconception

"OPEN OUTPUT adds to the file." It creates the file afresh, destroying what was there. Use OPEN EXTEND to append. Many a test file has been lost to this.

Misconception

"I can test end of file before reading." COBOL only knows the file has ended when a READ fails to find a record. That is why the loop needs a priming read before it starts, and a read at the end of each pass.

Misconception

"A FILE STATUS clause makes I/O errors safe." It makes them your responsibility. A program that declares a status and never checks it will carry on after a failed WRITE as if nothing happened, which is worse than stopping.

Misconception

"The file stores the numbers I see on the report." The file stores the record layout's bytes: no decimal points, signs folded into digits or written separately, and COMP-3 fields as raw packed bytes. To read a file correctly in any language you need its record description.

Exercises

Exercises

Try each question before opening the hints. Every answer about program output was checked by compiling and running the program with GnuCOBOL 3.2.

1. Files and reports

Warm-upHuman

After OPEN INPUT archive-file, the file's status field holds 35. What happened?

Choose one

2. Files and reports

Warm-upComputational

A file contains one record. A program opens it for input and reads twice. What does the status field hold after the second READ? (Two characters.)

3. Files and reports

Warm-upHuman

A program must add today's records to the end of an existing sequential log file. Which OPEN should it use?

Choose one

4. Files and reports

CoreComputational

In the lesson's account file, acct-balance is PIC S9(7)V99 SIGN IS LEADING SEPARATE. What ten characters does the file contain for a balance of −75.10?

5. Files and reports

CoreComputational

A control-break report like the lesson's (break on region, plus a grand total) reads these records, already sorted by region: Asia, Asia, Asia, Europe, Oceania, Oceania. How many total lines does it print, counting the grand total?

6. Files and reports

CoreHuman

Why does the standard COBOL read loop read the first record before the loop and the next record at the end of each pass?

Choose one

7. Files and reports

StretchHuman

A program reads an indexed file by key with READ customer-file INVALID KEY ... END-READ, and no record has that key. Which statement is true?

Choose one

Further reading and resources