Skip to content
LumenaryAcademy
Foundations 55 min

Decimal arithmetic and money

Why money needs fixed-point decimals, how COBOL stores numbers (zoned, packed, binary), and the arithmetic verbs with ROUNDED and ON SIZE ERROR.

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

A cent is not a binary fraction

Ask almost any language for 0.1 + 0.2 and you get 0.30000000000000004. The reason is that most languages store non-integers as binary floating point (IEEE 754 doubles), and 0.1 has no exact binary representation, in the same way that one third has no exact decimal representation. The stored value is the nearest double, slightly off, and the errors add up.

For physics that is fine: measurements carry error anyway. For money it is not. A bank must be able to say exactly how much is in an account, and an auditor must be able to add up a ledger by hand and get the same answer as the computer, to the cent. A cent in euros, rupees or pesos is one hundredth: a decimal fraction. What money needs is arithmetic that works in decimal, with a fixed number of decimal places.

That is what COBOL has always done. Watch the difference. This program adds one cent a thousand times, once in a COBOL decimal item and once in a double (COMP-2, COBOL's name for a double-precision float):

cobol
IDENTIFICATION DIVISION.
PROGRAM-ID. cents.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 decimal-total  PIC S9(5)V99   VALUE 0.
01 float-total    USAGE COMP-2   VALUE 0.
01 cent-in-float  USAGE COMP-2   VALUE 0.01.
PROCEDURE DIVISION.
    PERFORM 1000 TIMES
        ADD 0.01 TO decimal-total
        ADD cent-in-float TO float-total
    END-PERFORM
    DISPLAY "decimal: " decimal-total
    DISPLAY "float:   " float-total
    STOP RUN.
text
decimal: +00010.00
float:   9.999999999999801

Ten euros exactly, against a number that is almost ten. Rounding the float for display would hide the error here, but in a system that adds millions of amounts, compares balances and splits payments, such errors eventually change a result. Python has a decimal module and Java has BigDecimal for this reason. In COBOL, decimal arithmetic is simply what numbers are.

DefinitionsH

Fixed-point decimals and how they are stored

Definition— Fixed-point decimal number

A number stored as an integer of decimal digits together with a scale, the fixed number of digits after the decimal point. The value is the integer divided by 10scale10^{\text{scale}}. In COBOL the picture gives both: PIC S9(7)V99 holds nine digits with scale 2, so the digits 001234567 mean 12345.67.

Because every value is an exact count of the smallest unit (here, hundredths), addition, subtraction and multiplication by whole numbers are exact. Only division and multiplication by fractions can produce more decimal places than the target holds, and then COBOL either truncates (the default) or rounds (when you say ROUNDED). The programmer always decides which; nothing happens by accident.

The usages

The USAGE clause chooses how a number is stored. The value and the picture stay the same; the bytes differ.

UsageAlso writtenStorageTypical use
DISPLAY(default)One character per digit (zoned decimal)Files people can read, reports, input
PACKED-DECIMALCOMP-3Two digits per byte, sign in the last half-byteAmounts in records and calculations on mainframes
BINARYCOMP, COMP-4A binary integer, sized from the pictureCounters, subscripts, lengths
COMP-5A native binary integer using the full range of its bytesInterfacing with C and system APIs
COMP-1, COMP-2FLOAT-SHORT, FLOAT-LONGBinary floating point, single and doubleScience and statistics, never money

A key point: COMP is still decimal-scaled. PIC S9(7)V99 COMP stores the integer 1234567 in binary and remembers that two of those digits are decimals. It is fixed point, stored in binary. Only COMP-1 and COMP-2 are floating point.

Packed decimal, byte by byte

Packed decimal deserves a closer look, because it is everywhere in mainframe data. Each byte holds two nibbles (half-bytes), each nibble one decimal digit from 0 to 9. The last nibble holds the sign: hexadecimal C for positive, D for negative, F for unsigned. A picture with nn digits therefore needs n+1n + 1 nibbles, rounded up to whole bytes:

bytes=⌊n2⌋+1\text{bytes} = \left\lfloor \frac{n}{2} \right\rfloor + 1

001234567Cbyte 1byte 2byte 3byte 4byte 5implied point (V)sign: C = +
PIC S9(7)V99 COMP-3 holding +12345.67: nine digits and a sign nibble packed into five bytes. The implied decimal point is not stored; the picture says where it is.

You do not have to take the figure on trust. GnuCOBOL 3.2 has a FUNCTION HEX-OF that shows an item's bytes in hexadecimal:

cobol
IDENTIFICATION DIVISION.
PROGRAM-ID. usages.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 zoned-amt    PIC S9(7)V99               VALUE +12345.67.
01 packed-amt   PIC S9(7)V99 USAGE COMP-3  VALUE +12345.67.
01 packed-neg   PIC S9(7)V99 USAGE COMP-3  VALUE -12345.67.
01 binary-amt   PIC S9(7)V99 USAGE COMP    VALUE +12345.67.
01 float-amt    USAGE COMP-2               VALUE 12345.67.
PROCEDURE DIVISION.
    DISPLAY "DISPLAY  bytes " FUNCTION BYTE-LENGTH(zoned-amt)
            "  hex " FUNCTION HEX-OF(zoned-amt)
    DISPLAY "COMP-3   bytes " FUNCTION BYTE-LENGTH(packed-amt)
            "  hex " FUNCTION HEX-OF(packed-amt)
    DISPLAY "COMP-3 - bytes " FUNCTION BYTE-LENGTH(packed-neg)
            "  hex " FUNCTION HEX-OF(packed-neg)
    DISPLAY "COMP     bytes " FUNCTION BYTE-LENGTH(binary-amt)
            "  hex " FUNCTION HEX-OF(binary-amt)
    DISPLAY "COMP-2   bytes " FUNCTION BYTE-LENGTH(float-amt)
    DISPLAY packed-amt " " packed-neg " " binary-amt
    STOP RUN.
text
DISPLAY  bytes 9  hex 303031323334353637
COMP-3   bytes 5  hex 001234567C
COMP-3 - bytes 5  hex 001234567D
COMP     bytes 4  hex 0012D687
COMP-2   bytes 8
+0012345.67 -0012345.67 +0012345.67

Reading the output:

  • DISPLAY takes nine bytes, one per digit: 30 to 39 are the ASCII codes of the characters 0 to 9. On an IBM mainframe, which uses the EBCDIC character set, the digits are F0 to F9, and the sign is folded into the last byte (C7 for a positive 7, D7 for a negative one). That folding is called an overpunch, after the punched-card trick it imitates.
  • COMP-3 takes five bytes, exactly as the figure shows, and the negative value differs only in its last nibble.
  • COMP stores the integer 1234567 (hexadecimal 12D687) in four bytes, most significant byte first, as IBM mainframes do. The scale of 2 lives only in the picture.
  • Whatever the usage, the value is the same, and DISPLAY shows the same number.

Why does packed decimal matter so much? IBM's mainframe processors have had instructions for packed-decimal arithmetic in hardware since the System/360 in the 1960s, so arithmetic on COMP-3 fields is fast there, and it halves the storage of DISPLAY numbers. Generations of record layouts were designed around it. When you meet a mainframe file layout, expect amounts in COMP-3.

ComputationC

The arithmetic verbs

COBOL has two styles of arithmetic. The verbs ADD, SUBTRACT, MULTIPLY and DIVIDE read like ledger instructions. COMPUTE takes an ordinary formula with +, -, *, / and ** (power). Both accept the same options:

OptionEffect
GIVING targetStore the result in target instead of changing an operand
REMAINDER r(DIVIDE only) also store the remainder of an integer division
ROUNDEDRound to the target's decimal places instead of truncating
ON SIZE ERROR ...Run these statements if the result does not fit; the target keeps its old value
NOT ON SIZE ERROR ...Run these statements when it did fit

Mind the direction of the verbs: ADD a TO b changes b; SUBTRACT fee FROM balance changes balance; MULTIPLY rate BY amount changes amount; DIVIDE 3 INTO total changes total, while DIVIDE total BY 3 GIVING share changes only share.

cobol
IDENTIFICATION DIVISION.
PROGRAM-ID. verbs.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 balance      PIC S9(7)V99  VALUE 1500.00.
01 deposit      PIC S9(7)V99  VALUE 249.95.
01 fee          PIC S9(7)V99  VALUE 3.50.
01 quotient     PIC 9(3).
01 leftover     PIC 9(3).
01 third        PIC 9(3)V99.
01 tiny         PIC 99        VALUE 50.
01 interest     PIC S9(7)V99.
PROCEDURE DIVISION.
    ADD deposit TO balance
    SUBTRACT fee FROM balance
    DISPLAY "balance       " balance
    DIVIDE 17 BY 5 GIVING quotient REMAINDER leftover
    DISPLAY "17 / 5        " quotient " remainder " leftover
    DIVIDE 2 BY 3 GIVING third
    DISPLAY "2/3 truncated " third
    DIVIDE 2 BY 3 GIVING third ROUNDED
    DISPLAY "2/3 rounded   " third
    COMPUTE interest ROUNDED = balance * 0.035 / 12
    DISPLAY "interest      " interest
    COMPUTE interest ROUNDED = 1000 * (1 + 0.05) ** 3
    DISPLAY "compounded    " interest
    ADD 60 TO tiny
        ON SIZE ERROR DISPLAY "size error: tiny kept " tiny
    END-ADD
    ADD 60 TO tiny
    DISPLAY "no check:     " tiny
    STOP RUN.
text
balance       +0001746.45
17 / 5        003 remainder 002
2/3 truncated 000.66
2/3 rounded   000.67
interest      +0000005.09
compounded    +0001157.63
size error: tiny kept 50
no check:     10

Three things to notice:

  1. Truncation is the default. Two thirds into two decimal places is 0.66 unless you ask for ROUNDED. For money you almost always want ROUNDED, and the omission is a classic review comment.
  2. One month's interest at 3.5% a year on 1746.45 is 5.0938…, rounded to 5.09. The compounded value 1000 × 1.05³ is exactly 1157.625, and default rounding takes it up to 1157.63: the standard rounding mode rounds a half away from zero.
  3. Overflow is silent unless you check. tiny is PIC 99. With ON SIZE ERROR, the impossible result 110 was rejected and tiny kept 50. Without it, 50 + 60 = 110 was stored as 10, the high-order digit simply dropped. Production code that can overflow should always say what to do about it.

Rounding decisions that change totals

Rounding raises questions that are business rules, not programming details. Two of them come up in every finance system:

cobol
IDENTIFICATION DIVISION.
PROGRAM-ID. rounding.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 prices.
   05 FILLER     PIC 9(3)V99 VALUE 1.05.
   05 FILLER     PIC 9(3)V99 VALUE 2.05.
   05 FILLER     PIC 9(3)V99 VALUE 3.05.
01 price-table REDEFINES prices.
   05 price      PIC 9(3)V99 OCCURS 3 TIMES.
01 i             PIC 9.
01 line-tax      PIC 9(3)V99.
01 sum-of-taxes  PIC 9(3)V99 VALUE 0.
01 net-total     PIC 9(3)V99 VALUE 0.
01 tax-on-total  PIC 9(3)V99.
01 half-cent     PIC 9V999   VALUE 2.125.
01 r-default     PIC 9V99.
01 r-even        PIC 9V99.
01 r-trunc       PIC 9V99.
01 bill          PIC 9(5)V99 VALUE 100.00.
01 share         PIC 9(5)V99.
01 left-over     PIC 9(5)V99.
PROCEDURE DIVISION.
    PERFORM VARYING i FROM 1 BY 1 UNTIL i > 3
        COMPUTE line-tax ROUNDED = price(i) * 0.15
        ADD line-tax TO sum-of-taxes
        ADD price(i) TO net-total
    END-PERFORM
    COMPUTE tax-on-total ROUNDED = net-total * 0.15
    DISPLAY "tax line by line: " sum-of-taxes
    DISPLAY "tax on the total: " tax-on-total
    COMPUTE r-default ROUNDED = half-cent
    COMPUTE r-even ROUNDED MODE NEAREST-EVEN = half-cent
    COMPUTE r-trunc = half-cent
    DISPLAY "2.125 default " r-default " even " r-even " truncated " r-trunc
    DIVIDE bill BY 3 GIVING share
    COMPUTE left-over = bill - share * 3
    DISPLAY "each pays " share ", left over " left-over
    STOP RUN.
text
tax line by line: 000.93
tax on the total: 000.92
2.125 default 2.13 even 2.12 truncated 2.12
each pays 00033.33, left over 00000.01

(The three prices are kept in a small table with OCCURS, which lesson 5 explains; for now read price(i) as "the i-th price".)

  • Round each line or round the total? A 15% tax on 1.05, 2.05 and 3.05 is 0.1575, 0.3075 and 0.4575. Rounded line by line, the taxes sum to 0.93; computed on the total of 6.15, the tax is 0.9225, rounded to 0.92. Both are defensible, and tax authorities and contracts specify which one to use. The program must follow the rule, and the people who check it must know which rule it follows.
  • Which rounding mode? The default rounds halves away from zero, so 2.125 becomes 2.13. Banker's rounding rounds halves to the even neighbour, giving 2.12, which avoids a slight upward bias over many roundings. Recent COBOL standards added ROUNDED MODE with options such as NEAREST-EVEN, NEAREST-AWAY-FROM-ZERO and TRUNCATION, and GnuCOBOL supports it; older code that needs banker's rounding implements it by hand.
  • Where does the odd cent go? 100.00 split three ways is 33.33 each, and 0.01 is left over. Money must never be created or lost, so real systems allocate the remainder explicitly: one party pays 33.34, by a documented rule such as "the first share takes the remainder".

How big are intermediate results?

COMPUTE evaluates its formula with intermediate results that have more digits than any single item; the standard and each compiler define how many. GnuCOBOL computes with arbitrary-precision decimal arithmetic (it uses the GMP library), so intermediate results do not overflow. IBM Enterprise COBOL has fixed limits on the digits of items and intermediate results, which its ARITH compiler option raises, and its programming guide explains how it sizes each intermediate step. In practice: keep formulas simple, give the target enough digits, and use ON SIZE ERROR where a result could grow beyond them.

ExplanationH

Choosing usages and rounding rules in practice

On a real project you rarely choose usages from scratch. Record layouts are shared between dozens of programs, Db2 tables and files exchanged with other organisations, so the layout already decides. Still, the conventions you will see are consistent enough to state:

  • Amounts and rates in records and in working storage are usually COMP-3, signed, with the number of decimals fixed by the business: two for most currencies, none for currencies such as the yen, and four or six for exchange and interest rates. An odd number of digits (S9(9)V99 is eleven) packs without a wasted half-byte.
  • Counters, subscripts and lengths are COMP (binary), often PIC S9(4) COMP or PIC S9(9) COMP, because they are integers that the processor handles natively.
  • Anything a person or another system reads as text, such as a print line, a CSV export or a screen field, is DISPLAY, usually edited.
  • Floating point appears in statistical and actuarial models, never in balances.

Rounding rules deserve the same discipline. Write down, near the code, which rule a calculation follows and where it comes from: a tax regulation, a contract, an accounting standard. Test the halfway cases explicitly, because they are exactly where two plausible implementations disagree. And remember that when a COBOL system is rewritten in another language, the most common source of differences in the results is not a logic error but a rounding or truncation rule the new code did not reproduce.

Common misconceptionsH

Common misconceptions

Misconception

"COMP means floating point." COMP (BINARY) is a binary integer with a decimal scale from the picture: still fixed point and still exact. Floating point is COMP-1 and COMP-2 only.

Misconception

"COBOL rounds automatically." It truncates unless you write ROUNDED. A missing ROUNDED can lose up to a cent on every calculation, always in the same direction.

Misconception

"ON SIZE ERROR fixes the overflow." It only detects it. The target keeps its previous value and your error branch runs; deciding what to do (reject the record, log it, stop the run) is still your job.

Misconception

"Packed decimal is obsolete." It is still the normal format for amounts in mainframe records and Db2 DECIMAL columns, and the hardware still computes with it directly. Anyone who reads mainframe data dumps learns to read COMP-3 by eye.

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. Decimal arithmetic and money

Warm-upHuman

Why do financial systems avoid binary floating point (such as COMP-2 or a C double) for amounts of money?

Choose one

2. Decimal arithmetic and money

Warm-upHuman

How many bytes does PIC S9(9)V99 USAGE COMP-3 take?

3. Decimal arithmetic and money

CoreComputational

What does DISPLAY FUNCTION HEX-OF(small) print for this item? Give the hexadecimal digits.

01 small PIC S9(3) COMP-3 VALUE -42.

4. Decimal arithmetic and money

CoreComputational

With GnuCOBOL, what does this fragment print?

01 x PIC 9V9.
...
    COMPUTE x ROUNDED = 7 / 8
    DISPLAY x

5. Decimal arithmetic and money

CoreComputational

q is PIC 9. After DIVIDE 7 BY 2 GIVING q, what is the value of q?

6. Decimal arithmetic and money

CoreComputational

counter is PIC 999 VALUE 995. This fragment prints three lines. Which values of counter are displayed? Give the two numbers exactly as printed, for example 123, 456.

    ADD 10 TO counter
        ON SIZE ERROR DISPLAY "overflow"
        NOT ON SIZE ERROR DISPLAY "ok"
    END-ADD
    DISPLAY counter
    ADD 10 TO counter
    DISPLAY counter

Write elements separated by commas. Order and repeats don’t matter — just like in a set!

7. Decimal arithmetic and money

StretchHuman

A program splits a payment of 100.00 between three recipients with DIVIDE payment BY 3 GIVING share ROUNDED and pays each one share. What is wrong, and what do finance systems do?

Choose one

Further reading and resources