Data first
In most languages you think about the code first and let the data take whatever shape the code needs. COBOL turns that around. Before a single statement runs, the data division describes every item the program will touch, character by character: how wide it is, whether it holds digits or text, where its decimal point sits, and how items nest inside records.
There is a practical reason for this. Business systems are built around records: a customer, an account, a payment, an employee. Those records are written to files and read back by other programs, sometimes written in other decades by other teams. A file of payments is just a long run of bytes; what turns it into payments is a precise agreement about which bytes mean what. In COBOL that agreement is the data division. When two programs share the same record description (usually through a shared file called a copybook, which lesson 7 covers), they agree, exactly, about every field.
This lesson teaches you to write and read those descriptions. It is the most important skill in reading real COBOL, because in a typical business program the data division is often longer than the procedure division, and most bugs trace back to a field that was too small, a sign that was dropped or a record that was laid out differently from the file.
Levels, pictures and usage
Level numbers
Each data description entry starts with a level number that says where the item sits in a hierarchy:
| Level | Meaning |
|---|---|
01 | A record or a top-level item. Every hierarchy starts here. |
02 to 49 | A subordinate item inside the 01 above it. Higher numbers nest deeper. |
77 | An independent item that is never part of a record (an older style; 01 does the same job) |
88 | A condition name: a named test on the value of the item above it |
66 | RENAMES, a rarely used way of regrouping fields |
An item with subordinate items is a group item; an item without them is an elementary item, and only elementary items have a PIC clause. A group item has no type of its own: it is simply the concatenation of its parts, treated as characters. Programmers number levels in steps of five (01, 05, 10, 15) so that a level can be inserted later without renumbering.
Definition— Picture clause
The PICTURE (usually PIC) clause of an elementary item is a string of symbols, one per character position or digit, describing the item's size and category. A number in brackets repeats the symbol before it: 9(5) is the same as 99999.
The main picture symbols
| Symbol | Meaning | Takes a position? |
|---|---|---|
9 | A decimal digit | Yes |
X | Any character | Yes |
A | A letter or space | Yes |
V | Where the implied decimal point sits | No: the point is not stored |
S | The number has a sign | No with the default usage: the sign shares a byte with a digit |
P | A scaling position (rare; it assumes zeros) | No |
So PIC S9(5)V99 is a signed number with five digits before the point and two after: seven digits, stored in seven bytes. PIC X(30) is thirty characters. PIC 9(8) is an eight-digit number, often a date such as 20261119.
Usage
The usage of an item says how it is stored. The default is USAGE DISPLAY: one character per digit, readable if you print the bytes, which is why files of DISPLAY numbers can be opened in a text editor. Lesson 3 introduces the other usages, COMP-3 (packed decimal) and COMP/BINARY, which store numbers more compactly. In this lesson everything is DISPLAY.
VALUE, FILLER and figurative constants
VALUE gives an item its starting value when the program begins. FILLER (or simply no name at all) declares a position you never refer to by name, typically spaces between columns of a printed line. COBOL also has figurative constants, words that stand for "as many as needed" of a character: SPACE or SPACES, ZERO, ZEROS or ZEROES, HIGH-VALUES and LOW-VALUES (the largest and smallest byte values), QUOTE, and ALL "literal", which repeats a literal to fill the item.
Records, MOVE and edited pictures
A record and its fields
Here is a customer record. The group items cust-name and birth-date contain smaller fields, and an 88 level names a test on the country code:
IDENTIFICATION DIVISION.
PROGRAM-ID. customer-layout.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 customer-record.
05 cust-id PIC 9(5).
05 cust-name.
10 first-name PIC X(10).
10 last-name PIC X(12).
05 birth-date.
10 birth-year PIC 9(4).
10 birth-month PIC 99.
10 birth-day PIC 99.
05 country-code PIC XX.
88 in-east-asia VALUE "JP" "KR" "CN" "MN" "TW".
PROCEDURE DIVISION.
MOVE "00042Mei Tanaka 19870314JP" TO customer-record
DISPLAY "id: " cust-id
DISPLAY "first: " first-name
DISPLAY "last: " last-name
DISPLAY "born: " birth-day "/" birth-month "/" birth-year
DISPLAY "country: " country-code
IF in-east-asia
DISPLAY "region: East Asia"
END-IF
DISPLAY "record length: " FUNCTION LENGTH(customer-record)
ADD 1 TO cust-id
DISPLAY "[" customer-record "]"
STOP RUN.id: 00042
first: Mei
last: Tanaka
born: 14/03/1987
country: JP
region: East Asia
record length: 37
[00043Mei Tanaka 19870314JP]The single MOVE of a 37-character string into the group filled every field at once, because a group is nothing but its bytes laid end to end: 5 for the id, 10 and 12 for the names, 4, 2 and 2 for the date, 2 for the country. That is exactly what happens when a program reads a record from a file: the bytes arrive, and the field descriptions give them meaning. ADD 1 TO cust-id then changed five bytes in the middle of the record, and displaying the whole group shows the change.
The 88 level in-east-asia is not storage. It is a name for the condition "country-code is one of these values", so IF in-east-asia reads like English. Condition names are one of COBOL's best features: the meaning of a code lives in one place, next to the field, instead of being repeated in every IF. Lesson 4 uses them for flags and loop control.
The rules of MOVE
MOVE copies a value into one or more items, converting it to the receiver's format. The rules depend on the receiver:
- Alphanumeric receiver (
PIC X): characters are placed from the left. A shorter value is padded with spaces on the right; a longer one is cut off on the right. - Numeric receiver (
PIC 9): the value is aligned on the decimal point. Missing digits become zeros; extra digits are cut off on both ends: high-order digits on the left, extra decimal places on the right. A negative value moved into an unsigned item loses its sign.
None of this is an error. COBOL does exactly what the pictures say, silently:
IDENTIFICATION DIVISION.
PROGRAM-ID. move-rules.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 city-short PIC X(5).
01 city-long PIC X(12).
01 two-digits PIC 99.
01 money PIC 9(4)V99.
01 unsigned-n PIC 9(3).
01 signed-n PIC S9(3) VALUE -125.
01 as-text PIC X(6).
PROCEDURE DIVISION.
MOVE "Montevideo" TO city-short
DISPLAY "[" city-short "]"
MOVE "Ulm" TO city-long
DISPLAY "[" city-long "]"
MOVE 2026 TO two-digits
DISPLAY "[" two-digits "]"
MOVE 7.5 TO money
DISPLAY "[" money "]"
MOVE 123.456 TO money
DISPLAY "[" money "]"
MOVE signed-n TO unsigned-n
DISPLAY "[" unsigned-n "]"
MOVE 42 TO as-text
DISPLAY "[" as-text "]"
STOP RUN.[Monte]
[Ulm ]
[26]
[0007.50]
[0123.45]
[125]
[42 ]Look at each line. "Montevideo" lost its last five letters. "Ulm" was padded to twelve characters. The year 2026 became 26, because a two-digit field keeps the two rightmost digits: this is precisely how two-digit years caused the year-2000 problem. 7.5 was aligned on the point and padded with zeros; 123.456 lost its third decimal place (truncated, not rounded). The sign of −125 vanished. And the number 42 moved into a text field became the characters 42 followed by spaces.
GnuCOBOL shows the implied decimal point when it displays a V item (0007.50). Other compilers may show only the stored digits (000750). Never rely on DISPLAY of raw numeric items for output people will read; move them into an edited picture instead.
Edited pictures: formatting numbers for people
An edited picture is a picture used only as the receiver of a MOVE, to turn a number into readable text. Its symbols insert characters or replace leading zeros:
| Symbol | Effect |
|---|---|
Z | A digit, but a leading zero becomes a space |
* | A digit, but a leading zero becomes an asterisk (cheque protection) |
, and . | Insert a comma or the decimal point (swapped by DECIMAL-POINT IS COMMA) |
$ (repeated) | A currency sign that floats to just before the first significant digit |
- or + | A sign; repeated, it floats. - shows only for negatives; + shows + or - |
CR, DB | Accountants' credit and debit markers, shown only for negative values |
B, 0, / | Insert a space, a zero or a slash |
The same value moved into different edited pictures shows the range:
IDENTIFICATION DIVISION.
PROGRAM-ID. edited-pictures.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 amount PIC S9(5)V99.
01 plain-z PIC ZZ,ZZ9.99.
01 cheque PIC **,**9.99.
01 currency-out PIC $$$,$$9.99.
01 credit-debit PIC ZZ,ZZ9.99CR.
01 leading-sign PIC -ZZ,ZZ9.99.
01 floating-sign PIC ---,--9.99.
01 trailing-plus PIC ZZ,ZZ9.99+.
01 iso-date PIC 9999/99/99.
01 date-digits PIC 9(8) VALUE 20261119.
01 spaced PIC XXXBXXXBXXXX.
PROCEDURE DIVISION.
MOVE -1234.5 TO amount
MOVE amount TO plain-z DISPLAY "Z: [" plain-z "]"
MOVE amount TO cheque DISPLAY "*: [" cheque "]"
MOVE amount TO currency-out DISPLAY "$: [" currency-out "]"
MOVE amount TO credit-debit DISPLAY "CR: [" credit-debit "]"
MOVE amount TO leading-sign DISPLAY "fixed -: [" leading-sign "]"
MOVE amount TO floating-sign DISPLAY "float -: [" floating-sign "]"
MOVE amount TO trailing-plus DISPLAY "+: [" trailing-plus "]"
MOVE 7 TO amount
MOVE amount TO plain-z DISPLAY "Z: [" plain-z "]"
MOVE amount TO cheque DISPLAY "*: [" cheque "]"
MOVE amount TO credit-debit DISPLAY "CR: [" credit-debit "]"
MOVE amount TO floating-sign DISPLAY "float -: [" floating-sign "]"
MOVE amount TO trailing-plus DISPLAY "+: [" trailing-plus "]"
MOVE date-digits TO iso-date DISPLAY "date: [" iso-date "]"
MOVE "0215550123" TO spaced DISPLAY "phone: [" spaced "]"
STOP RUN.Z: [ 1,234.50]
*: [*1,234.50]
$: [ $1,234.50]
CR: [ 1,234.50CR]
fixed -: [- 1,234.50]
float -: [ -1,234.50]
+: [ 1,234.50-]
Z: [ 7.00]
*: [*****7.00]
CR: [ 7.00 ]
float -: [ 7.00]
+: [ 7.00+]
date: [2026/11/19]
phone: [021 555 0123]Several professional lessons hide in that output:
Zalone drops the sign. The first line shows −1234.50 as a positive-looking1,234.50. If a value can be negative, its edited picture must have a sign symbol orCR/DB. This mistake has printed refunds as charges on real statements.- The comma disappears with the leading zeros. For the value 7, the
Zs and the comma both turned into spaces, so you never see, 7.00. - A fixed sign stays put; a floating sign moves.
-ZZ,ZZ9.99leaves a gap between the minus and the digits;---,--9.99puts the minus right against them. The same is true of a floating currency sign. - Edited items are text. You cannot do arithmetic on
plain-z. Keep the number in a numeric item and move it to an edited item only for output. - Insertion works on text and dates too.
Band/split a phone number or a date without any string handling.
The currency sign is $ by default. The CURRENCY SIGN clause in SPECIAL-NAMES can choose another single character, and the 2002 standard added multi-character signs such as EUR with a separate picture symbol. Compiler support for that newer form varies (GnuCOBOL 3.2 warns that it is not yet implemented), so many systems simply print the currency code in a separate column.
REDEFINES, INITIALIZE and figurative constants
REDEFINES gives a second description of the same bytes. It is how COBOL views a date as one eight-digit number and as three parts, or a record whose layout depends on a type code. INITIALIZE resets a group sensibly: alphanumeric fields to spaces and numeric fields to zeros.
IDENTIFICATION DIVISION.
PROGRAM-ID. redefines-demo.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 order-date PIC 9(8).
01 order-date-parts REDEFINES order-date.
05 od-year PIC 9(4).
05 od-month PIC 99.
05 od-day PIC 99.
01 order-line.
05 ol-product PIC X(10) VALUE "Teff flour".
05 ol-quantity PIC 9(3) VALUE 25.
05 ol-price PIC 9(3)V99 VALUE 4.80.
01 rule PIC X(30) VALUE ALL "=-".
PROCEDURE DIVISION.
MOVE 20261119 TO order-date
DISPLAY "year " od-year ", month " od-month ", day " od-day
MOVE 12 TO od-month
DISPLAY "whole date now " order-date
DISPLAY rule
DISPLAY "[" order-line "]"
INITIALIZE order-line
DISPLAY "[" order-line "]"
MOVE SPACES TO order-line
DISPLAY "[" order-line "]"
MOVE ZEROS TO ol-quantity
DISPLAY "[" order-line "]"
STOP RUN.year 2026, month 11, day 19
whole date now 20261219
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
[Teff flour02500480]
[ 00000000]
[ ]
[ 000 ]Changing od-month changed order-date, because they are the same two bytes. Note the difference between INITIALIZE, which put zeros in the numeric fields, and MOVE SPACES to the group, which put spaces everywhere, including in ol-quantity and ol-price. A group move never looks at the fields inside; it copies characters. Spaces in a numeric DISPLAY field are invalid data, and the last line shows the repair: MOVE ZEROS TO ol-quantity fixed one field, but ol-price still holds spaces.
How professionals lay out data
Experienced COBOL programmers treat the data division as the design of the program. Some habits worth adopting from the start:
- Prefixes show where an item lives.
ws-for working storage, a record prefix such ascust-orpay-for every field of a record,ls-for linkage items. You can then tell at a glance where any name in the procedure division comes from, and you never collide with a reserved word. - Size fields for the worst case, with room to spare. Ask what the largest legitimate value is, then add a digit. Many production incidents are a total that outgrew its picture.
- Signed by default for amounts. Refunds, corrections and reversals happen.
S9(9)V99is a common choice for money. - Test incoming numeric fields. Data from files and screens can be wrong. The class test
IF pay-amount IS NUMERICchecks that aDISPLAYfield really contains digits (and a valid sign) before you compute with it. On IBM mainframes, arithmetic on a field that holds spaces or letters stops the program with a data exception, known by its abend code S0C7, which every mainframe programmer learns to recognise early. - Condition names instead of magic values.
88 account-closed VALUE "C".beatsIF acct-status = "C"scattered through the code.
Common misconceptions
Misconception
"The V in a picture is stored as a decimal point." It is not stored at all. PIC 9(4)V99 is six bytes, not seven. The compiler remembers where the point is and aligns arithmetic and moves accordingly. An edited picture with . is different: there the point is a real character.
Misconception
"COBOL will warn me if a value does not fit." MOVE truncates silently according to the rules above. Arithmetic statements can detect overflow with ON SIZE ERROR (lesson 3), but MOVE cannot. Size fields generously and check data at the boundary.
Misconception
"Moving a group converts each field." A move to or from a group item is a plain character copy, whatever the fields inside are. That is useful (it is how records are read) and dangerous (it can put spaces into numeric fields).
Misconception
"An 88-level is a variable." A condition name takes no storage. It names a test on its parent item; SET name TO TRUE moves its value into the parent.
Exercises
Try each question before opening the hints. Every answer about program output was checked by compiling and running the program with GnuCOBOL 3.2.
1. Data, levels and pictures
Warm-upHumanHow many bytes does this record take with the default USAGE DISPLAY? (GnuCOBOL's FUNCTION LENGTH(rec) prints the answer.)
01 rec.
05 a PIC X(3).
05 b PIC 9(4)V99.
05 c PIC S9(3).
2. Data, levels and pictures
Warm-upComputationalWhat does this fragment print?
01 city PIC X(8).
...
MOVE "Johannesburg" TO city
DISPLAY "[" city "]"
3. Data, levels and pictures
CoreComputationalWith GnuCOBOL, what does this fragment print?
01 small-amt PIC 9(3)V99.
...
MOVE 98765.4321 TO small-amt
DISPLAY "[" small-amt "]"
4. Data, levels and pictures
CoreComputationalWhat does this fragment print? Type the brackets and spaces exactly.
01 signed-out PIC ---9.99.
...
MOVE -3.5 TO signed-out
DISPLAY "[" signed-out "]"
5. Data, levels and pictures
CoreHumanAn account balance can be anything from −9,999,999.99 to 9,999,999.99. Which picture should hold it for arithmetic?
6. Data, levels and pictures
CoreComputationalA statement printer moves a refund of −250.00 into PIC ZZ,ZZ9.99 and prints it. What appears?
7. Data, levels and pictures
StretchHumanA record has 05 qty PIC 9(3). and 05 name PIC X(10). A colleague clears it with MOVE SPACES TO the-record and later runs ADD 1 TO qty. What is the best explanation of the risk?
Further reading and resources
- GnuCOBOL guides and documentationThe Programmer's Guide has a full table of picture symbols and the MOVE rules.
- IBM Enterprise COBOL for z/OS documentationSee the language reference's chapters on the data division, the PICTURE clause and MOVE.