Editing Business-Requirements (section)

= Business Requirements =

<blockquote>'''Document ID:''' PGCBL-BRD-001 · '''Version:''' 1.0 · '''Status:''' Approved · '''Last updated:''' 2026-03-17
</blockquote>
'''← [[Primes system Design]]''' | [[Technical-Specification|Technical Specification →]]


-----

<span id="contents"></span>
== Contents ==

# [[#1-business-objective|Business Objective]]
# [[#2-stakeholders|Stakeholders]]
# [[#3-functional-requirements|Functional Requirements]]
#* [[#fr-01--prime-generation|FR-01 Prime Generation]]
#* [[#fr-02--trial-division-algorithm|FR-02 Trial-Division Algorithm]]
#* [[#fr-03--prime-reporting|FR-03 Prime Reporting]]
#* [[#fr-04--print-report-format|FR-04 Print Report Format]]
#* [[#fr-05--operational-logging|FR-05 Operational Logging]]
#* [[#fr-06--error-handling|FR-06 Error Handling]]
# [[#4-non-functional-requirements|Non-Functional Requirements]]
# [[#5-constraints|Constraints]]
# [[#6-out-of-scope|Out of Scope]]
# [[#7-traceability|Traceability]]


-----

<span id="business-objective"></span>
== 1. Business Objective ==

The system must generate and persistently store the complete sequence of prime numbers from 3 up to 999,999,999, and produce a paginated formatted print report of all stored primes on demand.

It demonstrates a '''three-tier COBOL architecture''' on Linux with a PostgreSQL back-end:

{|
!width="33%"| Tier
!width="33%"| Program
!width="33%"| Responsibility
|-
| Orchestrator
| <code>primesmain</code>
| Command-line routing, session lifecycle
|-
| Business Logic
| <code>primesgen</code>
| Sieve algorithm, report cursor loop
|-
| Data Access
| <code>primes</code>
| All SQL via GixSQL
|-
| Presentation
| <code>primesui</code>
| Print file, console logging
|}

See [[Technical-Specification#1-system-architecture|Technical Specification → Architecture]] for the component diagram.


-----

<span id="stakeholders"></span>
== 2. Stakeholders ==

{|
!width="50%"| Role
!width="50%"| Interest
|-
| '''System operator'''
| Runs generation and reporting jobs from the command line; reads console output
|-
| '''Database administrator'''
| Owns the PostgreSQL <code>primes</code> schema; manages credentials and data
|-
| '''Report consumer'''
| Receives and reads the formatted print file <code>primes.prt</code>
|}


-----

<span id="functional-requirements"></span>
== 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>
== 4. Non-Functional Requirements ==

{|
!width="33%"| ID
!width="33%"| Category
!width="33%"| Requirement
|-
| NFR-01
| Platform
| Must run on Linux using GnuCOBOL 4.0
|-
| NFR-02
| Database
| Must connect to PostgreSQL 11+ at <code>localhost:5432</code>, database <code>primes</code>
|-
| NFR-03
| Persistence
| Generated primes must survive program termination
|-
| NFR-04
| Restartability
| Running <code>reset-primes.sql</code> must produce a clean, empty database state
|}


-----

<span id="constraints"></span>
== 5. Constraints ==

{|
!width="33%"| ID
!width="33%"| Constraint
!width="33%"| Source
|-
| C-01
| Upper generation bound is fixed at '''999,999,999'''
| Hard-coded in <code>primesgen.cbl</code>
|-
| C-02
| Database credentials are hard-coded
| <code>primes.cbl</code> WORKING-STORAGE — technical debt
|-
| C-03
| Single-user batch execution only
| Architecture; no concurrency controls
|-
| C-04
| Generate and report are mutually exclusive per invocation
| <code>primesmain.cbl</code> EVALUATE structure
|-
| C-05
| Prime 2 must be manually seeded before a generation run
| Algorithm limitation; sieve starts at 3
|}


-----

<span id="out-of-scope"></span>
== 6. Out of Scope ==

* Interactive or web-based user interfaces
* Concurrent or distributed execution
* Primes above 999,999,999
* Generation algorithms other than trial division
* Checkpoint / restart for interrupted generation runs
* Encryption or secure credential handling (in this version)


-----

<span id="traceability"></span>
== 7. Traceability ==

{|
!width="33%"| Requirement
!width="33%"| Design element
!width="33%"| Flow diagram
|-
| FR-01, FR-02
| <code>primesgen.cbl</code> r80–r89; <code>primes.cbl</code> r83, r81
| [[Flow-Diagrams#3-prime-generation-sieve-loop|Sieve Loop]] · [[Flow-Diagrams#7-inter-program-call-sequence--generate-run|Generate Sequence]]
|-
| FR-03
| <code>primesgen.cbl</code> r86, r90, r94; <code>primes.cbl</code> s01, s02
| [[Flow-Diagrams#4-prime-report-loop|Report Loop]] · [[Flow-Diagrams#8-inter-program-call-sequence--report-run|Report Sequence]]
|-
| FR-04
| <code>primesui.cbl</code> r90–r94
| [[Flow-Diagrams#6-ui-primesui-method-dispatch|UI Dispatch]]
|-
| FR-05
| <code>primesui.cbl</code> r98; <code>primes-ui.cpy</code> process-message
| [[Data-Dictionary#13-primes-ui|Data Dictionary — primes-ui]]
|-
| FR-06
| <code>primesmain.cbl</code> WHEN OTHER; all result-code checks
| [[Flow-Diagrams#1-top-level-application-flow|Top-Level Flow]]
|}


-----

'''← [[Home]]''' | [[Technical-Specification|Technical Specification →]]