Editing Business-Requirements (section)

== 3. Functional Requirements ==

<span id="fr-01-prime-generation"></span>
=== FR-01 — Prime Generation ===

{|
!width="50%"| ID
!width="50%"| Requirement
|-
| FR-01-a
| The system shall accept a <code>generate</code> command-line argument to trigger prime-number generation.
|-
| FR-01-b
| The system shall test every odd integer from 3 upward for primality using trial division.
|-
| FR-01-c
| The system shall store each confirmed prime in the database in ascending order of discovery.
|-
| FR-01-d
| Generation shall continue until the candidate number reaches 999,999,999.
|}

<blockquote>⚠ '''Defect T1:''' The PERFORM that invokes the sieve loop is commented out in <code>primesmain.cbl</code> line 51. This requirement is '''not currently met''' by the shipped source. See [[Technical-Specification#7-known-technical-issues|Technical Specification → Defect Register]].
</blockquote>

-----

<span id="fr-02-trial-division-algorithm"></span>
=== FR-02 — Trial-Division Algorithm ===

{|
!width="50%"| ID
!width="50%"| Requirement
|-
| FR-02-a
| For each candidate number N, the system shall divide N by each known prime p where p ≤ √N.
|-
| FR-02-b
| If any p divides N exactly (remainder = 0), N is composite and shall not be stored.
|-
| FR-02-c
| If no such p exists, N is confirmed prime and shall be persisted.
|-
| FR-02-d
| Trial divisors shall be read from the database in identity sequence order.
|}

The algorithm implementation lives in <code>primesgen.cbl</code> paragraphs <code>r80-test-number</code> through <code>r89-get-next-divider</code>. See [[Flow-Diagrams#3-prime-generation-sieve-loop|Flow Diagrams → Sieve Loop]].


-----

<span id="fr-03-prime-reporting"></span>
=== FR-03 — Prime Reporting ===

{|
!width="50%"| ID
!width="50%"| Requirement
|-
| FR-03-a
| The system shall accept a <code>report</code> command-line argument to trigger report generation.
|-
| FR-03-b
| The system shall read all stored primes from the database in sequence order.
|-
| FR-03-c
| The system shall write a paginated, formatted print file containing all stored primes.
|}

The report loop lives in <code>primesgen.cbl</code> paragraphs <code>r90-start-primes-report</code> and <code>r86-report-primes</code>. See [[Flow-Diagrams#4-prime-report-loop|Flow Diagrams → Report Loop]].


-----

<span id="fr-04-print-report-format"></span>
=== FR-04 — Print Report Format ===

{|
!width="50%"| ID
!width="50%"| Requirement
|-
| FR-04-a
| The report shall carry the heading <code>&quot;primes overview&quot;</code> on every page.
|-
| FR-04-b
| A column header row (<code>&quot;Sequence  Prime&quot;</code> × 6) shall follow the heading on every page.
|-
| FR-04-c
| Each data line shall display '''six''' prime entries side by side — sequence number and prime value.
|-
| FR-04-d
| Each page shall carry a right-aligned page-number footer (<code>page: ZZZZ9</code>).
|-
| FR-04-e
| The print record width shall be exactly '''132 characters'''.
|-
| FR-04-f
| The print file shall be named <code>primes.prt</code> and written to the working directory.
|}

Print formatting is implemented entirely in <code>primesui.cbl</code>. See [[Technical-Specification#6-file-io-specification|Technical Specification → File I/O Specification]] for the full record layout.

'''Print record layout (one data line):'''

<pre>┌────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ Z(9) sp sp │ Z(9) sp sp │ Z(9) sp sp │ Z(9) sp sp │ Z(9) sp sp │ Z(9) sp sp │
│  seq 1     │  prime 1   │  seq 2     │  prime 2   │  seq 3     │  prime 3   │ … × 6
│  11 chars  │  11 chars  │  11 chars  │  11 chars  │  11 chars  │  11 chars  │
└────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
  Each cell = 9 (value) + 2 (separator) = 11 chars × 6 entries = 66 chars of data + 66 chars padding = 132 total</pre>
<blockquote>Each cell in <code>primesui</code> is actually <code>Z(9) + X(2) + Z(9) + X(2)</code> = 22 chars × 6 = 132.
</blockquote>

-----

<span id="fr-05-operational-logging"></span>
=== FR-05 — Operational Logging ===

{|
!width="50%"| ID
!width="50%"| Requirement
|-
| FR-05-a
| The system shall write progress and status messages to the system console throughout execution.
|-
| FR-05-b
| Each structured message shall identify the issuing '''program name''' and '''paragraph name'''.
|-
| FR-05-c
| Significant events shall be logged: session start/stop, DB connect/disconnect, cursor open, first fetch, fetch errors, print file open/close.
|}

Logging is routed through <code>primesui</code> paragraph <code>r98-message-ui</code> using the <code>process-message</code> group in [[Data-Dictionary#13-primes-ui|<code>primes-ui</code>]].


-----

<span id="fr-06-error-handling"></span>
=== FR-06 — Error Handling ===

{|
!width="50%"| ID
!width="50%"| Requirement
|-
| FR-06-a
| An unrecognised command-line argument shall cause the system to log an error and stop cleanly.
|-
| FR-06-b
| Failure to open the print file shall cause the system to log an error and stop.
|-
| FR-06-c
| A database connection failure shall cause the system to log an error and set <code>session-result = 1</code>.
|-
| FR-06-d
| A cursor open failure shall cause the system to log an error and set <code>session-result = 1</code>.
|-
| FR-06-e
| A fetch failure shall cause the system to log an error and terminate the fetch loop.
|}


-----

<span id="non-functional-requirements"></span>