Arithmetic statements, overflow and ON SIZE ERROR

Add 1500 to a balance of 9000 kept in PIC S9(4) and the balance becomes 500, with no message, no error and no change in how the program ends. COBOL drops the digits a receiver cannot hold unless the statement asks to be told, and whether a binary item overflows at all depends on the dialect and the compiler’s options.

Below you will write the five arithmetic statements with GIVING, REMAINDER and ROUNDED, catch an overflow with ON SIZE ERROR, compare how GnuCOBOL’s dialects and IBM’s TRUNC option treat binary results, read the signs of quotients and remainders, and handle a divisor of zero on purpose.

Each statement says which item gets the result

COBOL has five arithmetic statements, and the form of each says which item receives the result. ADD A TO B and SUBTRACT A FROM B change B. MULTIPLY A BY B stores the product in B, and DIVIDE A INTO B stores B divided by A in B. With GIVING, the operands are only read and the result goes to the item after GIVING. COMPUTE takes a whole arithmetic expression, written with +, -, *, / and **, and stores it in the item before the equals sign. This program runs each of them on one account:

       IDENTIFICATION DIVISION.
       PROGRAM-ID. STATEMENTS.
      * The five arithmetic statements on one account: which item
      * each one changes, and the trap of MULTIPLY ... BY.
       DATA DIVISION.
       WORKING-STORAGE SECTION.
       01  BALANCE      PIC S9(7)V99 VALUE 12500.00.
       01  DEPOSIT      PIC S9(7)V99 VALUE 2500.00.
       01  FEE          PIC S9(5)V99 VALUE 25.00.
       01  QTY          PIC S9(3)    VALUE 3.
       01  PRICE        PIC S9(5)V99 VALUE 199.99.
       01  TOTAL        PIC S9(7)V99.
       01  SHARE-AMT    PIC S9(7)V99.
       01  LEFT-OVER    PIC S9(7)V99.
       01  RATE         PIC SV9(4)   VALUE .0725.
       01  INTEREST     PIC S9(5)V99.
       01  E-OUT        PIC -(7)9.99.
       PROCEDURE DIVISION.
           ADD DEPOSIT TO BALANCE
           MOVE BALANCE TO E-OUT
           DISPLAY "ADD DEPOSIT TO BALANCE       BALANCE   " E-OUT
           SUBTRACT FEE FROM BALANCE
           MOVE BALANCE TO E-OUT
           DISPLAY "SUBTRACT FEE FROM BALANCE    BALANCE   " E-OUT
           MULTIPLY QTY BY PRICE GIVING TOTAL
           MOVE TOTAL TO E-OUT
           DISPLAY "MULTIPLY QTY BY PRICE GIVING TOTAL     " E-OUT
           DIVIDE TOTAL BY 4 GIVING SHARE-AMT REMAINDER LEFT-OVER
           MOVE SHARE-AMT TO E-OUT
           DISPLAY "DIVIDE TOTAL BY 4 GIVING     SHARE-AMT " E-OUT
           MOVE LEFT-OVER TO E-OUT
           DISPLAY "               REMAINDER     LEFT-OVER " E-OUT
           COMPUTE INTEREST ROUNDED = BALANCE * RATE / 12
           MOVE INTEREST TO E-OUT
           DISPLAY "COMPUTE INTEREST ROUNDED     INTEREST  " E-OUT
           MULTIPLY RATE BY BALANCE
           MOVE BALANCE TO E-OUT
           DISPLAY "MULTIPLY RATE BY BALANCE     BALANCE   " E-OUT
           STOP RUN.

from session import files, run

# The five statements on one account.
files("statements.cob")
run("""
cobc -x statements.cob
./statements
""")

$ cobc -x statements.cob
$ ./statements
ADD DEPOSIT TO BALANCE       BALANCE      15000.00
SUBTRACT FEE FROM BALANCE    BALANCE      14975.00
MULTIPLY QTY BY PRICE GIVING TOTAL          599.97
DIVIDE TOTAL BY 4 GIVING     SHARE-AMT      149.99
               REMAINDER     LEFT-OVER        0.01
