PICTURE strings, literals and figurative constants

PIC S9(7)V99 holds a balance as large as 9,999,999.99, yet it takes 9 bytes, not 11: the sign and the decimal point get no byte of their own. Every COBOL data item is a fixed number of bytes set by its PICTURE string, and a record layout is right only when each field is counted the way the compiler counts it.

Below you will count the bytes of items built from 9, X, A, S, V and P and read each byte the compiler stores, write numeric, alphanumeric and hexadecimal literals and catch a VALUE that does not fit, fill items with figurative constants, and keep data names clear of the words a compiler reserves.

A PICTURE string sets the bytes of an item

A PICTURE clausePICTURE clause: The clause, PIC for short, that describes an elementary item with symbols such as 9, X, A, S and V. In USAGE DISPLAY each 9, X or A is one byte, so PIC X(8) is 8 bytes., PIC for short, describes an item with symbols. 9 is a digit, X is any character and A is a letter or a space, and a number in brackets repeats the symbol before it, so 9(4) means 9999. In USAGE DISPLAY, the usage an item has when it names no other, each of those symbols is one byte, so the PICTURE string is the size of the item. For four items, this program prints the size from the BYTE-LENGTH function and the bytes from HEX-OF, which writes every byte as two hexadecimal digits:

       IDENTIFICATION DIVISION.
       PROGRAM-ID. PICTURES.
      * Four items of the three basic kinds, each with its size in
      * bytes and its bytes in hexadecimal.
       DATA DIVISION.
       WORKING-STORAGE SECTION.
       01  ACCT-NO      PIC X(8)   VALUE "AC000417".
       01  BRANCH       PIC 9(4)   VALUE 42.
       01  INITIALS     PIC A(3)   VALUE "RKS".
       01  CITY         PIC X(12)  VALUE "NAGPUR".
       01  CODE-IN      PIC X(3)   VALUE "R2D".
       PROCEDURE DIVISION.
           DISPLAY "ACCT-NO   " FUNCTION BYTE-LENGTH(ACCT-NO)
                   " bytes  " FUNCTION HEX-OF(ACCT-NO)
           DISPLAY "BRANCH    " FUNCTION BYTE-LENGTH(BRANCH)
                   " bytes  " FUNCTION HEX-OF(BRANCH)
           DISPLAY "INITIALS  " FUNCTION BYTE-LENGTH(INITIALS)
                   " bytes  " FUNCTION HEX-OF(INITIALS)
           DISPLAY "CITY      " FUNCTION BYTE-LENGTH(CITY)
                   " bytes " FUNCTION HEX-OF(CITY)
           MOVE CODE-IN TO INITIALS
           DISPLAY "INITIALS now holds [" INITIALS "]"
           IF INITIALS IS ALPHABETIC
               DISPLAY "  and it is alphabetic"
           ELSE
               DISPLAY "  and it is not alphabetic"
           END-IF
           STOP RUN.

from session import files, run

# Four items of the three basic kinds: their sizes in bytes, their bytes in hexadecimal, and what the PICTURE of an
# alphabetic item does and does not check.
files("pictures.cob")
run("""
cobc -x pictures.cob && ./pictures
""")

$ cobc -x pictures.cob && ./pictures
ACCT-NO   8 bytes  4143303030343137
BRANCH    4 bytes  30303432
INITIALS  3 bytes  524B53
CITY      12 bytes 4E4147505552202020202020
INITIALS now holds [R2D]
  and it is not alphabetic

Each size is the count of symbols: X(8) gave 8 bytes, 9(4) gave 4 and A(3) gave 3. The bytes show how DISPLAY data is kept, as characters. BRANCH holds the number 42 as the four characters 0042, X’30303432’, and CITY holds NAGPUR followed by six spaces, each X’20’, because a value shorter than its item is padded on the right. The table sums up the three symbols:

The last two lines of the run show what a PICTURE does not do. MOVE CODE-IN TO INITIALS put R2D into an item whose PICTURE promises letters, and nothing objected: the PICTURE describes what the item should hold and checks nothing at run time. Only the class test IS ALPHABETIC noticed the digit.

