Divisions, paragraphs and the period that ends them

Two accounts, one of them overdrawn, and a COBOL program charged 50.00 in overdraft fees instead of 25.00. The cause was one period at the end of a line, which ended an IF two statements too early. A COBOL program is built from divisions, paragraphs and sentences, and the period is the punctuation that holds them together, or breaks them.

Below you will put the four divisions in their order, follow control from paragraph to paragraph and see how STOP RUN and GOBACK end a run, find what a stray period does inside an IF, tell NEXT SENTENCE from CONTINUE, and pair each END-IF with the IF it really closes.

Four divisions, always in the same order

A COBOL program has up to four divisionsdivision: One of the four main parts of a COBOL program, in a fixed order: IDENTIFICATION, ENVIRONMENT, DATA and PROCEDURE. Only the IDENTIFICATION DIVISION, with its PROGRAM-ID, is required., in a fixed order. IBM’s guide describes what each one holds. The IDENTIFICATION DIVISION names the program in its PROGRAM-ID paragraph, the name other programs use to call it. The ENVIRONMENT DIVISION describes “aspects of the program that depend on the computing environment”, from the computer it is compiled for to the files it connects to. The DATA DIVISION defines the data: file records, working storage, and data passed in from another program. The PROCEDURE DIVISION holds the code. Here are all four in one small program:

       IDENTIFICATION DIVISION.
       PROGRAM-ID. FOURDIV.
      * The four divisions, in the order the language requires.
       ENVIRONMENT DIVISION.
       CONFIGURATION SECTION.
       SOURCE-COMPUTER. LAPTOP.
       DATA DIVISION.
       WORKING-STORAGE SECTION.
       01  ACCOUNT-ID   PIC X(6)     VALUE "AC0001".
       01  BALANCE      PIC S9(5)V99 VALUE 1250.75.
       PROCEDURE DIVISION.
       SHOW-ACCOUNT.
           DISPLAY "Account " ACCOUNT-ID " balance " BALANCE
           STOP RUN.

The PROCEDURE DIVISION is where the structure goes deeper. IBM’s guide divides it into sections and paragraphsparagraph: A named group of sentences in the PROCEDURE DIVISION. Its name starts in Area A and ends with a period, and PERFORM can run it by that name., which contain sentences, which contain statements. Here is fourdiv.cob from its divisions down to its two statements:

Build it, then a program with only two divisions, then one that puts two divisions in the wrong order:

from session import files, run

# The four divisions in order, the two that every program needs, and what cobc says when the order is wrong.
files("fourdiv.cob", "tiny.cob", "order.cob")
run("""
cobc -x fourdiv.cob && ./fourdiv
cobc -x tiny.cob && ./tiny
cobc -x order.cob 2>&1 | grep 'error:'
""")

$ cobc -x fourdiv.cob && ./fourdiv
Account AC0001 balance +01250.75
$ cobc -x tiny.cob && ./tiny
Two divisions are enough
$ cobc -x order.cob 2>&1 | grep 'error:'
order.cob:7: error: PROCEDURE DIVISION header missing
order.cob:7: error: syntax error, unexpected ENVIRONMENT
order.cob:8: error: syntax error, unexpected CONFIGURATION
order.cob:9: error: syntax error, unexpected SOURCE-COMPUTER
order.cob:10: error: syntax error, unexpected PROCEDURE

fourdiv printed its account. tiny shows that the ENVIRONMENT and DATA divisions may be left out when a program needs nothing from them. IBM’s Language Reference calls even the PROCEDURE DIVISION optional, although a program without one does nothing; what every program needs is the IDENTIFICATION DIVISION, first, with its PROGRAM-ID paragraph, which IBM’s documentation marks as required. order.cob put its DATA DIVISION before the ENVIRONMENT DIVISION, and cobc’s first error came at line 7: after the DATA DIVISION only the PROCEDURE DIVISION may follow, so it reported the PROCEDURE DIVISION header missing and then could make no sense of the lines after it.

Control falls from one paragraph into the next

