USAGE DISPLAY and zoned decimals

A field has a picture, and it also has a usage: the word that says how the bytes of that picture are laid out. The usage this course has used so far without naming it is DISPLAY, and it is the default for every field, so the clause is almost never written. What it does is worth one lesson, because the other three usages are read from what it does not do.

USAGE DISPLAY is the default

In USAGE DISPLAY the field is a string of characters: one byte per position of the picture, and the byte is the character you would print. Two fields with the same picture and one of them carrying the clause are the same bytes:

IDENTIFICATION DIVISION. PROGRAM-ID. DISP. DATA DIVISION. WORKING-STORAGE SECTION. 01 A-CODE PIC 9(3) VALUE 123. 01 B-CODE PIC 9(3) USAGE DISPLAY VALUE 123. 01 C-NAME PIC X(4) VALUE "ANNA". 01 D-RATE PIC 9(3)V99 VALUE 12.34. 01 E-AMT PIC 9(3).99 VALUE 12.34. PROCEDURE DIVISION. DISPLAY "A=" A-CODE " B=" B-CODE " C=" C-NAME. DISPLAY "D=[" D-RATE "] E=[" E-AMT "]". DISPLAY "A " LENGTH OF A-CODE. DISPLAY "B " LENGTH OF B-CODE. DISPLAY "C " LENGTH OF C-NAME. DISPLAY "D " LENGTH OF D-RATE. DISPLAY "E " LENGTH OF E-AMT. STOP RUN.

cobc -x -free -Wall -o disp disp.cob
./disp

A=123 B=123 C=ANNA
D=[012.34] E=[012.34]
A 3
B 3
C 4
D 5
E 6

A and B print the same and are three bytes each, so the explicit clause adds nothing but a reminder. The name is four bytes, one per letter, and the rate is five: three digits, two digits and no byte for the V.

The point that costs a byte

E is the same number as D and one byte longer, because PIC 9(3).99 is an edited field: the . is a character to be stored and printed, so it takes a byte of its own, while the V of 9(3)V99 is a note to the compiler and takes nothing. Both print 012.34, and only the length tells them apart.

That byte is the reason a working field is written with V and a printed field with .. Numbers are added and compared in the first kind, and the point is put in at the end, once, on the way to a report. The lesson on edited numeric output shows what a picture with Z and commas does when the number grows.

The zone of the last digit

The digits are not stored as a number. Each one is a character, and a character byte has two halves: the low half holds the digit, and the high half, the zone, says what kind of character it is. For a plain digit the zone makes it the printed digit. A signed field borrows the zone of the last digit to carry the sign, which is why a PIC S9(3) is three bytes and not four.

IDENTIFICATION DIVISION. PROGRAM-ID. ZONED. DATA DIVISION. WORKING-STORAGE SECTION. 01 NEGATIVE-F PIC S9(3) VALUE -42. 01 NEG-BYTES REDEFINES NEGATIVE-F PIC X(3). 01 POSITIVE-F PIC S9(3) VALUE 42. 01 POS-BYTES REDEFINES POSITIVE-F PIC X(3). 01 PLAIN-F PIC 9(3) VALUE 42. 01 PLAIN-BYTES REDEFINES PLAIN-F PIC X(3). PROCEDURE DIVISION. DISPLAY "[" NEGATIVE-F "] bytes [" NEG-BYTES "]". DISPLAY "[" POSITIVE-F "] bytes [" POS-BYTES "]". DISPLAY "[" PLAIN-F "] bytes [" PLAIN-BYTES "]". STOP RUN.

cobc -x -free -Wall -o zoned zoned.cob
./zoned

[-042] bytes [04r]
[+042] bytes [042]
[042] bytes [042]

The REDEFINES puts a PIC X(3) over the same three bytes, so the second bracket is the field as it really is: 0, 4 and a last character that is not a digit. For -42 that character is r, the ASCII letter whose low half is 2 and whose high half marks a negative; for +42 it is the plain digit 2. A zoned decimal is a string that happens to hold a sign in its last character.

This is the layout IBM mainframes have used since the 1960s and the reason a COBOL file can be read by a program that knows nothing about COBOL. The lesson on SIGN LEADING, TRAILING and SEPARATE moves the sign to the front and to a byte of its own, and the lesson on ASCII, EBCDIC and UTF-8 explains what changes when the characters are not ASCII.

MOVE into a DISPLAY field

A MOVE into a DISPLAY field obeys the receiving picture, and the receiving picture decides which end gives way:

