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.
Files in three places
Using a file in COBOL involves three parts of the program:
FILE-CONTROL, in the environment division'sINPUT-OUTPUT SECTION, has oneSELECTentry 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-characterFILE STATUSfield.- The
FILE SECTIONof the data division has an FD (file description) for each file, followed by its record layout. The record area is whereREADputs the next record and whereWRITEtakes it from. - The procedure division uses the I/O verbs:
OPEN,READ,WRITE,REWRITE,DELETE,START,CLOSE.
Organisations
| Organisation | What it is | Mainframe equivalent |
|---|---|---|
LINE SEQUENTIAL | A text file: one record per line, ended by a newline (GnuCOBOL and PC compilers) | none; a Unix-style text file |
SEQUENTIAL | Records one after another, read and written in order | A QSAM data set |
INDEXED | Records with a unique key, readable in key order or directly by key; optional alternate keys | A VSAM KSDS (key-sequenced data set) |
RELATIVE | Records addressed by a record number | A 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:
| Status | Meaning |
|---|---|
00 | Success |
10 | End of file: no next record |
22 | Duplicate key on a WRITE to an indexed file |
23 | Record not found for that key |
35 | OPEN INPUT of a file that does not exist |
39 | The file's attributes (such as record length) conflict with the program's description |
41, 42 | Opening 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.
Reading and writing sequential files
Write, append, read, and handle a missing file
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.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 35After the run, accounts.dat is a plain text file, one 36-character record per line:
100201Leilani Kahale +000152040
100202Tomasz Wojcik -000007510
100203Aiyana Redcloud +009800000
100204Farah Haddad +000031025This 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-filereads the first record before the loop. The loop then processes the current record and reads the next one at the bottom. When aREADfinds no more records,AT ENDsets 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-accountis 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-filehas aFILE STATUS, the open failed with status35and 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.
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:
*> 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 RECORDINVALID 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.
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:
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.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.90How it works:
SORT ... USING ... GIVINGopens 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 ofUSINGandGIVINGyou can name anINPUT PROCEDUREthat selects or changes records withRELEASEas they go into the sort, and anOUTPUT PROCEDUREthat receives them in order withRETURN, 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-breakprints 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.
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 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
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-upHumanAfter OPEN INPUT archive-file, the file's status field holds 35. What happened?
2. Files and reports
Warm-upComputationalA 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-upHumanA program must add today's records to the end of an existing sequential log file. Which OPEN should it use?
4. Files and reports
CoreComputationalIn 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
CoreComputationalA 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
CoreHumanWhy does the standard COBOL read loop read the first record before the loop and the next record at the end of each pass?
7. Files and reports
StretchHumanA 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?
Further reading and resources
- GnuCOBOL guides and documentationThe Programmer's Guide documents file organisations, I/O statements, FILE STATUS codes and SORT.
- IBM Enterprise COBOL for z/OS documentationThe programming guide's chapters on processing QSAM and VSAM files describe sequential and indexed files on the mainframe.
- z/OS documentationIBM's z/OS library, including DFSMS (data sets and VSAM) and the JCL reference.