Editing Business rules (section)

= Business Rules =

'''Project:''' pgcobol — Prime Numbers Application<br />
'''Version:''' 1.0 (reverse-engineered)<br />
'''Date:''' 2026-03-17


-----

<span id="primality-algorithm"></span>
== 1. Primality Algorithm ==

<span id="br-algo-01-input-domain"></span>
=== BR-ALGO-01 — Input domain ===

Only odd integers are tested for primality. The sieve begins at <code>test-number = 3</code> and advances in steps of 2 (<code>ADD 2 TO test-number</code>), implicitly excluding all even numbers. The even prime 2 is intended as a seed but is not currently inserted in the active code path.

<span id="br-algo-02-upper-bound"></span>
=== BR-ALGO-02 — Upper bound ===

Generation terminates when <code>test-number = 999,999,999</code>. This value is the terminal condition of the PERFORM loop in primesgen.

<pre>PERFORM r80-test-number UNTIL test-number = 999999999</pre>
<span id="br-algo-03-divisibility-test"></span>
=== BR-ALGO-03 — Divisibility test ===

A candidate is composite if the remainder of dividing it by the current trial divisor is zero:

<pre>DIVIDE test-number BY test-divider
       GIVING test-quot REMAINDER test-rest

WHEN test-rest = 0  →  composite; skip to next candidate</pre>
<span id="br-algo-04-square-root-bound-trial-division-cutoff"></span>
=== BR-ALGO-04 — Square-root bound (trial-division cutoff) ===

If the current trial divisor exceeds the square root of the candidate, no factor can exist and the candidate is prime. The square root is computed using COBOL exponentiation:

<pre>COMPUTE test-number-sqr = test-number ** 0.5

WHEN test-divider &gt; test-number-sqr  →  prime confirmed</pre>
<code>test-number-sqr</code> is re-computed every time <code>test-number</code> advances (in <code>r82-next-test-number</code>).

<span id="br-algo-05-trial-divisors-sourced-from-the-database"></span>
=== BR-ALGO-05 — Trial divisors sourced from the database ===

Trial divisors are not held in memory; they are fetched from the <code>primes</code> table by <code>ident</code> sequence:

<pre>SELECT prime FROM primes WHERE ident = :new-ident</pre>
The index <code>old-ident</code> is initialised to 1 for each new candidate and incremented by 1 on each <code>next-divider</code> call. This means the algorithm uses previously stored primes as divisors — a characteristic of a sieve-of-Eratosthenes variant rather than pure trial division.

<span id="br-algo-06-candidate-advance-rule"></span>
=== BR-ALGO-06 — Candidate advance rule ===

After a composite or prime determination, the candidate advances to the next odd integer and the divisor index resets:

<pre>ADD 2 TO test-number
COMPUTE test-number-sqr = test-number ** 0.5
MOVE 1 TO old-ident
PERFORM r89-get-next-divider   ← loads test-divider = first prime (ident 1)</pre>

-----

<span id="data-validation-rules"></span>
== 2. Data Validation Rules ==

<span id="br-val-01-command-line-argument"></span>
=== BR-VAL-01 — Command-line argument ===

The application accepts exactly one of two valid argument values:

{|
! Value
! Effect
|-
| <code>&quot;report&quot;</code>
| Execute reporting path
|-
| <code>&quot;generate&quot;</code>
| Execute generation path
|-
| anything else
| Log error; <code>STOP RUN</code> immediately
|}

Rule is implemented by 88-level conditions and an <code>EVALUATE TRUE</code> with <code>WHEN OTHER</code>:

<pre>88 report-primes   VALUE &quot;report&quot;.
88 generate-primes VALUE &quot;generate&quot;.
...
WHEN OTHER
  LOG &quot;Bad parameter, program initialisation failed.&quot;
  STOP RUN</pre>
<span id="br-val-02-ui-initialisation-must-succeed-before-processing"></span>
=== BR-VAL-02 — UI initialisation must succeed before processing ===

If <code>primesui</code> returns <code>ui-method-result ≠ 0</code> on a <code>&quot;start&quot;</code> call, the program issues an emergency console message and halts unconditionally. No database activity is attempted.

<pre>IF ui-method-ok THEN ...
ELSE
  DISPLAY &quot;Emergency console message program stops.&quot; UPON scherm
  STOP RUN</pre>
<span id="br-val-03-database-connection-must-succeed-before-processing"></span>
=== BR-VAL-03 — Database connection must succeed before processing ===

In both <code>r90-start-primes-report</code> and <code>r91-start-primes-generation</code>, a failed <code>&quot;connect&quot;</code> call sets <code>session-result = 1</code> and processing does not continue. The condition is checked via:

<pre>IF dal-method-ok THEN ...
ELSE
  LOG &quot;Database initialisation failed.&quot;
  session-result = 1
  (falls through to r99-close-primes)</pre>
<span id="br-val-04-cursor-must-open-successfully-before-fetching"></span>
=== BR-VAL-04 — Cursor must open successfully before fetching ===