IDENTIFICATION DIVISION. PROGRAM-ID. MOVES. DATA DIVISION. WORKING-STORAGE SECTION. 01 SMALL-F PIC 9(3). 01 WIDE-F PIC 9(5). 01 TEXT-F PIC X(3) VALUE "123". 01 FROM-TEXT PIC 9(3). PROCEDURE DIVISION. MOVE 12345 TO SMALL-F. DISPLAY "12345 into 9(3): [" SMALL-F "]". MOVE 5 TO WIDE-F. DISPLAY "5 into 9(5): [" WIDE-F "]". MOVE TEXT-F TO FROM-TEXT. DISPLAY "text into 9(3): [" FROM-TEXT "]". MOVE -7 TO SMALL-F. DISPLAY "-7 into 9(3): [" SMALL-F "]". STOP RUN.

cobc -x -free -Wall -o moves moves.cob
./moves

moves.cob:12: warning: value size exceeds data size [-Wtruncate]
10 |
11 | PROCEDURE DIVISION.
12 > MOVE 12345 TO SMALL-F.
13 | DISPLAY "12345 into 9(3): [" SMALL-F "]".
14 | MOVE 5 TO WIDE-F.
moves.cob:12: note: value is 12345 [-Wtruncate]
moves.cob:6: note: 'SMALL-F' defined here as PIC 9(3) [-Wtruncate]
4 | DATA DIVISION.
5 | WORKING-STORAGE SECTION.
6 > 01 SMALL-F PIC 9(3).
7 | 01 WIDE-F PIC 9(5).
8 | 01 TEXT-F PIC X(3) VALUE "123".
moves.cob:18: warning: ignoring sign [-Wtruncate]
16 | MOVE TEXT-F TO FROM-TEXT.
17 | DISPLAY "text into 9(3): [" FROM-TEXT "]".
18 > MOVE -7 TO SMALL-F.
19 | DISPLAY "-7 into 9(3): [" SMALL-F "]".
20 | STOP RUN.
12345 into 9(3): [345]
5 into 9(5): [00005]
text into 9(3): [123]
-7 into 9(3): [007]

The four rules are visible in the output. A long number keeps its right end, because the right end is the units: 12345 becomes 345. A short number is filled on the left: 5 becomes 00005, which is the same number. A field of digits is accepted as a number when the characters are digits. And a negative number in an unsigned picture loses its sign, -7 becoming 007, with a warning from -Wtruncate that only -Wall turns on.

The last one is the dangerous rule, because a report that adds 007 where -7 was meant is wrong by fourteen and looks right. A field that can hold a negative number has to have a S in its picture. The lesson on MOVE takes the whole set of rules, group moves included.

Arithmetic in the field

Arithmetic on a DISPLAY field is decimal arithmetic, and the point is where the picture says it is, whether or not the field stores it:

IDENTIFICATION DIVISION. PROGRAM-ID. PAY. DATA DIVISION. WORKING-STORAGE SECTION. 01 PRICE PIC 9(3)V99 VALUE 12.34. 01 TAX PIC 9(1)V99 VALUE 0.66. 01 TOTAL-F PIC 9(4)V99. PROCEDURE DIVISION. COMPUTE TOTAL-F = PRICE + TAX. DISPLAY "price [" PRICE "]". DISPLAY "tax [" TAX "]". DISPLAY "total [" TOTAL-F "]". MOVE 5.5 TO PRICE. DISPLAY "price after MOVE 5.5 [" PRICE "]". STOP RUN.

cobc -x -free -Wall -o pay pay.cob
./pay

price [012.34]
tax [0.66]
total [0013.00]
price after MOVE 5.5 [005.50]

Twelve and thirty-four hundredths plus sixty-six hundredths is thirteen exactly, and the total keeps two decimal places because its picture has two. Nothing here is a binary fraction, so the sum cannot be a cent off: the digits are the digits. That property is the subject of why money is decimal, and the truncation a division introduces comes back in ROUNDED and truncation.

Text into a numeric field

A DISPLAY numeric field is a string of digit characters, and the compiler cannot stop a program from putting other characters there. A MOVE of a literal into it is checked, and the check is a warning, not a stop:

IDENTIFICATION DIVISION. PROGRAM-ID. BADMOVE. DATA DIVISION. WORKING-STORAGE SECTION. 01 SMALL-F PIC 9(3) VALUE 7. PROCEDURE DIVISION. MOVE "AB" TO SMALL-F. DISPLAY "[" SMALL-F "]". STOP RUN.

cobc -x -free -Wall -o badmove badmove.cob
./badmove

badmove.cob:9: warning: numeric value is expected [-Wtyping]
7 |
8 | PROCEDURE DIVISION.
9 > MOVE "AB" TO SMALL-F.
10 | DISPLAY "[" SMALL-F "]".
11 | STOP RUN.
badmove.cob:6: note: 'SMALL-F' defined here as PIC 9(3) [-Wtyping]
4 | DATA DIVISION.
5 | WORKING-STORAGE SECTION.
6 > 01 SMALL-F PIC 9(3) VALUE 7.
7 |
8 | PROCEDURE DIVISION.
[0AB]

