Non-Functional Requirements

Non-Functional Requirements

Field	Value
Document ID	PGCBL-NFR-001
Document Type	Non-Functional Requirements
System	pgcobol — Prime Numbers Application v1.0
Version	1.0
Status	Draft — performance and security targets require stakeholder input
Owner	Lead Developer / Architect
Author	[reverse-engineered; targets are best-practice defaults where not specified in source]
Created	2026-03-17
Last modified	2026-03-17
Classification	Internal
Parent document	PGCBL-BRD-001

Version History

Version	Date	Author	Status	Change Summary
0.1	2026-03-17	—	Draft	Initial draft from source analysis and best-practice defaults

---

Table of Contents

1. Purpose and Taxonomy
2. Performance
3. Reliability and Availability
4. Security
5. Maintainability
6. Portability and Compatibility
7. Operability
8. Auditability and Compliance
9. Recoverability
10. Open Issues

---

1. Purpose and Taxonomy

Non-functional requirements (NFRs) specify how well the system must do things, as opposed to what it must do (functional requirements). They are the quality attributes of the system.

This document uses the ISO/IEC 25010:2011 (SQuaRE) quality model as its taxonomy. Each NFR is assigned a category from that model:

ISO 25010 Category	Subcategories
Performance efficiency	Time behaviour, resource utilisation, capacity
Reliability	Maturity, availability, fault tolerance, recoverability
Security	Confidentiality, integrity, non-repudiation, accountability, authenticity
Maintainability	Modularity, reusability, analysability, modifiability, testability
Portability	Adaptability, installability, replaceability
Operability	Appropriateness recognisability, learnability, user error protection
Compatibility	Co-existence, interoperability

Each NFR entry follows this format:

NFR-<category>-<NN>
  Requirement:   <measurable statement of what is required>
  Rationale:     <why this matters>
  Test approach: <how it will be verified>
  Priority:      Must Have | Should Have | Nice to Have
  Source:        <observed in code / stakeholder input / best-practice default>
  Status:        [CONFIRMED] | [UNCONFIRMED — needs stakeholder sign-off]

---

2. Performance

NFR-PERF-01 — Generation throughput

Requirement: The system should generate and insert at least 1,000 primes per second under normal operating conditions (single-user, unloaded PostgreSQL on localhost).
Rationale: There are approximately 50 million primes below 10^9. Without a throughput target the system may be functionally correct but practically unusable.
Test approach: Time a generation run of the first 10,000 primes; divide by elapsed seconds.
Priority: Should Have
Source: Best-practice default [UNCONFIRMED — no target specified in source]
Status: Open — target must be agreed with the system owner.

NFR-PERF-02 — Report generation time

Requirement: A report covering up to 1 million stored primes should complete within 5 minutes.
Rationale: A batch report that runs overnight is operationally acceptable; one that runs for days is not.
Test approach: Seed 1,000,000 rows; time a full report run.
Priority: Should Have
Source: Best-practice default [UNCONFIRMED]
Status: Open.

NFR-PERF-03 — Database query response

Requirement: The SELECT prime WHERE ident = :n divider lookup should return in under 50 ms at any point in the generation run.
Rationale: This query is called once per trial division step; if it is slow, the entire sieve is slow.
Test approach: Run EXPLAIN ANALYZE on the query with a populated table; check absence of sequential scan on primes.primes.
Priority: Must Have
Source: Algorithm design analysis
Status: Open — no index on ident is defined in primes_schema.sql; a sequential scan is likely. This is a defect.

---

3. Reliability and Availability

NFR-REL-01 — Batch completion

Requirement: A generation or report run, once started on a healthy system, should complete without manual intervention.
Rationale: Batch jobs that require operator interaction to proceed are unreliable.
Test approach: Run end-to-end generation and report on a healthy environment; observe for any interactive prompts or hangs.
Priority: Must Have
Source: Standard batch computing requirement
Status: [CONFIRMED by design — no interactive prompts in the code]

NFR-REL-02 — Graceful failure

