Skip to content
LumenaryAcademy
Foundations 55 min

Data, levels and pictures

Describing every byte in advance, the rules of MOVE, and edited pictures that format numbers for people.

Code tested · 4AI-draftedAwaiting review by a computer scientist
MotivationH

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.

DefinitionsH

Levels, pictures and usage

Level numbers

Each data description entry starts with a level number that says where the item sits in a hierarchy:

LevelMeaning
01A record or a top-level item. Every hierarchy starts here.
02 to 49A subordinate item inside the 01 above it. Higher numbers nest deeper.
77An independent item that is never part of a record (an older style; 01 does the same job)
88A condition name: a named test on the value of the item above it
66RENAMES, 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

SymbolMeaningTakes a position?
9A decimal digitYes
XAny characterYes
AA letter or spaceYes
VWhere the implied decimal point sitsNo: the point is not stored
SThe number has a signNo with the default usage: the sign shares a byte with a digit
PA 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.

Worked examplesH

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:

cobol
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.
text
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:

cobol
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.
text
[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:

SymbolEffect
ZA 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, DBAccountants' 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:

cobol
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.
text
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:

  • Z alone drops the sign. The first line shows −1234.50 as a positive-looking 1,234.50. If a value can be negative, its edited picture must have a sign symbol or CR/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.99 leaves a gap between the minus and the digits; ---,--9.99 puts 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. B and / 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.

cobol
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.
text
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.

ExplanationH

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 as cust- or pay- 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)V99 is a common choice for money.
  • Test incoming numeric fields. Data from files and screens can be wrong. The class test IF pay-amount IS NUMERIC checks that a DISPLAY field 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". beats IF acct-status = "C" scattered through the code.
Common misconceptionsH

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

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-upHuman

How 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-upComputational

What does this fragment print?

01 city PIC X(8).
...
    MOVE "Johannesburg" TO city
    DISPLAY "[" city "]"

3. Data, levels and pictures

CoreComputational

With 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

CoreComputational

What 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

CoreHuman

An account balance can be anything from −9,999,999.99 to 9,999,999.99. Which picture should hold it for arithmetic?

Choose one

6. Data, levels and pictures

CoreComputational

A statement printer moves a refund of −250.00 into PIC ZZ,ZZ9.99 and prints it. What appears?

Choose one

7. Data, levels and pictures

StretchHuman

A 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?

Choose one

Further reading and resources