S, V and P add no bytes, unless the sign is separate

The amount 42.50 can be described in several ways, and only a separate sign costs an extra byte. V is the implied decimal pointimplied decimal point: The V of a PICTURE string. It tells the compiler where the decimal point falls for arithmetic and MOVE, but takes no byte, so PIC 9(3)V99 is 5 bytes.: it tells the compiler where the point falls, for arithmetic and for MOVE, and IBM’s reference says it is “not counted in the size of the elementary item”. S says the item has a sign and is not counted either, unless a SIGN clause makes the sign SEPARATE, which gives it a byte of its own. P is a scaling positionscaling position: A P of a PICTURE string: a digit position that is never stored. PIC 9(3)PPP stores three digits and stands for a multiple of 1,000, so 123456 is held as 123000., a digit that is never stored. The program prints the size, the bytes and the displayed value of each form:

       IDENTIFICATION DIVISION.
       PROGRAM-ID. SIGNS.
      * The same amount with and without a sign, the sign kept in a
      * byte of its own, and P scaling. V and S take no byte here.
       DATA DIVISION.
       WORKING-STORAGE SECTION.
       01  AMT-PLAIN    PIC 9(3)V99  VALUE 42.50.
       01  AMT-SIGNED   PIC S9(3)V99 VALUE -42.50.
       01  AMT-LEAD     PIC S9(3)V99 SIGN LEADING SEPARATE
                        VALUE -42.50.
       01  AMT-TRAIL    PIC S9(3)V99 SIGN TRAILING SEPARATE
                        VALUE -42.50.
       01  BALANCE      PIC S9(7)V99 VALUE -1234.50.
       01  THOUSANDS    PIC 9(3)PPP.
       PROCEDURE DIVISION.
           DISPLAY "AMT-PLAIN   " FUNCTION BYTE-LENGTH(AMT-PLAIN)
                   "  " FUNCTION HEX-OF(AMT-PLAIN) "    " AMT-PLAIN
           DISPLAY "AMT-SIGNED  " FUNCTION BYTE-LENGTH(AMT-SIGNED)
                   "  " FUNCTION HEX-OF(AMT-SIGNED) "    " AMT-SIGNED
           DISPLAY "AMT-LEAD    " FUNCTION BYTE-LENGTH(AMT-LEAD)
                   "  " FUNCTION HEX-OF(AMT-LEAD) "  " AMT-LEAD
           DISPLAY "AMT-TRAIL   " FUNCTION BYTE-LENGTH(AMT-TRAIL)
                   "  " FUNCTION HEX-OF(AMT-TRAIL) "  " AMT-TRAIL
           DISPLAY "BALANCE     " FUNCTION BYTE-LENGTH(BALANCE)
                   "  " FUNCTION HEX-OF(BALANCE) " " BALANCE
           MOVE 123456 TO THOUSANDS
           DISPLAY "THOUSANDS   " FUNCTION BYTE-LENGTH(THOUSANDS)
                   "  " FUNCTION HEX-OF(THOUSANDS) "        " THOUSANDS
           STOP RUN.

from session import files, run

# The bytes of one amount with and without a sign, with the sign in a byte of its own, and an item scaled with P.
files("signs.cob")
run("""
cobc -x signs.cob && ./signs
""")

$ cobc -x signs.cob && ./signs
AMT-PLAIN   5  3034323530    042.50
AMT-SIGNED  5  3034323570    -042.50
AMT-LEAD    6  2D3034323530  -042.50
AMT-TRAIL   6  30343235302D  042.50-
BALANCE     9  303030313233343570 -0001234.50
THOUSANDS   3  313233        123000

AMT-PLAIN, PIC 9(3)V99, is five bytes, the digits 04250 with no point among them. AMT-SIGNED has the same five bytes except the last: GnuCOBOL keeps the sign of a signed DISPLAY item in its last byte, so X’30’, the character 0, became X’70’.