The build warns and the run prints 0AB: the literal was placed at the right end of the field and the free position on its left was filled with a zero, because the receiving picture is numeric. The field now holds something no arithmetic can use, and the next ADD on it is a data error that shows up far from the MOVE.

The habit that prevents this is to move between fields of the same category: text through PIC X, numbers through PIC 9, and a conversion in between that checks the text first, as FUNCTION NUMVAL does.

Exercises

  1. Add 01 F-AMT PIC 9(3)V99 USAGE DISPLAY VALUE 12.34. to the first program and print its length. Why is it the same as D and not as E?
  2. Print the bytes of PIC S9(3) VALUE -100 with a REDEFINES. Which byte carries the sign, and what does it look like when the last digit is a zero?
  3. Move -7 into a PIC S9(3) and print it. Then build the same MOVE into a PIC 9(3) and read the warning again.
  4. Change TOTAL-F to PIC 9(3)V99 in the arithmetic program and explain the total it prints.

Questions

A new set of questions in a new order every time. Choose one answer for each, then check.

  1. What is USAGE DISPLAY?

    Answer

    One byte per picture position, holding the character to print

    DISPLAY is the character form of the field: the digit or letter itself sits in the byte, which is why a five-digit picture is five bytes.

  2. How many bytes does PIC 9(3).99 take, and how many does PIC 9(3)V99 take?

    Answer

    6 and 5: the point of the edited field is stored

    A . in a picture is a character position of its own; a V is a note to the compiler and takes no byte, so the working field is one byte shorter.

  3. Where does the sign of a PIC S9(3) field live?

    Answer

    In the zone of the last digit, so the field stays three bytes

    The overpunched last byte carries both the last digit and the sign; -42 shows as 04r, with r marking the minus.

  4. What does MOVE 12345 TO a PIC 9(3) field leave in it?

    Answer

    345: the right end of the number is kept

    A numeric move keeps the units, so the low-order digits survive and the build warns about the truncation under -Wall.

  5. What does this program print? IDENTIFICATION DIVISION. PROGRAM-ID. Q1. DATA DIVISION. WORKING-STORAGE SECTION. 01 E-AMT PIC 9(3).99 VALUE 12.34. PROCEDURE DIVISION. DISPLAY LENGTH OF E-AMT. STOP RUN.

    Answer

    6

    Three digits, the stored point and two digits: the edited picture spends a byte on the point.

  6. What does this program print? IDENTIFICATION DIVISION. PROGRAM-ID. Q2. DATA DIVISION. WORKING-STORAGE SECTION. 01 NEG-F PIC S9(3) VALUE -42. 01 NEG-B REDEFINES NEG-F PIC X(3). PROCEDURE DIVISION. DISPLAY "[" NEG-B "]". STOP RUN.

    Answer

    [04r]

    The three bytes are the two leading digits and an overpunched last byte, so the minus is inside r and not in front of the field.

  7. What does this program print? IDENTIFICATION DIVISION. PROGRAM-ID. Q3. DATA DIVISION. WORKING-STORAGE SECTION. 01 SMALL-F PIC 9(3). PROCEDURE DIVISION. MOVE -7 TO SMALL-F. DISPLAY "[" SMALL-F "]". STOP RUN.

    Answer

    [007]

    The picture has no S, so the sign cannot be kept: the magnitude goes in with leading zeros and the build warns that the sign was ignored.

  8. What does this program print? IDENTIFICATION DIVISION. PROGRAM-ID. Q4. DATA DIVISION. WORKING-STORAGE SECTION. 01 SMALL-F PIC 9(3) VALUE 7. PROCEDURE DIVISION. MOVE "AB" TO SMALL-F. DISPLAY "[" SMALL-F "]". STOP RUN.

    Answer

    [0AB]

    The text is right-aligned in the numeric field and the free position on the left gets a zero; the build warns with numeric value is expected.

  9. What does this program print? IDENTIFICATION DIVISION. PROGRAM-ID. Q5. DATA DIVISION. WORKING-STORAGE SECTION. 01 PRICE PIC 9(3)V99 VALUE 12.34. 01 TAX PIC 9(1)V99 VALUE 0.25. 01 TOTAL-F PIC 9(4)V99. PROCEDURE DIVISION. COMPUTE TOTAL-F = PRICE + TAX. DISPLAY "[" TOTAL-F "]". STOP RUN.

    Answer

    [0012.59]

    The total picture has four integer digits and two decimals, so the sum prints with a leading zero pair and the implied point in place.

  10. A field is PIC 9(5) and a program moves 5 into it. What does DISPLAY print?

    Answer

    00005

    A numeric MOVE fills the free positions on the left with zeros, so the value keeps its meaning and the width of its picture.

The code on this page was built with cobc (GnuCOBOL) 3.2.0 and run on Alpine Linux 3.24.3 (x86_64) in a Docker container.

Article author: Arthur Isaev