Inside the PROCEDURE DIVISION, a statement such as MOVE or DISPLAY is one action. A sentencesentence: One or more COBOL statements ended by a separator period. is one or more statements that end with a separator periodseparator period: A period followed by a space or the end of the line. It ends a sentence, and with it every statement still open, an IF included.. A paragraph is a name in Area A followed by its sentences, and a section groups paragraphs under a header. PERFORM runs a paragraph by name and comes back. Otherwise the program runs its paragraphs in the order they are written, and it does not stop at the end of one. This program has no STOP RUN:

       IDENTIFICATION DIVISION.
       PROGRAM-ID. FALLTHRU.
      * MAIN-PARA has no STOP RUN: watch what runs after it ends.
       PROCEDURE DIVISION.
       MAIN-PARA.
           DISPLAY "1. MAIN-PARA starts"
           PERFORM PRINT-TOTALS
           DISPLAY "3. back in MAIN-PARA".
       PRINT-TOTALS.
           DISPLAY "2. PRINT-TOTALS runs".

The session runs it, and then a file of three programs that shows how a run ends:

from session import files, run

# Control falls from one paragraph into the next; STOP RUN ends the whole run unit, GOBACK returns to the caller.
files("fallthru.cob", "rununit.cob")
run("""
cobc -x fallthru.cob && ./fallthru
cobc -x rununit.cob && ./rununit
""")

$ cobc -x fallthru.cob && ./fallthru
1. MAIN-PARA starts
2. PRINT-TOTALS runs
3. back in MAIN-PARA
2. PRINT-TOTALS runs
$ cobc -x rununit.cob && ./rununit
MAINPGM calls SUBGOOD
  SUBGOOD ends with GOBACK
MAINPGM is back from SUBGOOD
  SUBSTOP ends with STOP RUN

fallthru printed 2 twice. PERFORM ran PRINT-TOTALS and came back for line 3; then MAIN-PARA ended, nothing ended the run, and control fell into PRINT-TOTALS, the next paragraph in the source. Step through it:

Two statements end a run, and they differ inside a subprogram. IBM’s documentation says that STOP RUN in a subprogram returns directly to the program that called the main program, which ends the whole run unitrun unit: The programs that run together from one start. STOP RUN ends all of them, wherever it is reached; GOBACK returns only from the program that executes it., while GOBACK returns to the caller. rununit.cob shows both: after SUBGOOD’s GOBACK, MAINPGM carried on, and after SUBSTOP’s STOP RUN, MAINPGM never printed its last line.

One period ends every open statement

Now the fee program from the opening. Its paragraph CHARGE-OVERDRAFT is meant to display a message, add 25.00 and display a second message, for an overdrawn account only:

       IDENTIFICATION DIVISION.
       PROGRAM-ID. FEES.
      * Charges a 25.00 fee on each overdrawn account. The IF is
      * meant to cover the three statements under it.
       DATA DIVISION.
       WORKING-STORAGE SECTION.
       01  BALANCE      PIC S9(5)V99.
       01  FEES-TOTAL   PIC 9(3)V99 VALUE ZERO.
       PROCEDURE DIVISION.
       MAIN-PARA.
           MOVE 120.00 TO BALANCE
           PERFORM CHARGE-OVERDRAFT
           MOVE -35.50 TO BALANCE
           PERFORM CHARGE-OVERDRAFT
           DISPLAY "Fees charged in total: " FEES-TOTAL
           STOP RUN.
       CHARGE-OVERDRAFT.
           DISPLAY "Account balance " BALANCE
           IF BALANCE < ZERO
               DISPLAY "  overdrawn".
               ADD 25.00 TO FEES-TOTAL
               DISPLAY "  fee charged".

The line DISPLAY " overdrawn" ends with a period. IBM’s guide says what that does: the period is an implicit scope terminator that “ends the scope of all previous statements not yet ended”, the IF included. So the IF covers one statement, and the ADD after it runs for every account. fees-fixed.cob drops the inner periods and closes the IF with END-IF, an explicit scope terminatorscope terminator: A word such as END-IF or END-READ that ends one statement without ending the sentence. It closes the nearest statement of its kind that is still open., which ends a statement without ending the sentence:

from session import files, run

# One period too many: the fee program with the stray period, the same program with END-IF, a -Wall build that says
# nothing, what -Wterminator reports, and a check that finds IFs closed by a period.
files("fees.cob", "fees-fixed.cob")
run("""
cobc -x fees.cob && ./fees
cobc -x fees-fixed.cob && ./fees-fixed
cobc -x -Wall -o fees-wall fees.cob
cobc -x -Wterminator -o fees-count fees.cob 2>&1 | grep -o '[A-Z]* statement not terminated' | sort | uniq -c
cobc -x -Wterminator -o fees-check fees.cob 2>&1 | grep 'IF statement'
cobc -x -Wterminator -o fees-fixed-check fees-fixed.cob 2>&1 | grep 'IF statement' || echo "no IF without END-IF"
""")

$ cobc -x fees.cob && ./fees
Account balance +00120.00
  fee charged
Account balance -00035.50
  overdrawn
  fee charged
Fees charged in total: 050.00
$ cobc -x fees-fixed.cob && ./fees-fixed
Account balance +00120.00
Account balance -00035.50
  overdrawn
  fee charged
Fees charged in total: 025.00
$ cobc -x -Wall -o fees-wall fees.cob
$ cobc -x -Wterminator -o fees-count fees.cob 2>&1 | grep -o '[A-Z]* statement not terminated' | sort | uniq -c
   1 ADD statement not terminated
   4 DISPLAY statement not terminated
   1 IF statement not terminated
$ cobc -x -Wterminator -o fees-check fees.cob 2>&1 | grep 'IF statement'
fees.cob:19: warning: IF statement not terminated by END-IF [-Wterminator]
$ cobc -x -Wterminator -o fees-fixed-check fees-fixed.cob 2>&1 | grep 'IF statement' || echo "no IF without END-IF"
no IF without END-IF

The version with the stray period charged the account with 120.00 and totalled 050.00; the fixed one charged only the overdrawn account, 025.00. The -Wall build said nothing about the period. -Wterminator lists every statement that ends without its END- word: in fees.cob four DISPLAY statements, the ADD and the IF. Filtering its output for IF statement found line 19, the IF that ends at a period, and nothing in the fixed version. Follow the false branch for the account in credit:

NEXT SENTENCE jumps past the next period, CONTINUE does nothing

Older code often writes NEXT SENTENCE where nothing should happen. It does not do nothing: it sends control to the statement after the next separator period, and IBM’s documentation adds that inside IF … END-IF, control “does not pass to the statement following the END-IF”. CONTINUE is the statement that does nothing, a “no operation statement”. This program uses one and then the other:

       IDENTIFICATION DIVISION.
       PROGRAM-ID. SKIPS.
      * NEXT SENTENCE and CONTINUE, each inside IF ... END-IF.
       DATA DIVISION.
       WORKING-STORAGE SECTION.
       01  BALANCE      PIC S9(5)V99 VALUE 80.00.
       PROCEDURE DIVISION.
       MAIN-PARA.
           IF BALANCE > ZERO
               NEXT SENTENCE
           END-IF
           DISPLAY "A: after the first END-IF"
           DISPLAY "B: still in the first sentence".
           DISPLAY "C: first statement after the period"
           IF BALANCE > ZERO
               CONTINUE
           END-IF
           DISPLAY "D: after the second END-IF"
           STOP RUN.

from session import files, run

# NEXT SENTENCE jumps past the next period, even from inside IF ... END-IF; CONTINUE does nothing.
files("skips.cob")
run("""
cobc -x skips.cob && ./skips
cobc -x -Wall -o skips-wall skips.cob 2>&1 | grep 'warning:'
""")

$ cobc -x skips.cob && ./skips
C: first statement after the period
D: after the second END-IF
$ cobc -x -Wall -o skips-wall skips.cob 2>&1 | grep 'warning:'
skips.cob:10: warning: NEXT SENTENCE is archaic in GnuCOBOL [-Warchaic]