In the report path, cursor failure sets <code>session-result = 1</code> and no fetch loop is entered. The guard is:

<pre>IF dal-method-ok THEN
  PERFORM r86-report-primes UNTIL session-method-eof</pre>
<span id="br-val-05-sqlcode-0-is-the-sole-sql-success-criterion"></span>
=== BR-VAL-05 — SQLCODE = 0 is the sole SQL success criterion ===

All SQL error handling uses <code>IF SQLCODE = 0 THEN ... ELSE ...</code>. No other status codes (e.g., +100 NOT FOUND) are explicitly handled with named conditions; they fall into the <code>ELSE</code> branch.


-----

<span id="calculations"></span>
== 3. Calculations ==

<span id="br-calc-01-square-root-computation"></span>
=== BR-CALC-01 — Square root computation ===

<pre>COMPUTE test-number-sqr = test-number ** 0.5</pre>
<code>test-number-sqr</code> is declared as <code>PIC 9(9)V9(9)</code> — an 18-digit decimal with 9 integer and 9 fractional digits. The comparison <code>test-divider &gt; test-number-sqr</code> relies on COBOL’s decimal comparison across the two fields.

<span id="br-calc-02-remainder-computation"></span>
=== BR-CALC-02 — Remainder computation ===

<pre>DIVIDE test-number BY test-divider
       GIVING test-quot REMAINDER test-rest</pre>
Both <code>test-quot</code> and <code>test-rest</code> are declared <code>PIC 9(9)V9(9)</code>. The condition <code>test-rest = 0</code> detects exact divisibility.


-----

<span id="output-formatting-rules"></span>
== 4. Output Formatting Rules ==

<span id="br-fmt-01-six-primes-per-print-line"></span>
=== BR-FMT-01 — Six primes per print line ===

The <code>primes-table</code> working-storage in primesui holds 6 cells. A line is written to the print file only when all 6 are filled (<code>primes-idx = 7</code> after increment):

<pre>IF primes-idx = 7 THEN
  WRITE print line
  SET primes-idx TO 1</pre>
<span id="br-fmt-02-zero-suppression"></span>
=== BR-FMT-02 — Zero suppression ===

Sequence numbers and prime values are formatted with <code>PIC Z(9)</code> (leading-zero suppression) in the print cells <code>t-ident</code> and <code>t-prime</code>.

<span id="br-fmt-03-page-trigger-at-line-53"></span>
=== BR-FMT-03 — Page trigger at line 53 ===

End-of-page processing fires when <code>linage-counter = 53</code> (3 lines before the 56-line page boundary), leaving room for the footing:

<pre>IF linage-counter = 53 THEN PERFORM r94-eop</pre>
<span id="br-fmt-04-new-page-flag-controls-heading-output"></span>
=== BR-FMT-04 — New-page flag controls heading output ===

<code>print-new-page</code> (88 condition <code>new-page</code>, VALUE 1) is the gate for writing the heading. It is set to 1 at initialisation and after each page footing; cleared to 0 after the heading is written:

<pre>IF new-page THEN PERFORM r93-new-page
...
r93-new-page:
  MOVE ZERO TO print-new-page</pre>
<span id="br-fmt-05-partial-line-flush-at-stop"></span>
=== BR-FMT-05 — Partial line flush at stop ===

When <code>primesui</code> receives <code>&quot;stop&quot;</code>, it pads the remaining cells with zeros and keeps calling <code>r92-write-primesui</code> until <code>new-page</code> triggers (i.e., until the partial line fills, writes, and a new page would be needed), ensuring the last data line is always written:

<pre>MOVE 0 TO u-sequence
MOVE 0 TO u-number
PERFORM r92-write-primesui UNTIL new-page</pre>

-----

<span id="session-and-error-handling-rules"></span>
== 5. Session and Error-Handling Rules ==

<span id="br-err-01-result-code-convention"></span>
=== BR-ERR-01 — Result-code convention ===

All three tier interfaces use the same pattern:

{|
! Code
! Meaning
|-
| 0
| Success
|-
| 1
| Failure / error
|-
| 9 or 99
| End-of-data / EOF
|}

<span id="br-err-02-no-retry-on-failure"></span>
=== BR-ERR-02 — No retry on failure ===

Errors at any tier cause a log message and a result code of 1. The calling tier checks the result and either skips subsequent steps or falls through to cleanup. There is no retry logic.

<span id="br-err-03-cleanup-always-attempted"></span>
=== BR-ERR-03 — Cleanup always attempted ===

<code>r99-close-primes</code> in primesgen and <code>r99-stop-session</code> in primesmain are always performed before <code>EXIT PROGRAM</code> or <code>STOP RUN</code>, regardless of whether prior steps succeeded. This ensures the database connection and print file are always closed.
<hr/>
Terug naar: [[Primes_programs_specifications]] | [[Cobol and PostgreSQL]]