COMPUTE INTEREST ROUNDED     INTEREST        90.47
MULTIPLY RATE BY BALANCE     BALANCE       1085.68

The DIVIDE line shows REMAINDER: 599.97 split four ways is 149.9925, SHARE-AMT keeps 149.99, and IBM defines the remainder as the dividend minus the quotient times the divisor, so 0.01 is left over. COMPUTE with ROUNDED turned 90.4739… into 90.47. The last line is the classic slip: MULTIPLY RATE BY BALANCE was meant to work out a year’s interest and instead replaced the balance with it.

A result that does not fit loses its high-order digits

A size errorsize error: The condition of an arithmetic statement whose final result has more integer digits than its receiver holds, or that divides by zero. ON SIZE ERROR then keeps the receiver's old value and runs its statement. happens when a result, after its decimal point is lined up with the receiver’s, has more integer digits than the receiver holds, or when a divisor is zero. IBM’s rules give two outcomes. Without an ON SIZE ERROR phrase, “truncation rules apply”: the high-order digits are dropped and the rest is stored. With the phrase, the receiver “is not altered” and the phrase’s statement runs. This program adds 1500 to 9000 in four PIC S9(4) items of different USAGE, first without the phrase and then with it; the session builds it twice:

       IDENTIFICATION DIVISION.
       PROGRAM-ID. SIZE-ERROR.
      * 9000 + 1500 into PIC S9(4) under four USAGEs: first with no
      * ON SIZE ERROR phrase, then with one.
       DATA DIVISION.
       WORKING-STORAGE SECTION.
       01  T-DISPLAY   PIC S9(4)        VALUE 9000.
       01  T-PACKED    PIC S9(4) COMP-3 VALUE 9000.
       01  T-BINARY    PIC S9(4) COMP   VALUE 9000.
       01  T-NATIVE    PIC S9(4) COMP-5 VALUE 9000.
       01  E-OUT       PIC -(5)9.
       PROCEDURE DIVISION.
           DISPLAY "without ON SIZE ERROR"
           ADD 1500 TO T-DISPLAY
           ADD 1500 TO T-PACKED
           ADD 1500 TO T-BINARY
           ADD 1500 TO T-NATIVE
           PERFORM SHOW-ALL
           DISPLAY "with ON SIZE ERROR"
           MOVE 9000 TO T-DISPLAY T-PACKED T-BINARY T-NATIVE
           ADD 1500 TO T-DISPLAY
               ON SIZE ERROR DISPLAY "  DISPLAY size error"
           END-ADD
           ADD 1500 TO T-PACKED
               ON SIZE ERROR DISPLAY "  COMP-3  size error"
           END-ADD
           ADD 1500 TO T-BINARY
               ON SIZE ERROR DISPLAY "  COMP    size error"
               NOT ON SIZE ERROR DISPLAY "  COMP    no size error"
           END-ADD
           ADD 1500 TO T-NATIVE
               ON SIZE ERROR DISPLAY "  COMP-5  size error"
               NOT ON SIZE ERROR DISPLAY "  COMP-5  no size error"
           END-ADD
           PERFORM SHOW-ALL
           ADD 30000 TO T-NATIVE
               ON SIZE ERROR DISPLAY "  COMP-5 + 30000: size error"
           END-ADD
           MOVE T-NATIVE TO E-OUT
           DISPLAY "  COMP-5  " E-OUT
           STOP RUN.
       SHOW-ALL.
           MOVE T-DISPLAY TO E-OUT
           DISPLAY "  DISPLAY " E-OUT
           MOVE T-PACKED TO E-OUT
           DISPLAY "  COMP-3  " E-OUT
           MOVE T-BINARY TO E-OUT
           DISPLAY "  COMP    " E-OUT
           MOVE T-NATIVE TO E-OUT
           DISPLAY "  COMP-5  " E-OUT.

from session import files, run

# 9000 + 1500 into PIC S9(4), built with GnuCOBOL's default dialect and then with -std=ibm.
files("size-error.cob")
run("""
cobc -x size-error.cob
./size-error
cobc -x -std=ibm -o size-error-ibm size-error.cob
./size-error-ibm
""")