Requirement: On any database error, the system shall log a descriptive message, set an error code, and exit cleanly (closing the database connection and print file) rather than abending.
Rationale: An abend may leave the database connection open or the print file in an inconsistent state.
Test approach: Simulate a database failure mid-run (e.g. kill the PostgreSQL process); verify clean exit and closed resources.
Priority: Must Have
Source: Observed in source; partial — cleanup paragraphs exist but error propagation is incomplete (see PGCBL-IOB-001 D-RPT-01).
Status: Partially met; D-RPT-01 is an open defect.

NFR-REL-03 — Idempotent reset

Requirement: Running reset-primes.sql shall always produce a clean, empty, ready-to-use database state regardless of the prior state of the database.
Rationale: Developers and operators must be able to reset state reliably between test runs.
Test approach: Run the reset script three times consecutively; verify the same clean state each time.
Priority: Must Have
Source: reset-primes.sql uses DROP … CASCADE + CREATE; this is correct.
Status: [CONFIRMED by SQL analysis]

---

4. Security

NFR-SEC-01 — Credential storage

Requirement: Database credentials shall not be stored in plain text within compiled program source code.
Rationale: Credentials in source code are exposed to anyone who can read the binary, the source, or the version-control history.
Test approach: Inspect all .cbl files for hard-coded user names and passwords; verify none are present.
Priority: Must Have
Source: OWASP Secure Coding Practice #3 — Credential Management
Status: NOT MET — DBUSR and DBPWD are hard-coded in primes.cbl WORKING-STORAGE. Remediation: use environment variables or a secrets manager.

NFR-SEC-02 — Principle of least privilege

Requirement: The database user primes_user shall have only the minimum privileges required: INSERT and SELECT on primes.primes, USAGE on primes.asc_ident.
Rationale: If the application account is compromised, the attacker cannot drop tables, access other schemas, or escalate.
Test approach: Review PostgreSQL privilege grants; attempt a DROP TABLE as primes_user and verify it is denied.
Priority: Must Have
Source: CIS PostgreSQL Benchmark, control 6.1
Status: [UNCONFIRMED — not specified in primes_schema.sql; only ownership is set]

NFR-SEC-03 — Output file permissions

Requirement: primes.prt shall be readable only by the operator user and the intended report consumer; it shall not be world-readable.
Rationale: Prime numbers are not sensitive, but the file permissions standard is a good habit and should be enforced as a baseline.
Test approach: Check umask of the running process; verify primes.prt permissions after creation.
Priority: Nice to Have
Source: Best-practice default
Status: [UNCONFIRMED]

---

5. Maintainability

NFR-MAIN-01 — Three-tier separation

Requirement: No SQL shall appear outside primes.cbl. No file I/O (other than console DISPLAY) shall appear outside primesui.cbl.
Rationale: Tier separation is the principal architectural rule of this system; violating it makes changes to one tier affect others.
Test approach: Grep all .cbl files for EXEC SQL and for SELECT/WRITE file statements; verify only the expected programs contain them.
Priority: Must Have
Source: Architecture design principle; observed and partially met (primesgen has an unused FD declaration — minor violation).
Status: Partially met.

NFR-MAIN-02 — Copybook as interface contract

Requirement: Changes to any copybook must be reviewed for impact on all programs that COPY it before the change is applied.
Rationale: Copybooks are shared; a field-size change in a copybook breaks every program that uses it without any compile-time warning in all cases.
Test approach: Impact analysis process; verified by recompiling all programs after any copybook change.
Priority: Must Have
Source: Standard COBOL maintenance practice
Status: [CONFIRMED as a process requirement — no tooling enforcement in place]

NFR-MAIN-03 — Code commentary

Requirement: Every paragraph shall carry a comment line stating its purpose. Every EXEC SQL block shall carry a comment stating what it does and why.
Rationale: Current source has minimal commentary; future maintainers depend on the specification documents, which is insufficient.
Test approach: Code review checklist.
Priority: Should Have
Source: COBOL coding best practice
Status: NOT MET in current source.

NFR-MAIN-04 — Testability

Requirement: Each tier (primesgen, primes, primesui) shall be callable in isolation with a synthetic control block, without requiring the full three-tier stack.
Rationale: Unit testing individual tiers is only possible if they can be called with a test harness.
Test approach: Write a minimal test driver for each program; verify it compiles and runs independently.
Priority: Should Have
Source: Testability principle; the method-dispatch pattern makes this achievable by design.
Status: [UNCONFIRMED — no test harnesses exist]

