Business-Requirements
Jump to navigation
Jump to search
Business Requirements
Document ID: PGCBL-BRD-001 · Version: 1.0 · Status: Approved · Last updated: 2026-03-17
← Home | Technical Specification →
Contents
- Business Objective
- Stakeholders
- Functional Requirements
- Non-Functional Requirements
- Constraints
- Out of Scope
- Traceability
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:
| Tier | Program | Responsibility |
|---|---|---|
| Orchestrator | primesmain
|
Command-line routing, session lifecycle |
| Business Logic | primesgen
|
Sieve algorithm, report cursor loop |
| Data Access | primes
|
All SQL via GixSQL |
| Presentation | primesui
|
Print file, console logging |
See Technical Specification → Architecture for the component diagram.
2. Stakeholders
| Role | Interest |
|---|---|
| System operator | Runs generation and reporting jobs from the command line; reads console output |
| Database administrator | Owns the PostgreSQL primes schema; manages credentials and data
|
| Report consumer | Receives and reads the formatted print file primes.prt
|
3. Functional Requirements
FR-01 — Prime Generation
| ID | Requirement |
|---|---|
| FR-01-a | The system shall accept a generate 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. |
⚠ Defect T1: The PERFORM that invokes the sieve loop is commented out in
primesmain.cblline 51. This requirement is not currently met by the shipped source. See Technical Specification → Defect Register.
FR-02 — Trial-Division Algorithm
| ID | 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 primesgen.cbl paragraphs r80-test-number through r89-get-next-divider. See Flow Diagrams → Sieve Loop.
FR-03 — Prime Reporting
| ID | Requirement |
|---|---|
| FR-03-a | The system shall accept a report 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 primesgen.cbl paragraphs r90-start-primes-report and r86-report-primes. See Flow Diagrams → Report Loop.
FR-04 — Print Report Format
| ID | Requirement |
|---|---|
| FR-04-a | The report shall carry the heading "primes overview" on every page.
|
| FR-04-b | A column header row ("Sequence Prime" × 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 (page: ZZZZ9).
|
| FR-04-e | The print record width shall be exactly 132 characters. |
| FR-04-f | The print file shall be named primes.prt and written to the working directory.
|
Print formatting is implemented entirely in primesui.cbl. See Technical Specification → File I/O Specification for the full record layout.
Print record layout (one data line):
┌────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ │ 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
Each cell in
primesuiis actuallyZ(9) + X(2) + Z(9) + X(2)= 22 chars × 6 = 132.
FR-05 — Operational Logging
| ID | 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 primesui paragraph r98-message-ui using the process-message group in primes-ui.
FR-06 — Error Handling
| ID | 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 session-result = 1.
|
| FR-06-d | A cursor open failure shall cause the system to log an error and set session-result = 1.
|
| FR-06-e | A fetch failure shall cause the system to log an error and terminate the fetch loop. |
4. Non-Functional Requirements
| ID | Category | Requirement |
|---|---|---|
| NFR-01 | Platform | Must run on Linux using GnuCOBOL 4.0 |
| NFR-02 | Database | Must connect to PostgreSQL 11+ at localhost:5432, database primes
|
| NFR-03 | Persistence | Generated primes must survive program termination |
| NFR-04 | Restartability | Running reset-primes.sql must produce a clean, empty database state
|
5. Constraints
| ID | Constraint | Source |
|---|---|---|
| C-01 | Upper generation bound is fixed at 999,999,999 | Hard-coded in primesgen.cbl
|
| C-02 | Database credentials are hard-coded | primes.cbl 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 | primesmain.cbl EVALUATE structure
|
| C-05 | Prime 2 must be manually seeded before a generation run | Algorithm limitation; sieve starts at 3 |
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)
7. Traceability
| Requirement | Design element | Flow diagram |
|---|---|---|
| FR-01, FR-02 | primesgen.cbl r80–r89; primes.cbl r83, r81
|
Sieve Loop · Generate Sequence |
| FR-03 | primesgen.cbl r86, r90, r94; primes.cbl s01, s02
|
Report Loop · Report Sequence |
| FR-04 | primesui.cbl r90–r94
|
UI Dispatch |
| FR-05 | primesui.cbl r98; primes-ui.cpy process-message
|
Data Dictionary — primes-ui |
| FR-06 | primesmain.cbl WHEN OTHER; all result-code checks
|
Top-Level Flow |