Reference Format: Fixed and Free

The program below shows every ordinary use of the indicator area apart from the debugging line: a comment line, a page-eject comment, and a literal continued on a second line. It uses the Circulation scenario’s notice text. Note how the paragraph name starts in column 8 (Area A) and every statement starts in column 12 (Area B).

Compiled with cobc -x -Wall and with cobc -x -Wall -std=ibm, with no warnings, it prints the same output both times:

Source: IBM Enterprise COBOL for z/OS 6.5 Language Reference: Reference format and GnuCOBOL Programmer’s Guide: compiler options for the source format

Two details of that listing are worth remembering. First, only the first line of each statement has to start in Area B: text may continue anywhere in Area B on the lines after it, so a long DISPLAY or COMPUTE is normally wrapped at a clause boundary and indented. Second, a blank sequence number area is not required; the six columns are simply not looked at. Code copied from a file with line numbers in columns 73 to 80, or in columns 1 to 6, therefore compiles unchanged, which is also why editors and source-control tools can stamp change flags there.

The standard and IBM’s Language Reference fix, for each kind of item, whether it must begin in Area A, in Area B, or in either. The rule set is short in practice:

How strictly the compiler checks this depends on the compiler. Enterprise COBOL expects these items where the Language Reference puts them. GnuCOBOL does not check the areas at all in its default fixed format; with -std=ibm it checks them and reports a warning, and with -fformat=cobol85 plus -fareacheck it reports an error. The deliberately wrong program below puts a paragraph name in column 12:

The output below is real. With -std=ibm (which turns the Area A check on as a warning) the same program prints warning: 'MAIN-PARA' should start in Area A [-Wothers] and then runs; with plain cobc -x -Wall it compiles silently and prints Area A check.

Source: GnuCOBOL Programmer’s Guide: -fformat= values and Area A enforcement (-fareacheck)

GnuCOBOL’s own manual explains the purpose: Area A enforcement exists to help develop programs that are portable to real mainframe environments, and it also lets the compiler recover from a missing period between paragraphs and sections. The practical advice is to keep to the layout the table above gives even where the compiler you use does not insist on it, because the code will then move between compilers without edits.

A * in column 7 turns the whole line into a comment. The text after it can be anything, including COBOL words, and it is printed in the compiler listing but never compiled. A / in column 7 does the same and additionally asks the compiler to start a new page in the listing at that line, which is why a / comment often precedes a major section. Inside a program a comment line can appear between any two lines, including in the middle of a statement that continues over several lines. The fixed1.cob listing above uses both.

COBOL 2002 added the floating comment indicator *>. It begins a comment anywhere on a line (outside a literal) and the comment runs to the end of the line. It lets a comment follow a statement or a data description entry, which a column-7 comment cannot. It works in both fixed and free format, and Enterprise COBOL and GnuCOBOL both accept it in fixed format, as the program below shows for GnuCOBOL.

Source: GnuCOBOL Programmer’s Guide: source format and comments

A D or d in column 7 makes the line a debugging line. The compiler treats it as a comment unless the program says it is in debugging mode, by writing WITH DEBUGGING MODE on the SOURCE-COMPUTER paragraph of the Configuration Section; then the line is compiled as an ordinary line. That lets a team keep trace DISPLAY statements in the source and switch them all on by editing one line. The program below has the clause, so it compiles and prints the debug line:

Without WITH DEBUGGING MODE (the same source with that clause deleted) the debug line is skipped and only Loans processed is printed. The same output was produced with -std=ibm. Source: IBM Enterprise COBOL for z/OS 6.5 Language Reference: Reference format, indicator area

In free format there are no columns, so GnuCOBOL provides the >>D directive for the same purpose; it is covered, with the other directives, on Compiler Directives and Conditional Compilation.

The most common error is to wrap the first line earlier than column 72. The compiler then treats the missing columns as spaces, so the literal silently contains a long run of blanks. This is the first of three deliberately wrong continuation examples, each with the real compiler output.

GnuCOBOL 3.2 compiles it, but with a truncation warning, because the literal contains the blanks and is therefore 88 characters long and does not fit PIC X(80); the run then shows the gap:

Source: IBM Enterprise COBOL for z/OS 6.5 Language Reference: Reference format (continuation lines)

The second is a missing hyphen in column 7. The continuation line is then read as a new line of text, the quotation mark opens a new literal, and the compiler stops with real errors:

Source: GnuCOBOL Programmer’s Guide: compiler messages

The third is text beyond column 72. Everything in columns 73 to 80 is ignored, so a literal that is longer than the margin is cut at column 72 and the compiler reports an unterminated literal:

Source: GnuCOBOL Programmer’s Guide: compiler messages

A statement element that is not a literal is not even reported: when a whole word is pushed into columns 73 to 80, the compiler never sees it. The program over73.cob below writes DISPLAY "Fine:" in Area B and WS-FINE starting in column 74. GnuCOBOL 3.2 compiles it, with no diagnostic even with -Wcolumn-overflow, and displays only the literal; Enterprise COBOL likewise ignores columns 73 to 80.

The standard also allows a word or a numeric literal to be continued the same way, but in practice never split a word: split a statement at a space instead, and for long text use concatenation, as the next section shows.

COBOL 2002 added a literal concatenation operator, the ampersand &. It joins two or more literals at compile time and lets each be written on a line of its own without reaching column 72 or using a column-7 hyphen. The Circulation notice again:

It compiled without warnings under both cobc -x -Wall and cobc -x -Wall -std=ibm. The operator is part of the standard from COBOL 2002; confirm in the Language Reference of your Enterprise COBOL release that your release accepts it before using it in code that must also be compiled on z/OS. Source: GnuCOBOL Programmer’s Guide: literals

The format can be chosen on the command line or inside the source:

In GnuCOBOL 3.2 the directive on the first line of a file is also detected without any option, which the compiler tells you with a note:

That automatic detection is a GnuCOBOL convenience, not a language feature. With -std=ibm it is switched off: the same file then reads the first lines as fixed format and reports one error per line, for example error: invalid indicator 'C' at column 7 for >>SOURCE, because the first character after column 6 is taken as the indicator. With -std=ibm -fformat=free it compiles and runs. This is a useful test of how a file will be read on a compiler that does not guess.

Source: GnuCOBOL Programmer’s Guide: -fformat= and the >>SOURCE directive

The GnuCOBOL manual lists the values accepted by -fformat= and by the >>SOURCE FORMAT directive. They cover the formats of other vendors' compilers, which helps when moving code to GnuCOBOL.

The programs written for this section use fixed only, plus free where it says so. Two other source-format options are worth knowing. -fareacheck turns the Area A checks on for the formats that have an Area A, and the warning -Wcolumn-overflow ("Warn if text after column 72 in FIXED format", not enabled by -Wall) exists for text beyond column 72; as the over73 example above shows, it did not report that case in 3.2.0. The dialect chosen with -std= also changes how strictly the areas are checked, as the -std=ibm run of the Area A example showed.

Variable format, as an example, is useful when a program was edited without respect to column 72. The following statement is one 99-column line, so with the default fixed format the literal is cut at column 72 and the compiler reports an error, and with -fformat=variable it compiles and runs.

Source: GnuCOBOL Programmer’s Guide: the variable format