$ cobc -x size-error.cob
$ ./size-error
without ON SIZE ERROR
  DISPLAY    500
  COMP-3     500
  COMP       500
  COMP-5   10500
with ON SIZE ERROR
  DISPLAY size error
  COMP-3  size error
  COMP    size error
  COMP-5  no size error
  DISPLAY   9000
  COMP-3    9000
  COMP      9000
  COMP-5   10500
  COMP-5 + 30000: size error
  COMP-5   10500
$ cobc -x -std=ibm -o size-error-ibm size-error.cob
$ ./size-error-ibm
without ON SIZE ERROR
  DISPLAY    500
  COMP-3     500
  COMP     10500
  COMP-5   10500
with ON SIZE ERROR
  DISPLAY size error
  COMP-3  size error
  COMP    no size error
  COMP-5  no size error
  DISPLAY   9000
  COMP-3    9000
  COMP     10500
  COMP-5   10500
  COMP-5 + 30000: size error
  COMP-5   10500

Look at the first build. Without the phrase, the DISPLAY, COMP-3 and COMP totals all became 500, which is 10500 with its high-order 1 dropped. With the phrase, each printed size error and kept 9000. Step through the two paths:

IBM adds two details. The test looks at final results only, never at intermediate results inside a COMPUTE, and ROUNDED is applied before the test, so a value that rounds up past the receiver’s limit is a size error too. The NOT ON SIZE ERROR phrase runs when the result fits, as it did for the COMP-5 item.

Binary receivers follow the dialect, not only the PICTURE

The COMP-5 total behaved differently in both builds: it became 10500, more than four digits, and raised no size error until 30000 more pushed it past 32,767, the limit of two signed bytes. The previous lesson showed why: COMP-5 is held to the capacity of its bytes, not to its PICTURE. The second build shows the trap. Under -std=ibm, GnuCOBOL stored 10500 in the PIC S9(4) COMP item as well, and its ON SIZE ERROR phrase did not run, because that dialect’s configuration sets binary-truncate to no; -fno-trunc does the same in the default dialect.

On z/OS the same choice is the TRUNC compiler option. TRUNC(STD), the default, truncates binary receivers to the number of digits in the PICTURE. TRUNC(BIN) truncates them only at the 2, 4 or 8-byte boundary and makes every binary item behave like COMP-5, which IBM handles that way whatever the option. TRUNC(OPT) lets the compiler truncate whichever way runs faster, and IBM warns that unpredictable results can occur when data does not fit the PICTURE. For ON SIZE ERROR, IBM’s Language Reference sets the limit of a BINARY, COMP, COMP-4 or COMP-5 receiver at its PICTURE, regardless of TRUNC.

The last rows are what IBM documents rather than a run here. They differ from GnuCOBOL’s -std=ibm build, so overflow handling that passes on a laptop proves little about z/OS: test it with the compiler and options of production.

DIVIDE truncates toward zero, and MOD and REM differ

