Editing Business Requirement Document (section)

= Business Requirements Document =

{|
!width="23%"| Field
!width="76%"| Value
|-
| Document ID
| PGCBL-BRD-001
|-
| Document Type
| Business Requirements Document
|-
| System
| pgcobol — Prime Numbers Application v1.0
|-
| Version
| 1.0
|-
| Status
| Approved
|-
| Owner
| Lead Developer
|-
| Author
| [reverse-engineered from source artifacts]
|-
| Reviewers
| — (pending)
|-
| Approved by
| — (pending)
|-
| Created
| 2026-03-17
|-
| Last modified
| 2026-03-17
|-
| Classification
| Internal
|-
| Parent document
| PGCBL-SAD-001 (Scope and Applicability)
|-
| Supersedes
| —
|}

<span id="version-history"></span>
== Version History ==

{|
!width="11%"| Version
!width="14%"| Date
!width="9%"| Author
!width="12%"| Status
!width="51%"| Change Summary
|-
| 0.1
| 2026-03-17
| —
| Draft
| Initial reverse-engineering baseline
|-
| 1.0
| 2026-03-17
| —
| Approved
| Baselined
|}


-----

<span id="table-of-contents"></span>
== Table of Contents ==

# [[#1-purpose-and-scope|Purpose and Scope]]
# [[#2-assumptions-and-dependencies|Assumptions and Dependencies]]
# [[#3-stakeholders|Stakeholders]]
# [[#4-functional-requirements|Functional Requirements]]
# [[#5-non-functional-requirements|Non-Functional Requirements]]
# [[#6-constraints|Constraints]]
# [[#7-out-of-scope|Out of Scope]]
# [[#8-related-documents|Related Documents]]
# [[#9-open-issues|Open Issues]]


-----

<span id="purpose-and-scope"></span>
== 1. Purpose and Scope ==

<span id="purpose"></span>
=== 1.1 Purpose ===

This document defines what the pgcobol system must do from a business perspective. It is the primary input to all technical and design documents in the specification set. Any feature not described here is out of scope.

<span id="scope"></span>
=== 1.2 Scope ===

This document covers all externally observable behaviour of pgcobol v1.0: prime-number generation, database persistence, and printed report production.

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

* How the system achieves its requirements (that is PGCBL-TSD-001).
* Internal program structure and algorithm details (PGCBL-PLG-001).
* Non-functional quality attributes in detail (PGCBL-NFR-001).

<span id="audience"></span>
=== 1.4 Audience ===

Business analysts, QA engineers, and stakeholders who need to understand what the system does without needing to read COBOL.

<span id="related-documents"></span>
=== 1.5 Related Documents ===

{|
!width="27%"| Document ID
!width="50%"| Title
!width="22%"| Relationship
|-
| PGCBL-SAD-001
| Scope and Applicability
| Navigation; defines document set
|-
| PGCBL-NFR-001
| Non-Functional Requirements
| Complements this BRD with quality attributes
|-
| PGCBL-TSD-001
| Technical Specification
| Implements requirements in this document
|-
| PGCBL-TTM-001
| Test Traceability Matrix
| Maps each requirement here to a test case
|-
| PGCBL-ADD-001
| Architecture Decision Records
| Documents why the design is as it is
|}


-----

<span id="assumptions-and-dependencies"></span>
== 2. Assumptions and Dependencies ==

See PGCBL-SAD-002 for the full register. Key items:

{|
!width="36%"| ID
!width="31%"| Item
!width="31%"| Type
|-
| A-01
| Prime 2 is manually seeded in the DB before generation
| Assumption
|-
| A-02
| DB is empty at the start of a generation run
| Assumption
|-
| DEP-03
| PostgreSQL running on localhost:5432
| Dependency
|-
| DEP-08
| Prime 2 seeded before first generation
| Dependency
|}


-----

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

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


-----

<span id="functional-requirements"></span>
== 4. Functional Requirements ==

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

* The system shall accept a <code>generate</code> command-line argument to trigger prime-number generation.
* The system shall test every odd integer from 3 upward for primality using trial division.
* The system shall store each confirmed prime in the database in ascending order of discovery.
* Generation shall continue until the candidate number reaches 999,999,999.

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

* For each candidate number N, the system shall divide N by each known prime p where p ≤ √N.
* If any p divides N exactly (remainder = 0), N is composite and shall not be stored.
* If no p ≤ √N divides N, N is prime and shall be persisted.

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

* The system shall accept a <code>report</code> command-line argument to trigger report generation.
* The system shall read all stored primes from the database in sequence order.
* The system shall write a paginated, formatted print file containing all primes.

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

* The report shall contain a page heading (“primes overview”) and column headers on each page.
* Each data line shall display six prime entries side by side: sequence number and prime value.
* Each page shall carry a page-number footing.
* The print record width shall be 132 characters.
* The report shall be written to a file named <code>primes.prt</code>.

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

* The system shall write progress and status messages to the system console throughout execution.
* Each message shall identify the issuing program name and paragraph.

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

* The system shall log an error message and stop cleanly if an unrecognised command-line argument is provided.
* The system shall log an error message and stop cleanly if the print file cannot be opened.
* The system shall log database connection or cursor failures and set an error indicator before exiting.


-----

<span id="non-functional-requirements"></span>
== 5. Non-Functional Requirements ==

Summary only — see PGCBL-NFR-001 for full specification.

{|
!width="33%"| ID
!width="33%"| Category
!width="33%"| Requirement
|-
| NFR-PERF-01
| Performance
| ≥ 1,000 primes generated per second
|-
| NFR-REL-01
| Reliability
| Batch runs to completion without manual intervention
|-
| NFR-SEC-01
| Security
| No credentials in compiled binary
|-
| NFR-MAIN-01
| Maintainability
| SQL only in <code>primes.cbl</code>; file I/O only in <code>primesui.cbl</code>
|-
| NFR-OPER-02
| Operability
| Non-zero process return code on failure
|}


-----

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

{|
! ID
! Constraint
|-
| C-01
| Must run on Linux with GnuCOBOL 4.0
|-
| C-02
| Must use PostgreSQL as the database
|-
| C-03
| Upper generation limit: 999,999,999 (hard-coded)
|-
| C-04
| Single-user batch execution only
|}


-----

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

* Interactive or web-based user interfaces.
* Concurrent or distributed execution.
* Generation of prime numbers by any algorithm other than trial division.
* Any prime number below 2 or above 999,999,999.
* Checkpoint/restart capability for interrupted generation runs.


-----

<span id="related-documents-1"></span>
== 8. Related Documents ==

As listed in §1.5.


-----

<span id="open-issues"></span>
== 9. Open Issues ==

{|
!width="18%"| ID
!width="18%"| Issue
!width="18%"| Owner
!width="21%"| Target
!width="21%"| Status
|-
| OI-01
| FR-01: generate loop is commented out in current source — this is defect D-01. FR-01 is not fully met by the current code.
| Developer
| —
| Open
|-
| OI-02
| FR-06: the process does not return a non-zero exit code on error (NFR-OPER-02 gap).
| Developer
| —
| Open
|}
<hr/>
Terug naar: [[Design standards]] | [[Cobol and PostgreSQL]]