.CBL File Format – File structure

Characters, encodings and line endings

• Character set. The standard names a COBOL character set of letters, digits, space and the special characters + - * / = $ , ; . " ' ( ) > < : & _. Comments and literals may hold any character the machine has.
• ASCII and its extensions on Windows, Linux and Unix. GnuCOBOL reads source as single-byte text and passes bytes above 127 through inside literals and comments; Micro Focus compilers read the current code page and, with a byte-order mark, UTF-8.
• EBCDIC on IBM z/OS and other IBM mainframes. Source there is held in fixed-length records, usually 80 bytes wide, with no line ending at all; a source member is not a stream. When it is downloaded it is converted to ASCII, often with a line ending added at column 80 or after trimming trailing blanks. A file still in EBCDIC is not shown as COBOL text by the viewer, because it holds bytes that are not text.
• Line endings are LF, CRLF or (on old Mac and some Micro Focus line-sequential sources) CR. A Ctrl-Z (0x1A) byte may end a DOS-era file. The viewer reads all three line endings and treats a Ctrl-Z as a blank.
• Tabs. The standard has none. Micro Focus and GnuCOBOL expand a tab to the next tab stop (eight columns by default); a tab in the first six columns puts the code in Area A or B with no indicator. The viewer treats a tab in the first seven columns as “no sequence area and no indicator”.
• Case. COBOL words are not case-sensitive in any dialect that matters. Literals are, and so is the content of a comment.

Divisions, sections, paragraphs, sentences

A program is a series of up to four divisions, in this order. Each division is made of sections (a name, the word SECTION, a full stop) and paragraphs (a name and a full stop); a paragraph holds sentences, and a sentence is one or more statements ended by a full stop.

Each header is a word, the word DIVISION or SECTION and a full stop. The IDENTIFICATION DIVISION header is optional in 2002 and later; a lone PROGRAM-ID paragraph is enough in GnuCOBOL and Micro Focus. A program with no PROCEDURE DIVISION is allowed only as a copybook fragment or a class with no behaviour. See Data division and Statements for what goes in them.

       IDENTIFICATION DIVISION.
       PROGRAM-ID. SHOWDATE.
       ENVIRONMENT DIVISION.
       CONFIGURATION SECTION.
       SPECIAL-NAMES.
           DECIMAL-POINT IS COMMA.
       DATA DIVISION.
       WORKING-STORAGE SECTION.
       01  WS-TODAY.
           05  WS-YEAR   PIC 9(4).
           05  WS-MONTH  PIC 99.
           05  WS-DAY    PIC 99.
       PROCEDURE DIVISION.
       MAIN-PARA.
           ACCEPT WS-TODAY FROM DATE YYYYMMDD
           DISPLAY WS-DAY "/" WS-MONTH "/" WS-YEAR
           STOP RUN.

Programs in one file

• A file holds one program, or several in a compilation group. Each program may end with END PROGRAM name.; the last one need not. Classes end with END CLASS, methods with END METHOD, functions with END FUNCTION.
• A program placed inside another before the outer one’s END PROGRAM is nested (COBOL-85). Without COMMON it can be called only by the program that contains it; names declared GLOBAL are visible inside it.
• Programs placed one after another are separate programs; with GnuCOBOL one object module comes out for the file.
• A file can instead hold a copybook: a piece of a program, such as a record layout, brought in by COPY (see Compiler directives). It has no division headers of its own, begins at a level number and often ends mid-program.

Reference format

Reference format says which columns of a line mean what. The 1960s to 1985 standards know only the fixed format of an 80-column card. COBOL 2002 added a free format. Compilers add further variants.

Fixed format

A statement may start in Area A or B unless it names something that must be in A. COBOL compilers of today (GnuCOBOL, IBM, Micro Focus) are lenient about Area A and B for most items; strict placement is a standard requirement and a style rule.

000100 IDENTIFICATION DIVISION.                                         HELLO001
000200 PROGRAM-ID. HELLO.                                               HELLO002
000300* A COMMENT LINE HAS AN ASTERISK IN COLUMN 7.                     HELLO003
000400 DATA DIVISION.                                                   HELLO004
000500 WORKING-STORAGE SECTION.                                         HELLO005
000600 01  MSG  PIC X(60) VALUE "THIS TEXT RUNS ALL THE WAY TO COLUMN 72
000700-    " AND CARRIES ON".                                           HELLO007
000800 PROCEDURE DIVISION.                                              HELLO008
000900     DISPLAY MSG.                                                 HELLO009
001000     STOP RUN.                                                    HELLO010

Continuation. A - in column 7 continues the previous line. A nonnumeric literal that runs to column 72 continues on the next line, whose first non-blank character after the hyphen is a quotation mark of the same kind; the text carries on after it. The same marker can split a word or numeric literal, a use the standards allow and GnuCOBOL warns about. Pseudo-text continues without a hyphen. See Lexical structure.

Free format

COBOL 2002 and later allow free format: no sequence area, no indicator column, no Area A and B, and a line may be as long as the compiler allows (255 characters in GnuCOBOL; each compiler states its own limit). Rules in GnuCOBOL’s documentation:

• A line whose first non-blank characters are *> is a comment, and *> starts a comment anywhere else on a line.
• There is no / comment.
• A debugging line starts with >>D.
• A literal too long for a line is written as pieces joined with the & operator.
• Compiler directives start with >> and may begin in any column.

>>SOURCE FORMAT IS FREE
IDENTIFICATION DIVISION.
PROGRAM-ID. greet.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 who PIC X(20) VALUE "World" &
   " and friends".   *> two pieces joined with &
PROCEDURE DIVISION.
    DISPLAY "Hello, " FUNCTION TRIM(who)
    STOP RUN.

Choosing a format

• GnuCOBOL: the -free and -fixed options of cobc; in the source >>SOURCE FORMAT IS FREE or FIXED, >>SET SOURCEFORMAT AS FREE or >>DEFINE FORMAT IS FREE. Fixed is the default. In fixed format a >> directive starts in column 8 or later.
• Micro Focus: $SET SOURCEFORMAT"FREE" (also "FIXED", "VARIABLE"), or the project setting; the ANSI format is the fixed one.
• IBM Enterprise COBOL 6.2 and later: >>SOURCE FORMAT IS FREE. Fixed-form is the default.
• A free-format file begins with nothing special; the viewer decides from the text (a line whose column 7 cannot be an indicator, or a comment starting *> in column 1, says free; six-digit sequence numbers say fixed) and follows the directives from there.

Other layouts

• Variable format (Micro Focus SOURCEFORMAT"VARIABLE"): like fixed format but a line may run past column 72 and the identification area does not exist. The viewer does not cut a line longer than 80 columns.
• Terminal format (Micro Focus): no sequence area; the indicator is in column 1 and code starts in column 7. The viewer does not know this layout.
• Punched-card and listing files have page headings and line numbers added by the compiler; they are listings, not source.

File extensions and conventions

On z/OS there is no extension: a program is a member of a partitioned data set such as USER.COBOL.SOURCE(PAYROLL), copybooks live in USER.COPYLIB, and JCL names them. See Dialects and versions. Files the compiler writes (Micro Focus .int, .gnt, .idy; GnuCOBOL .c, .o, .so; listings .lst) are not COBOL source.