Program Structure and Divisions

A COBOL source text is a strict hierarchy. A program has up to four divisions, in a fixed order. Divisions contain sections, sections contain paragraphs, paragraphs contain sentences, and sentences contain statements.

The figure above is the containment tree; the table below says what each level is and how it is written.

Which parts are required differs by standard and compiler. In the ISO standard only PROGRAM-ID is mandatory in the identification division, and the other three divisions can be left out. In practice a main program always has a procedure division, and a program that handles files or data has the other two. Section and paragraph names are the targets that PERFORM can name, and they start in Area A like the division headers; the area rules are on the reference-format page linked above. Procedure division sections are optional: a program can be made of paragraphs only, or of sections that hold paragraphs. Do not mix the two styles in one division, because paragraphs placed before the first section header are not allowed once sections are used.

The identification division names the program. It starts with IDENTIFICATION DIVISION. (in a free-format source, the abbreviation ID DIVISION. is accepted by Enterprise COBOL and GnuCOBOL) and holds paragraphs. PROGRAM-ID is the only paragraph the current standard and the compilers require.

The environment division describes what the program depends on outside itself. It has two sections, both optional:

The data division has up to six sections, in this order when present: FILE SECTION (record layouts of the FD and SD entries), WORKING-STORAGE SECTION (data allocated once for the run unit), LOCAL-STORAGE SECTION (data allocated afresh on each invocation), LINKAGE SECTION (the parameters a program receives, and data it addresses), plus the COMMUNICATION SECTION and REPORT SECTION / SCREEN SECTION where the compiler supports them. A copybook such as BOOKREC is pulled in with COPY (see Copybooks and REPLACE).

The procedure division holds the executable logic. A main program normally has PROCEDURE DIVISION.. A program that receives parameters adds USING (and RETURNING), as in PROCEDURE DIVISION USING LK-TOTAL. below. Execution begins at the first paragraph or section and runs on until a statement stops it or control falls off the end, so every program ends explicitly, as the last section of this page shows. In the Circulation program above, MAIN-LINE SECTION holds MAIN-PARA, and SHOW-BOOK is a second paragraph that PERFORM SHOW-BOOK runs. Put loops and tests in separate paragraphs and call them with PERFORM; the structured style is on PERFORM and Structured Programming.

A period ends a sentence and, with it, every statement scope still open. Writing scope terminators (END-IF, END-READ, END-PERFORM) and putting a single period at the end of the paragraph, as the examples do, avoids the classic bug in which a stray period closes an IF early.

Besides separate source files, COBOL offers a way to keep a small private helper next to its user. A nested program is a complete program (all four divisions) written inside another program, between its procedure division and its END PROGRAM. A source file may also contain several programs one after another (a batch compile). Both forms need END PROGRAM name. so the compiler knows where each one stops.

The names are the first rule. A nested program can be called with CALL "name" only by the program that directly contains it, unless it is declared COMMON, in which case any program inside the same container can call it, including its siblings. A program cannot call a program that contains it. The second rule is the data: names declared in a program are local to it, so two programs can each have WS-CALLS, and a nested program can see a name of its container only if that name is declared GLOBAL. The program below has an outer NIGHTLY program and three nested programs:

COUNTER and FRESH end differently on purpose: EXIT PROGRAM and GOBACK, which the next section compares.

COUNTER counts 1 and 2 because its WS-CALLS lives for the whole run unit. FRESH prints 1 twice, because INITIAL gives it a new copy each time. SHOWER is reached through a COMMON attribute, from two siblings that it does not belong to.

Source: Enterprise COBOL 6.5 Language Reference (PDF) and GnuCOBOL Manual

Nested and multiple programs have practical limits you should know:

Three statements end a program, and picking the wrong one is a classic bug in called programs. The IBM documentation gives this behaviour (the Language Reference tables for STOP, GOBACK and EXIT):

The practical rule: use GOBACK in every program, because it does the right thing whether the program was started as the main program or called as a subprogram. Use STOP RUN only in the main program when you want it to be obvious that the program ends the run, and never in a subprogram that other programs call. EXIT PROGRAM belongs only in called programs. The next program shows what STOP RUN does in a subprogram. DRIVER calls QUITTER, which ends the run unit, so the message after the CALL is never shown:

Source: Enterprise COBOL 6.5 Language Reference: STOP statement, GOBACK statement and EXIT statement

A main program that returns a status to the job passes it through RETURN-CODE before it ends (MOVE 8 TO RETURN-CODE then GOBACK); the job control language (JCL) on z/OS tests it as the step condition code. The error handling page covers that convention.