COBOL data division

COBOL declares data as records: a record is a group of items, each with a level number, a name and clauses that say how it looks in memory. There are no local variable declarations inside statements; everything lives in one of the sections below. The way a value is written (PIC and USAGE) is on Picture and usage.

Sections

Section	Holds	Storage
`FILE SECTION`	`FD` (file description) and `SD` (sort-merge file description) entries, each followed by its record layouts	The record area of each file, shared by all records of that file
`WORKING-STORAGE SECTION`	Items the program owns	Allocated when the program is first called; keeps values between calls (unless `INITIAL` or `CANCEL`)
`LOCAL-STORAGE SECTION` (COBOL-85 Amendment, 2002)	Items per invocation	Allocated and re-initialised on each call; needed for recursion and threads
`LINKAGE SECTION`	Items that belong to the caller (parameters) or are addressed with `SET ADDRESS`	No storage of its own
`COMMUNICATION SECTION`	`CD` entries for the message-control facility	Removed from the standard in 2002; IBM and GnuCOBOL do not support sending real messages
`REPORT SECTION`	`RD` report descriptions for the Report Writer, see Report Writer and screens	Report groups
`SCREEN SECTION`	Screen layouts for `ACCEPT` and `DISPLAY` (Micro Focus, GnuCOBOL, ACUCOBOL; standardised in 2002 and made optional in 2014)	Screen items

Sections must appear in the order shown. Classes (Object-oriented COBOL) have their own WORKING-STORAGE in the FACTORY and OBJECT paragraphs.

Level numbers

Level	Meaning
`01`	A record or independent item. Starts in Area A. A record may be a group (with sub-items) or an elementary item.
`02` to `49`	Sub-items. A higher number is subordinate to the closest preceding lower one. Group items have sub-items and no `PIC`; elementary items have a `PIC` (or a `USAGE` that needs none). Group items are always alphanumeric, unless `GROUP-USAGE` (2002) says national.
`66`	`RENAMES`: gives a second name to a range of items in a record.
`77`	An independent elementary item with no record structure (equivalent to a one-item `01`; no longer needed).
`78`	Constant entry in Micro Focus and GnuCOBOL: `78 MAX-ROWS VALUE 50.` Replaced in 2002 by the `CONSTANT` clause on `01`.
`88`	A condition name: a named test on the value of the item above it, with `VALUE` or `VALUES ARE` and `THRU` ranges; usable as a condition and as a `SET … TO TRUE` target.

       01  EMPLOYEE.
           05  EMP-ID          PIC 9(6).
           05  EMP-NAME.
               10  FIRST-NAME  PIC X(15).
               10  LAST-NAME   PIC X(20).
           05  EMP-STATUS      PIC X.
               88  ACTIVE      VALUE "A".
               88  RETIRED     VALUE "R" "P".
               88  KNOWN       VALUE "A" THRU "Z".
           05  EMP-PAY         PIC S9(7)V99 COMP-3.
       66  FULL-NAME RENAMES FIRST-NAME THRU LAST-NAME.
       77  RECORD-COUNT        PIC 9(5) VALUE 0.
       78  MAX-ROWS            VALUE 50.
       01  FLAG-LIMIT          CONSTANT 100.

A record with a group, a condition name, a renaming and constants

Names are unique within their scope or are qualified: FIRST-NAME OF EMP-NAME OF EMPLOYEE. FILLER (or no name in 2002 and later) gives an item no name. CORRESPONDING (CORR) statements pair items of two groups by name.

Data description clauses

Clauses follow the name in any order (except that REDEFINES comes first) and the entry ends with a full stop.

