What does It mean by Divide Function

Question

DIVIDE  WS-ENT-CNYR-RED BY 4 GIVING WS-DT-CNYR 
  REMAINDER WS-YR-REMAINDER ON SIZE ERROR.

What does it mean?

Answer 1

DIVIDE is a COBOL verb that allows you to do division, like in maths.

This, and, other maths verbs, are covered in your manual and course notes.

The actual DIVIDE you show is syntactically incorrect: you should have an "imperative statement" after the ON SIZE ERROR phrase. No reasonable COBOL compiler will allow that statement to compile.

What is the DIVIDE doing in? It is likely the start of a check for a leap-year. If a year is divisible by four, it is a leap-year candidate (it must also not be divisible by 100 unless it is divisible by 400).

The result of the division is placed in the data-name following the GIVING and the what is "left over" from the division is place in the data-name following the REMAINDER.

Usually when using REMAINDER it will be division with integers, which makes sense for being a year. The year 2015 divided by four gives 503 with a remainder of three. Not a leap year.

The ON SIZE ERROR in this case should be superfluous. It is division by a literal (4) and unless the result fields are not big enough to contain the result, there can never be a SIZE ERROR.

Data-definitions should be:

ll  WS-ENT-CNYR-RED                  PIC 9(4).
ll  WS-DT-CNYR                       PIC 9(3). 
ll  WS-YR-REMAINDER                  PIC 9.

Unless there are very large value for the year, in which case WS-DT-CNYR would need to be 9(4). ll is a level-number, it will be in the range 01-49 (or 1-49) or a 77.

An 88-level condition name should appear on WS-YR-REMAINDER, something like:

88  could-be-leap-year               VALUE ZERO.

GIVING is very common to see in COBOL. If GIVING is not used, then the result is stored in one of the fields mentioned in the statement (you should check which for DIVIDE, MULTIPLY, ADD and SUBTRACT).

REMAINDER you will only see when the "modulus" of a division is required.

There will be no rounding of a result unless the ROUNDED phrase is specified, and rounding with REMAINDER does not make much sense.

In this example, only WS-ENT-CNYR-RED must be a numeric item. WS-DT-CNYR and WS-YR-REMAINDER can both be numeric-edited items. The item on a GIVING will quite often be numeric-edited when formatting report lines. In this typical code for the start of a leap-year check, it is likely that all will be numeric, and all will be integers.

Depending on how much the three items are used, and how they are used, they may be defined as PACKED-DECIMAL (or whichever COMPUTATIONAL-? item is packed-decimal for that compiler) or even binary.

It is not necessary that this is the start of a leap-year check. There can be other reasons for dividing by four and needing to know the remainder.

Note that DIVIDE ... INTO ... is also valid. Indeed, there are five distinct formats of the DIVIDE statement documented in the 1985 COBOL Standard (and earlier ones) which you should see reflected in your manual.

ON SIZE ERROR tells the compiler to generate code when a "size error" occurs. A "size error" is when a result does not fit in a field provided for it.

  ON SIZE ERROR 
      imperative-statement.

or

  ON SIZE ERROR 
      imperative-statement.
END-... (scope-delimiter, consists of END- prefix and verb used, in this case `END-DIVIDE`).

The imperative-statement can be multiple statements, but is usually one (setting the result field to a default value, often zero). Because it can be multiple statements, it is very important to terminate the statement, otherwise you'll make unintended code part of the imperative-statement.

Many people think that ON SIZE ERROR is only actioned for a "divide by zero", but this is not the case. If a result does not fit in a field due to the size of the field, a "size error" has occurred.

I don't use ON SIZE ERROR. I ensure non-zero divisors, and that all result fields are large enough to contain the expected results.

Because I don't use ON SIZE ERROR, I don't know whether the REMAINDER can also cause a size error. I'll check :-)

OK, I've checked. This is with IBM's Enterprise COBOL, which, apart from Extensions, is to the 1985 Standard. If the REMAINDER field is too small to hold the remainder, the ON SIZE ERROR will be actioned. So be very careful about the size of the remainder field, as there is no way of knowing which field caused the size-error.

It is documented like so:

SIZE ERROR phrases For formats 1, 2, and 3, see “SIZE ERROR phrases” on page 296. For formats 4 and 5, if a size error occurs in the quotient, no remainder calculation is meaningful. Therefore, the contents of the quotient field (identifier-3) and the remainder field (identifier-4) are unchanged. If size error occurs in the remainder, the contents of the remainder field (identifier-4) are unchanged. In either of these cases, you must analyze the results to determine which situation has actually occurred.

Formats 4 and 5 are with REMAINDER.

If you don't specify ON SIZE ERROR then the behaviour will be down to the individual compiler, and run-time options. Enterprise COBOL will truncate the fields, but only after going to the run-time (Language Environment) to check whether you wanted something else to happen. Which will consume a lot of time relative to specifying ON SIZE ERROR.

So, ensure your fields are the correct size. If you don't want to do this, use ON SIZE ERROR. If using ON SIZE ERROR with REMAINDER, you have to determine yourself what caused the SIZE ERROR before doing anything.

ON SIZE ERROR has a counterpart, NOT ON SIZE ERROR. It's use is similar to ON SIZE ERROR, except with the obvious difference. ON SIZE ERROR and NOT ON SIZE ERROR can both be used at the same time:

DIVIDE WS-ENT-CNYR-RED       BY 4 
  GIVING                     WS-DT-CNYR 
  REMAINDER                  WS-YR-REMAINDER 
    ON SIZE ERROR
        imperative-statement-1
    NOT ON SIZE ERROR
        imperative-statement-2
END-DIVIDE (or .)