NEXT SENTENCE skipped A and B, the rest of its sentence, and landed on C, the first statement after the period. CONTINUE let control go on to D. GnuCOBOL’s -Wall reports NEXT SENTENCE as archaic. The two side by side, as skips.cob ran them:

An END-IF closes the nearest open IF

Explicit terminators have a trap of their own when statements nest: each END-IF closes the nearest IF that is still open, whatever the indentation suggests. In this paragraph the END-IF was meant for the outer IF:

       IDENTIFICATION DIVISION.
       PROGRAM-ID. NESTED.
      * Savings accounts get a second message when they are overdrawn.
       DATA DIVISION.
       WORKING-STORAGE SECTION.
       01  ACCOUNT-TYPE PIC X.
       01  BALANCE      PIC S9(5)V99.
       PROCEDURE DIVISION.
       MAIN-PARA.
           MOVE "S" TO ACCOUNT-TYPE
           MOVE 300.00 TO BALANCE
           PERFORM CHECK-ACCOUNT
           MOVE -40.00 TO BALANCE
           PERFORM CHECK-ACCOUNT
           STOP RUN.
       CHECK-ACCOUNT.
           IF BALANCE < ZERO
               DISPLAY "Overdrawn: " BALANCE
               IF ACCOUNT-TYPE = "S"
                   DISPLAY "  savings may not be overdrawn"
           END-IF
           DISPLAY "Checked " BALANCE.

from session import files, run

# One END-IF for two IFs closes the inner one, so the last DISPLAY stays inside the outer IF; the fix adds the second.
files("nested.cob", "nested-fixed.cob")
run("""
cobc -x nested.cob && ./nested
cobc -x nested-fixed.cob && ./nested-fixed
""")

$ cobc -x nested.cob && ./nested
Overdrawn: -00040.00
  savings may not be overdrawn
Checked -00040.00
$ cobc -x nested-fixed.cob && ./nested-fixed
Checked +00300.00
Overdrawn: -00040.00
  savings may not be overdrawn
Checked -00040.00

For 300.00 the first program printed nothing at all. Its only END-IF closed the inner IF, so DISPLAY "Checked " stayed inside the outer IF, whose condition was false, until the period at the end of the paragraph. nested-fixed.cob adds the second END-IF, and it printed Checked +00300.00 for the account in credit. IBM’s guide shows the same with READ: one END-READ under two nested READ statements closes the inner READ, and the fix is a second END-READ.

Practise: divisions, paragraphs and periods

Every answer below can be checked against a session of this lesson. Practice begins where your answers have been weakest, with a reason for every choice:

Interview questions

Warm-up (fresher to 2–5 years): how does a COBOL sentence differ from a statement?

A statement is one action that starts with a verb, such as MOVE, ADD, DISPLAY or IF. A sentence is one or more statements ended by a separator period, a period followed by a space or the end of the line. The difference matters because the period ends every statement still open at that point: an IF whose first statement ends with a period covers only that one statement, and the statements after it run whatever the condition says. Modern style therefore writes each paragraph as a single sentence: no periods inside the logic, END-IF and the other scope terminators to close statements, and one period at the end of the paragraph. A paragraph, in turn, is a name in Area A followed by its sentences.

Two harder questions follow, about fees charged to accounts in credit and about removing NEXT SENTENCE from a legacy program. Note your own answer first, then open each first step:

Key takeaways

• A program has up to four divisions in a fixed order, IDENTIFICATION, ENVIRONMENT, DATA and PROCEDURE, and only the IDENTIFICATION DIVISION with its PROGRAM-ID is required, although the code lives in the PROCEDURE DIVISION.
• Statements make sentences, sentences end at a period, paragraphs are named groups of sentences, and control falls from one paragraph into the next unless a PERFORM returns or STOP RUN or GOBACK ends the run.
• A period ends every statement still open, so a period inside an IF ended it early and charged a fee to an account in credit, 050.00 in fees where 025.00 was right.
• NEXT SENTENCE jumps past the next period, even from inside IF … END-IF, while CONTINUE does nothing, so the two are not interchangeable.
• An END-IF closes the nearest IF still open, so every IF needs its own END-IF, and the period belongs at the end of the paragraph.