Clause	Effect
`PICTURE` / `PIC` [`IS`] string	Category, size and editing of an elementary item. See Picture and usage.
`USAGE` [`IS`] type	Storage format (`DISPLAY`, `BINARY`, `COMP-3`…). The word `USAGE` is optional.
`VALUE` [`IS`] literal	Initial value (at program start in `WORKING-STORAGE`, on each call in `LOCAL-STORAGE`); in level 88, the values that make the condition true. Not allowed in the file or linkage section, except on 88 levels. `VALUE ALL` and `VALUE ZERO` fill the item.
`OCCURS` n [`TIMES`]	A table of n copies. See below.
`REDEFINES` name	This item shares storage with an earlier item of the same level and the same group. The redefining item may not carry `VALUE` (except level 88), and below level 01 it may be no larger than the item it redefines.
`RENAMES` a [`THRU` b]	Level 66 only.
`JUSTIFIED` / `JUST` [`RIGHT`]	Right-justifies a move into an alphabetic or alphanumeric item.
`BLANK WHEN ZERO`	Shows an all-blank field when the numeric value is zero.
`SIGN` [`IS`] `LEADING` \| `TRAILING` [`SEPARATE` [`CHARACTER`]]	Where the sign of a signed `DISPLAY` number is held: as an overpunch in the first or last digit, or as a separate `+` or `-` character.
`SYNCHRONIZED` / `SYNC` [`LEFT` \| `RIGHT`]	Align binary, pointer and floating items to their natural boundaries (slack bytes are added); important when a record is shared with C or a file.
`EXTERNAL`	One copy shared by every program in the run unit that declares the same name (01 level).
`GLOBAL`	Visible to nested programs, which do not need to declare it again.
`BASED` (2002)	No storage until `ALLOCATE` or `SET ADDRESS`.
`CONSTANT` (2002)	`01 N CONSTANT 5` or `CONSTANT FROM`, a named constant.
`TYPEDEF` and `TYPE` (2002)	Define a named data type (`01 PRICE-T TYPEDEF PIC 9(5)V99.`) and use it (`01 P TYPE PRICE-T.`). IBM has supported it since Enterprise COBOL 6.
`GROUP-USAGE` [`IS`] `BIT` \| `NATIONAL` (2002)	Makes a group of bit or national items.
`PROPERTY` (2002)	In a class: a data item with generated getters and setters.
`ALIGNED`, `ANY LENGTH`, `SELECT WHEN`, `PRESENT WHEN`, `VOLATILE`, `DEFAULT` (2002 and 2014)	Boolean alignment; unknown-size linkage items; conditional presence in a `JSON` or `XML` document; no caching; default value in a screen.
`DYNAMIC LENGTH` (2014)	A string item whose length is held at run time.

Tables, indexes and subscripts

OCCURS makes a table. The item and everything under it repeats.

OCCURS 10 TIMES is a fixed-size table. COBOL-85 allows seven nested OCCURS levels (COBOL-74 three); COBOL 2002 raised the limit to 15.
OCCURS 1 TO 100 TIMES DEPENDING ON N is variable-length: N says how many entries are in use. In a record the length changes with it.
ASCENDING KEY IS name or DESCENDING KEY says the table is in order, which SEARCH ALL relies on.
INDEXED BY name declares an index, a special item (displacement or occurrence number) handled with SET and used as a subscript.
OCCURS DYNAMIC CAPACITY (2014) is a table that grows.
A subscript names an entry: PRICE(3), MATRIX(ROW, COL), ITEM(IDX + 1) (index relative: IDX + 1 only with an index), ITEM(ALL) in intrinsic function arguments (2002).

Reference modification takes a part of an alphanumeric or national item: NAME(2:5) is five characters from character 2; NAME(3:) runs to the end.

       01  MONTHS.
           05  MONTH-NAME OCCURS 12 TIMES
                   INDEXED BY M-IX      PIC X(9).
       01  SALES-TABLE.
           05  SALE OCCURS 1 TO 500 TIMES DEPENDING ON SALE-COUNT
                   ASCENDING KEY IS SALE-DATE
                   INDEXED BY S-IX.
               10  SALE-DATE   PIC 9(8).
               10  SALE-AMT    PIC S9(7)V99 COMP-3.
       77  SALE-COUNT          PIC 9(3) COMP.

File section entries

An FD names a file declared in FILE-CONTROL and describes its records. Its clauses (File handling has the I/O side):

BLOCK CONTAINS n [CHARACTERS | RECORDS], RECORD CONTAINS n [TO m] CHARACTERS, RECORD IS VARYING IN SIZE FROM a TO b DEPENDING ON name
LABEL RECORDS ARE STANDARD | OMITTED, DATA RECORDS ARE …, VALUE OF …: obsolete in COBOL-85 and removed later; compilers still accept them.
LINAGE IS n LINES [WITH FOOTING AT f] [LINES AT TOP t] [LINES AT BOTTOM b] for page layout of printed output; sets LINAGE-COUNTER.
CODE-SET IS alphabet-name, EXTERNAL, GLOBAL, REPORT IS name (hands the file to the Report Writer), RECORDING MODE IS F | V | U | S (IBM).

An SD describes the work file of a SORT or MERGE in the same way. Several 01 records under one FD share the same record area, so writing one overlays the others.

Initial values

Items without VALUE have undefined contents in the standard; what a compiler does is its own choice (GnuCOBOL initialises them by category by default). The INITIALIZE statement sets items by category (numbers to zero, text to spaces), with the phrases WITH FILLER, TO VALUE and THEN REPLACING.

Linkage and parameters

The PROCEDURE DIVISION USING a b c header names the linkage items that stand for the caller’s arguments, by reference (the default), BY CONTENT (a copy that the callee cannot change) or BY VALUE (2002). RETURNING r names the result. OMITTED passes no argument. CHAINING (Micro Focus, GnuCOBOL) takes command-line arguments. See CALL.

.CBL File Format – Data division