DIVIDE without ROUNDED truncates its quotient toward zero, and its remainder is the dividend minus the quotient times the divisor, so the remainder takes the sign of the dividend. The intrinsic functions offer two other rules. IBM defines MOD with FUNCTION INTEGER, which rounds down to the greatest integer not above the quotient, and REM with FUNCTION INTEGER-PART, which cuts off the fraction. This program divides with negative operands:

       IDENTIFICATION DIVISION.
       PROGRAM-ID. DIVIDE-SIGNS.
      * Quotients and remainders of negative operands: DIVIDE with
      * REMAINDER, the MOD and REM functions, INTEGER and INTEGER-PART.
       DATA DIVISION.
       WORKING-STORAGE SECTION.
       01  Q           PIC S9(3).
       01  R           PIC S9(3).
       01  N           PIC S9(3).
       01  LABEL-TEXT  PIC X(18).
       01  E-Q         PIC -(3)9.
       01  E-R         PIC -(3)9.
       01  E-N         PIC -(3)9.
       PROCEDURE DIVISION.
           DIVIDE 17 BY 5 GIVING Q REMAINDER R
           MOVE "17 BY 5" TO LABEL-TEXT
           PERFORM SHOW-QR
           DIVIDE -17 BY 5 GIVING Q REMAINDER R
           MOVE "-17 BY 5" TO LABEL-TEXT
           PERFORM SHOW-QR
           DIVIDE 17 BY -5 GIVING Q REMAINDER R
           MOVE "17 BY -5" TO LABEL-TEXT
           PERFORM SHOW-QR
           DIVIDE -18 BY 5 GIVING Q ROUNDED REMAINDER R
           MOVE "-18 BY 5, ROUNDED" TO LABEL-TEXT
           PERFORM SHOW-QR
           COMPUTE N = FUNCTION MOD(-17, 5)
           MOVE "MOD(-17, 5)" TO LABEL-TEXT
           PERFORM SHOW-N
           COMPUTE N = FUNCTION REM(-17, 5)
           MOVE "REM(-17, 5)" TO LABEL-TEXT
           PERFORM SHOW-N
           COMPUTE N = FUNCTION INTEGER(-2.5)
           MOVE "INTEGER(-2.5)" TO LABEL-TEXT
           PERFORM SHOW-N
           COMPUTE N = FUNCTION INTEGER-PART(-2.5)
           MOVE "INTEGER-PART(-2.5)" TO LABEL-TEXT
           PERFORM SHOW-N
           STOP RUN.
       SHOW-QR.
           MOVE Q TO E-Q
           MOVE R TO E-R
           DISPLAY LABEL-TEXT " quotient " E-Q "  remainder " E-R.
       SHOW-N.
           MOVE N TO E-N
           DISPLAY LABEL-TEXT " " E-N.

from session import files, run

# Quotients, remainders, MOD, REM, INTEGER and INTEGER-PART of negative operands.
files("divide.cob")
run("""
cobc -x divide.cob
./divide
""")

$ cobc -x divide.cob
$ ./divide
17 BY 5            quotient    3  remainder    2
-17 BY 5           quotient   -3  remainder   -2
17 BY -5           quotient   -3  remainder    2
-18 BY 5, ROUNDED  quotient   -4  remainder   -3
MOD(-17, 5)           3
REM(-17, 5)          -2
INTEGER(-2.5)        -3
INTEGER-PART(-2.5)   -2

-17 BY 5 gave a quotient of -3 and a remainder of -2, and 17 BY -5 a quotient of -3 and a remainder of 2. MOD(-17, 5) was 3, because INTEGER(-3.4) is -4, while REM(-17, 5) was -2, the DIVIDE remainder. INTEGER(-2.5) was -3 and INTEGER-PART(-2.5) was -2. MOD takes the sign of the divisor instead, as IBM’s examples show with MOD(11, -5) = -4, so for a day of the week or a position in a cycle, with a positive divisor, MOD gives the answer that never goes negative.

The fourth line is a surprise: -18 BY 5 with a ROUNDED quotient stored -4, and still a remainder of -3. Step through why:

A zero divisor needs a test or ON SIZE ERROR

An average of zero items divides by zero. This program tries it without the phrase, with DIVIDE and with COMPUTE, then with ON SIZE ERROR, and last with the divisor tested before the division:

       IDENTIFICATION DIVISION.
       PROGRAM-ID. ZERO-DIVIDE.
      * An average over zero items: DIVIDE and COMPUTE without ON SIZE
      * ERROR, the exception the run records, then the same DIVIDE
      * with the phrase, and with the divisor tested first.
       DATA DIVISION.
       WORKING-STORAGE SECTION.
       01  TOTAL       PIC S9(5)V99 VALUE 1000.00.
       01  ITEM-COUNT  PIC S9(3)    VALUE 0.
       01  AVERAGE     PIC S9(5)V99 VALUE 77.00.
       01  E-OUT       PIC -(5)9.99.
       PROCEDURE DIVISION.
           DIVIDE TOTAL BY ITEM-COUNT GIVING AVERAGE
           MOVE AVERAGE TO E-OUT
           DISPLAY "DIVIDE, no phrase:    AVERAGE " E-OUT
           DISPLAY "exception status:     "
               FUNCTION EXCEPTION-STATUS
           COMPUTE AVERAGE = TOTAL / ITEM-COUNT
           MOVE AVERAGE TO E-OUT
           DISPLAY "COMPUTE, no phrase:   AVERAGE " E-OUT
           DIVIDE TOTAL BY ITEM-COUNT GIVING AVERAGE
               ON SIZE ERROR
                   MOVE ZERO TO AVERAGE
                   DISPLAY "ON SIZE ERROR ran:    AVERAGE set to 0"
           END-DIVIDE
           IF ITEM-COUNT = ZERO
               DISPLAY "divisor tested first: no items, no average"
           ELSE
               DIVIDE TOTAL BY ITEM-COUNT GIVING AVERAGE
           END-IF
           DISPLAY "the run carried on"
           STOP RUN.