SIGN LEADING SEPARATE and SIGN TRAILING SEPARATE add a sixth byte, a minus sign, X’2D’, in front of the digits or after them. Step through the bytes of AMT-LEAD:

BALANCE is the field of the opening: nine digits, 9 bytes, 303030313233343570. THOUSANDS, PIC 9(3)PPP, is 3 bytes that hold 123 and stand for 123000. The three Ps are the units, tens and hundreds it never stores, so MOVE 123456 TO THOUSANDS kept the thousands and dropped 456 without a word.

Literals are bytes, and a VALUE must fit them

A literal is a value written into the program. A numeric literal is digits with at most one sign, at the left, and at most one decimal point, as in -2500.75. An alphanumeric literal stands between quotation marks or apostrophes, and the delimiter itself is written twice inside it, as in ‘Payee’‘s copy’. A hexadecimal literalhexadecimal literal: A literal written X'…' with two hexadecimal digits for each byte, such as X'414243' for ABC or X'09' for a tab. It gives exact bytes, printable or not., X’…‘, gives the bytes themselves, two hexadecimal digits for each, and IBM allows one anywhere an alphanumeric literal may stand: X’414243’ is ABC, and X’09’ is a tab, which no keyboard puts between quotes. A VALUE clause gives an item its starting value from a literal. Here are four literals that fit their items and three that do not:

       IDENTIFICATION DIVISION.
       PROGRAM-ID. LITERALS.
      * Literals in VALUE clauses: four that fit, three that do not.
       DATA DIVISION.
       WORKING-STORAGE SECTION.
       01  NOTE-TEXT    PIC X(12)    VALUE 'Payee''s copy'.
       01  LETTERS      PIC X(3)     VALUE X'414243'.
       01  TAB-CHAR     PIC X        VALUE X'09'.
       01  OVERDRAFT    PIC S9(5)V99 VALUE -2500.75.
       01  STATION      PIC X(10)    VALUE "CHENNAI CENTRAL".
       01  LIMIT-AMT    PIC 9(3)     VALUE 12345.
       01  PAYEE        PIC X(20)
                        VALUE "नमिता पाल".
       PROCEDURE DIVISION.
           DISPLAY "NOTE-TEXT [" NOTE-TEXT "]"
           DISPLAY "LETTERS   [" LETTERS "]"
           DISPLAY "TAB-CHAR  [" FUNCTION HEX-OF(TAB-CHAR) "]"
           DISPLAY "OVERDRAFT [" OVERDRAFT "]"
           DISPLAY "STATION   [" STATION "]"
           DISPLAY "LIMIT-AMT [" LIMIT-AMT "]"
           DISPLAY "PAYEE     [" PAYEE "]"
           STOP RUN.

The session keeps only cobc’s own messages, the lines that start with the file name, then runs the program and builds it once more with the warning turned into an error:

from session import files, run

# Literals in VALUE clauses: what cobc says about three that do not fit (only its own messages, the lines that start
# with the file name), what the program then holds, and the same build with that warning made an error.
files("literals.cob")
run("""
cobc -x literals.cob 2>&1 | grep '^literals.cob'
./literals
!cobc -x -Werror=others -o literals-strict literals.cob
""")