---

6. Portability and Compatibility

NFR-PORT-01 — COBOL standard compliance

Requirement: Source code shall conform to COBOL 2002 (ISO 1989:2002) where GnuCOBOL extensions are not required, so that migration to a standard-compliant compiler is possible.
Rationale: GnuCOBOL 4.0-early-dev is a pre-release; the team should not depend on behaviours not in the standard.
Test approach: Compile with -std=cobol2002 flag; resolve any warnings.
Priority: Should Have
Source: Best-practice default
Status: [UNCONFIRMED — not tested]

NFR-PORT-02 — PostgreSQL version range

Requirement: The system shall operate correctly against PostgreSQL 11 through 16.
Rationale: PostgreSQL 11 is the minimum observed in the schema dump; operators may use a more recent version.
Test approach: Run integration tests against PostgreSQL 11, 14, and 16.
Priority: Should Have
Source: Best-practice default
Status: [UNCONFIRMED]

---

7. Operability

NFR-OPER-01 — Console log completeness

Requirement: Every significant state transition (session start/stop, DB connect/disconnect, first fetch, last fetch, error) shall produce a console log entry identifying the program name, paragraph, and a human-readable message.
Rationale: Operators diagnosing failures need to reconstruct what happened from the console log alone.
Test approach: Run both modes; verify all defined state transitions produce a log line.
Priority: Must Have
Source: Observed in source; partially met — direct DISPLAY statements in primes.cbl bypass the structured log format.
Status: Partially met.

NFR-OPER-02 — Return code

Requirement: The process shall exit with return code 0 on success and non-zero on failure.
Rationale: Job schedulers and shell scripts depend on process exit codes to detect failures.
Test approach: Run with a bad argument; check $? in the shell.
Priority: Must Have
Source: POSIX convention
Status: NOT MET — STOP RUN in GnuCOBOL returns 0 regardless of the path taken unless MOVE n TO RETURN-CODE is used; not present in current source.

---

8. Auditability and Compliance

NFR-AUD-01 — Run log retention

Requirement: Console output from each run should be captured and retained for at least 30 days.
Rationale: Enables post-hoc investigation of incorrect results or failures.
Test approach: Verify a shell wrapper redirects stdout/stderr to a dated log file.
Priority: Should Have
Source: Best-practice default
Status: [UNCONFIRMED — no wrapper script exists]

NFR-AUD-02 — Schema change control

Requirement: Changes to primes_schema.sql or reset-primes.sql must be version-controlled and reviewed before deployment.
Rationale: Schema changes can destroy data or break the application silently.
Test approach: Verify files are under git; verify a change-review process exists.
Priority: Must Have
Source: Standard DBA practice
Status: [UNCONFIRMED]

---

9. Recoverability

NFR-REC-01 — Clean restart after failure

Requirement: After any failure, it shall be possible to restore the system to a known clean state by running reset-primes.sql and re-running the generation job.
Rationale: Without a clean-restart procedure, a failed run leaves the database in an unknown state.
Test approach: Simulate a mid-run failure; run reset-primes.sql; run a full generation; verify correctness.
Priority: Must Have
Source: reset-primes.sql provides this; it must be documented as the recovery procedure.
Status: Script exists; recovery procedure not yet documented.

NFR-REC-02 — No partial-page print output

Requirement: The report print file shall always end with a complete, flushed page — no partial lines or missing footings.
Rationale: A partial last page is confusing to report consumers.
Test approach: Run a report with a number of primes that does not divide evenly by 6; inspect the last page of primes.prt.
Priority: Must Have
Source: r99-stop-primesui flush loop — implemented.
Status: [CONFIRMED by code analysis]

---

10. Open Issues

ID	Issue	Owner	Target	Status
OI-01	NFR-PERF-01, 02, 03 targets not confirmed by stakeholder	System owner	—	Open
OI-02	NFR-SEC-01 (hard-coded credentials) is a defect; remediation plan needed	Lead Dev	—	Open
OI-03	NFR-OPER-02 (return code) not implemented; affects job scheduler integration	Developer	—	Open
OI-04	NFR-PERF-03: no index on primes.ident; likely sequential scan — performance defect	DBA	—	Open

---

Terug naar: Design standards | Cobol and PostgreSQL