from session import files, run

# A zero divisor with and without ON SIZE ERROR. A command that fails would be followed by "[exit status N]".
files("zero-divide.cob")
run("""
cobc -x zero-divide.cob
./zero-divide
""")

$ cobc -x zero-divide.cob
$ ./zero-divide
DIVIDE, no phrase:    AVERAGE     77.00
exception status:     EC-SIZE-ZERO-DIVIDE
COMPUTE, no phrase:   AVERAGE     77.00
ON SIZE ERROR ran:    AVERAGE set to 0
divisor tested first: no items, no average
the run carried on

GnuCOBOL 3.2 left AVERAGE at its old value, 77.00, after both statements without the phrase, recorded the exception EC-SIZE-ZERO-DIVIDE, which FUNCTION EXCEPTION-STATUS returned, and carried on to its last line. GnuCOBOL’s own Programmer’s Guide says such a division ends the program with an error message, so the documentation and this build disagree. On z/OS a zero divisor in decimal arithmetic is a decimal-divide exception, system completion code 0CB, and in binary arithmetic a fixed-point-divide exception, 0C9.

One statement with three possible outcomes, a stale value, a stop or an abend, is reason enough to decide on purpose. A zero divisor that the business expects, such as an account with no transactions, gets its own branch, as the last block did. ON SIZE ERROR stays on the DIVIDE as a safety net for the cases nobody expected.

Practise: predict the result before the run

Each question takes its numbers from this lesson’s runs. Work out what the receiver holds before you choose; the explanations name the rule a wrong choice missed:

Interview questions

Warm-up (fresher to 2–5 years): what does ON SIZE ERROR do, and what happens without it?

ON SIZE ERROR is a phrase of ADD, SUBTRACT, MULTIPLY, DIVIDE and COMPUTE. A size error occurs when the final result has more integer digits than the receiver holds, after any rounding, or when a divisor is zero. With the phrase, the receiver keeps its old value and the statement after ON SIZE ERROR runs, so the program can reject or report the record; NOT ON SIZE ERROR runs when the result fits. Without the phrase the result is truncated on the left and stored with no message: 9000 + 1500 into PIC S9(4) left 0500. Binary items add a twist, because GnuCOBOL’s dialects and IBM’s TRUNC option decide whether a COMP receiver is cut to its PICTURE, so overflow handling is tested with the compiler options of production.

Two harder questions apply these ideas: a balance that wrapped without a message, and a binary total that differs between a laptop and z/OS. Work out your answer first, then open each first step:

Key takeaways

• Each arithmetic statement names its receiver: TO, FROM, BY and INTO change their second item, GIVING sends the result elsewhere, and MULTIPLY RATE BY BALANCE replaced the balance.
• Without ON SIZE ERROR an overflow drops the high-order digits silently, so 9000 + 1500 left 0500; with the phrase the receiver kept 9000 and the phrase ran.
• Binary receivers follow the dialect and the options: GnuCOBOL’s -std=ibm and COMP-5 kept 10500 in PIC S9(4) with no size error, while IBM documents a size error at the PICTURE whatever TRUNC is.
• DIVIDE and REM truncate toward zero and keep the dividend’s sign, MOD rounds down, and a ROUNDED quotient does not match its remainder.
• A zero divisor left GnuCOBOL’s receiver unchanged and is an 0CB or 0C9 abend on z/OS, so test the divisor and keep ON SIZE ERROR as a safety net.