$ cobc -x literals.cob 2>&1 | grep '^literals.cob'
literals.cob:10: warning: value size exceeds data size [-Wothers]
literals.cob:10: note: value size is 15 [-Wothers]
literals.cob:11: warning: value size exceeds data size [-Wothers]
literals.cob:13: warning: value size exceeds data size [-Wothers]
literals.cob:13: note: value size is 25 [-Wothers]
$ ./literals
NOTE-TEXT [Payee's copy]
LETTERS   [ABC]
TAB-CHAR  [09]
OVERDRAFT [-02500.75]
STATION   [CHENNAI CE]
LIMIT-AMT [345]
PAYEE     [नमिता प�]
$ cobc -x -Werror=others -o literals-strict literals.cob
literals.cob:10: error: value size exceeds data size [-Werror=others]
    8 |        01  TAB-CHAR     PIC X        VALUE X'09'.
    9 |        01  OVERDRAFT    PIC S9(5)V99 VALUE -2500.75.
   10 >        01  STATION      PIC X(10)    VALUE "CHENNAI CENTRAL".
   11 |        01  LIMIT-AMT    PIC 9(3)     VALUE 12345.
   12 |        01  PAYEE        PIC X(20)
literals.cob:10: note: value size is 15 [-Werror=others]
literals.cob:11: error: value size exceeds data size [-Werror=others]
    9 |        01  OVERDRAFT    PIC S9(5)V99 VALUE -2500.75.
   10 |        01  STATION      PIC X(10)    VALUE "CHENNAI CENTRAL".
   11 >        01  LIMIT-AMT    PIC 9(3)     VALUE 12345.
   12 |        01  PAYEE        PIC X(20)
   13 |                         VALUE "नमिता पाल".
literals.cob:13: error: value size exceeds data size [-Werror=others]
   11 |        01  LIMIT-AMT    PIC 9(3)     VALUE 12345.
   12 |        01  PAYEE        PIC X(20)
   13 >                         VALUE "नमिता पाल".
   14 |        PROCEDURE DIVISION.
   15 |            DISPLAY "NOTE-TEXT [" NOTE-TEXT "]"
literals.cob:13: note: value size is 25 [-Werror=others]
[exit status 1]

The four that fit hold what was written: Payee’s copy with one apostrophe, ABC, the tab byte 09, and -2500.75, which DISPLAY showed as -02500.75. For the other three, GnuCOBOL warned three times, value size exceeds data size, and built the program anyway. The alphanumeric STATION kept its first 10 bytes, CHENNAI CE, and the numeric LIMIT-AMT kept its last three digits, 345 of 12345: the rules of MOVE, which the next lesson takes apart. PAYEE shows that sizes are counted in bytes, not letters. The name नमिता पाल is 9 Unicode characters, a space and eight Devanagari ones, and in UTF-8 each Devanagari character takes 3 bytes, so the literal is 25 bytes. cobc reported value size is 25 and kept 20 bytes, which end one byte into the vowel sign after प: the terminal shows that broken character as �, and ल is lost.

Figurative constants fill every byte

A figurative constantfigurative constant: A reserved word that stands for a value, such as SPACES, ZEROS, HIGH-VALUES, LOW-VALUES, QUOTES or ALL with a literal. It takes the length of the item it fills. is a reserved word that stands for a value. The ones this lesson uses are SPACE or SPACES, ZERO, ZEROS or ZEROES, HIGH-VALUE or HIGH-VALUES, LOW-VALUE or LOW-VALUES, QUOTE or QUOTES, and ALL followed by a literal. It has no length of its own. IBM’s reference gives it the length of the item it is moved to, so it repeats until every byte is filled. This program moves each one into an item and prints the bytes, then tries to clear a number with SPACES:

       IDENTIFICATION DIVISION.
       PROGRAM-ID. FIGURATIVE.
      * What each figurative constant puts into an item: every byte
      * of the item is filled.
       DATA DIVISION.
       WORKING-STORAGE SECTION.
       01  FOUR         PIC X(4).
       01  QTY-4        PIC 9(4).
       01  RULE-LINE    PIC X(10).
       01  CODE-5       PIC X(5).
       PROCEDURE DIVISION.
           MOVE SPACES TO FOUR
           DISPLAY "SPACES          " FUNCTION HEX-OF(FOUR)
           MOVE ZEROS TO FOUR
           DISPLAY "ZEROS           " FUNCTION HEX-OF(FOUR)
           MOVE ZEROS TO QTY-4
           DISPLAY "ZEROS into 9(4) " FUNCTION HEX-OF(QTY-4)
           MOVE HIGH-VALUES TO FOUR
           DISPLAY "HIGH-VALUES     " FUNCTION HEX-OF(FOUR)
           MOVE LOW-VALUES TO FOUR
           DISPLAY "LOW-VALUES      " FUNCTION HEX-OF(FOUR)
           MOVE QUOTES TO FOUR
           DISPLAY "QUOTES          " FUNCTION HEX-OF(FOUR)
                   "  " FOUR
           MOVE ALL "*-" TO RULE-LINE
           DISPLAY "ALL '*-'        " RULE-LINE
           MOVE ALL "AB" TO CODE-5
           DISPLAY "ALL 'AB'        " CODE-5
           STOP RUN.

from session import files, run

# The bytes each figurative constant puts into an item, and SPACES moved to a numeric item.
files("figurative.cob", "spaces-num.cob")
run("""
cobc -x figurative.cob && ./figurative
!cobc -x spaces-num.cob
""")

$ cobc -x figurative.cob && ./figurative
SPACES          20202020
ZEROS           30303030
ZEROS into 9(4) 30303030
HIGH-VALUES     FFFFFFFF
LOW-VALUES      00000000
QUOTES          22222222  """"
ALL '*-'        *-*-*-*-*-
ALL 'AB'        ABABA
$ cobc -x spaces-num.cob
spaces-num.cob:8: error: MOVE of figurative constant SPACE to numeric item used
    6 |        01  QTY-4        PIC 9(4).
    7 |        PROCEDURE DIVISION.
    8 >            MOVE SPACES TO QTY-4
    9 |            DISPLAY QTY-4
   10 |            STOP RUN.
[exit status 1]

HIGH-VALUES and LOW-VALUES are bytes no keyboard types. IBM’s reference defines them by the collating sequencecollating sequence: The order in which a program or a sort ranks characters when it compares them. ASCII puts digits before letters and EBCDIC puts letters before digits; COLLATING SEQUENCE names the one a SORT or MERGE uses. More in “SORT and MERGE: input and output procedures”: the character with the highest or the lowest position in it, X’FF’ and X’00’ in EBCDIC, and the same bytes in GnuCOBOL’s native order here. Because no real key can be higher, programs move HIGH-VALUES into a key to mean “no more records”, a pattern the lessons on batch files build on. ALL “AB” in five bytes gave ABABA: the pattern repeats and stops where the item ends, half-way through it.

The last command shows a constant that is refused. MOVE SPACES TO QTY-4 failed to compile, MOVE of figurative constant SPACE to numeric item used, because spaces are not digits. ZEROS is the constant that clears a number, and it stores the same bytes in a numeric item as in an alphanumeric one.

A data name must not be a reserved word

The words of the language itself, such as MOVE, COUNT or STATUS, are reserved wordsreserved word: A word the COBOL language itself uses, such as COUNT or STATUS, which cannot name a data item or a paragraph. cobc --list-reserved lists the reserved words of GnuCOBOL. More in “Install GnuCOBOL, compile with cobc and run programs”, and no data item may be named with one. The trouble is that each compiler, and each dialect of a compiler, has its own list. This loan program names its monthly instalment EMI:

       IDENTIFICATION DIVISION.
       PROGRAM-ID. LOAN.
      * A loan program that names its monthly instalment EMI.
       DATA DIVISION.
       WORKING-STORAGE SECTION.
       01  EMI          PIC 9(6)V99 VALUE 8678.23.
       01  TENURE       PIC 9(3)    VALUE 240.
       PROCEDURE DIVISION.
           DISPLAY "Instalment " EMI " for " TENURE " months"
           STOP RUN.

from session import files, run

# A data name that is a reserved word, the reserved-word lists of two dialects, and the fix: a prefix on every name.
files("loan.cob", "loan-fixed.cob")
run("""
!cobc -x loan.cob
cobc --list-reserved | grep -E '^(BYTES|CD|EMI|ESI) '
cobc -std=cobol2014 --list-reserved | grep -E '^(BYTES|CD|EMI|ESI) ' || echo "none of the four"
cobc -x loan-fixed.cob && ./loan-fixed
""")

$ cobc -x loan.cob
loan.cob:6: error: syntax error, unexpected EMI
    4 |        DATA DIVISION.
    5 |        WORKING-STORAGE SECTION.
    6 >        01  EMI          PIC 9(6)V99 VALUE 8678.23.
    7 |        01  TENURE       PIC 9(3)    VALUE 240.
    8 |        PROCEDURE DIVISION.
loan.cob:9: error: syntax error, unexpected EMI
    7 |        01  TENURE       PIC 9(3)    VALUE 240.
    8 |        PROCEDURE DIVISION.
    9 >            DISPLAY "Instalment " EMI " for " TENURE " months"
   10 |            STOP RUN.
   11 | <EOF>
[exit status 1]
$ cobc --list-reserved | grep -E '^(BYTES|CD|EMI|ESI) '
BYTES                           No
CD                              Yes
EMI                             Yes
ESI                             Yes
$ cobc -std=cobol2014 --list-reserved | grep -E '^(BYTES|CD|EMI|ESI) ' || echo "none of the four"
none of the four
$ cobc -x loan-fixed.cob && ./loan-fixed
Instalment 008678.23 for 240 months

cobc stopped with syntax error, unexpected EMI, a message that never says the word is reserved. The list explains it: in GnuCOBOL’s default dialect EMI, CD and ESI are reserved words, and BYTES is reserved but not supported. Under -std=cobol2014 none of the four is reserved, and that does not make EMI safe. IBM’s table for Enterprise COBOL marks EMI, CD and ESI as words of the 1985 standard that it reserves without implementing, and naming an item with one of them gives a severe message; BYTES is not in IBM’s table at all. A name can build under one dialect and fail under another. Whether each word is reserved:

The fix is a habit rather than a list: give every data name a prefix, such as LN- for the items of a loan or WS- for working storage. No reserved word starts with one, so loan-fixed.cob, with LN-EMI and LN-TENURE, built and printed its instalment. GnuCOBOL’s -fnot-reserved=EMI would also take the word off the list, but only for GnuCOBOL: the same source would still fail on z/OS.

Practise: count the bytes, read the constants

Count the bytes and read the constants until the sizes come without counting on your fingers. The questions start with the idea you know least, and a wrong choice says which byte it miscounted:

Interview questions

Warm-up (fresher to 2–5 years): how many bytes does PIC S9(5)V99 take in USAGE DISPLAY, and why?

Seven. In USAGE DISPLAY each 9 is one byte, a digit kept as a character, and S9(5)V99 has seven of them. The S only says that the item is signed: by default the sign shares the last byte with the last digit, so it costs nothing, and IBM’s reference says S is not counted in the size. The V marks where the decimal point falls and is not stored either, so 123.45 is kept as the digits 0012345. Two things change the count. SIGN LEADING SEPARATE or SIGN TRAILING SEPARATE gives the sign a byte of its own, which makes eight, and another USAGE, such as packed decimal, packs the digits into fewer bytes. FUNCTION BYTE-LENGTH reports the size, so a test can check it instead of a reader counting by eye.

Two harder questions apply these ideas: a record whose fields moved, and a build full of value-size warnings. Try your own answer before you open the first step of each:

Key takeaways

• In USAGE DISPLAY each 9, X or A of a PICTURE string is one byte, so PIC X(8) is 8 bytes and PIC 9(4) holds 42 as the four characters 0042.
• S and V take no byte, so PIC S9(7)V99 is 9 bytes; SIGN … SEPARATE adds one byte for the sign, and P scales a value by digits that are never stored.
• Sizes are counted in bytes: GnuCOBOL only warns when a VALUE does not fit and keeps part of it, CHENNAI CE or 345, so a build with -Werror=others is the safer one.
• A figurative constant takes the length of the item it fills: SPACES puts X’20’ in every byte, HIGH-VALUES X’FF’, LOW-VALUES X’00’, and ALL repeats its literal to the end.
• Reserved words differ by compiler and dialect, as EMI showed, so a prefix on every data name keeps a program buildable everywhere.