Martin: Created page with " = Architecture Decision Records = {| !width="23%"| Field !width="76%"| Value |- | Document ID | PGCBL-ADD-001 |- | Document Type | Architecture Decision Document |- | System | pgcobol — Prime Numbers Application v1.0 |- | Version | 1.0 |- | Status | Draft — decisions marked [INFERRED] need developer confirmation |- | Owner | Lead Developer / Architect |- | Author | [reverse-engineered from source artifacts] |- | Creat..."

2026-03-25T15:34:59Z

Created page with " = Architecture Decision Records = {| !width="23%"| Field !width="76%"| Value |- | Document ID | PGCBL-ADD-001 |- | Document Type | Architecture Decision Document |- | System | pgcobol — Prime Numbers Application v1.0 |- | Version | 1.0 |- | Status | Draft — decisions marked [INFERRED] need developer confirmation |- | Owner | Lead Developer / Architect |- | Author | [reverse-engineered from source artifacts] |- | Creat..."

New page

= Architecture Decision Records =

{|
!width="23%"| Field
!width="76%"| Value
|-
| Document ID
| PGCBL-ADD-001
|-
| Document Type
| Architecture Decision Document
|-
| System
| pgcobol — Prime Numbers Application v1.0
|-
| Version
| 1.0
|-
| Status
| Draft — decisions marked [INFERRED] need developer confirmation
|-
| Owner
| Lead Developer / Architect
|-
| Author
| [reverse-engineered from source artifacts]
|-
| Created
| 2026-03-17
|-
| Last modified
| 2026-03-17
|-
| Classification
| Internal
|-
| Parent document
| PGCBL-TSD-001
|}


== Version History ==

{|
!width="16%"| Version
!width="22%"| Date
!width="15%"| Author
!width="15%"| Status
!width="30%"| Change Summary
|-
| 0.1
| 2026-03-17
| —
| Draft
| All ADRs inferred from source
|}

-----


== Table of Contents ==

# [[#1-purpose-and-format|Purpose and Format]]
# [[#2-adr-001--three-tier-architecture|ADR-001 — Three-Tier Architecture]]
# [[#3-adr-002--method-dispatch-pattern|ADR-002 — Method-Dispatch Pattern]]
# [[#4-adr-003--divisors-stored-in-database|ADR-003 — Divisors Stored in Database]]
# [[#5-adr-004--gixsql-as-sql-pre-processor|ADR-004 — GixSQL as SQL Pre-Processor]]
# [[#6-adr-005--copybooks-as-interface-contracts|ADR-005 — Copybooks as Interface Contracts]]
# [[#7-adr-006--hard-coded-database-credentials|ADR-006 — Hard-Coded Database Credentials]]
# [[#8-adr-007--no-explicit-commit-on-insert|ADR-007 — No Explicit COMMIT on INSERT]]
# [[#9-adr-008--odd-only-sieve-starting-at-3|ADR-008 — Odd-Only Sieve Starting at 3]]
# [[#10-open-issues|Open Issues]]

-----


== 1. Purpose and Format ==

An Architecture Decision Record (ADR) captures a single significant design decision: the context that prompted it, the options that were considered, the choice that was made, and the consequences. ADRs are written once and never deleted — if a decision is reversed, a new ADR documents the reversal and links to the original.

This document follows the '''MADR (Markdown Architectural Decision Records)''' format, a widely adopted lightweight standard (see <code>https://adr.github.io/madr/</code>).


=== ADR template ===

<pre class="markdown">## N. ADR-NNN — <Short title of the decision>

**Date:** YYYY-MM-DD
**Status:** Proposed | Accepted | Deprecated | Superseded by ADR-NNN
**Deciders:** <names or roles>
**Source:** [CONFIRMED] | [INFERRED from source] | [ASSUMED]

### Context

<What situation or problem prompted this decision? What forces are at play?>

### Decision Drivers

- <driver 1>
- <driver 2>

### Options Considered

| Option | Description | Pros | Cons |
|--------|-------------|------|------|
| A | ... | ... | ... |
| B | ... | ... | ... |

### Decision

<The option chosen and a one-line justification.>

### Consequences

**Positive:**
- <benefit 1>

**Negative / trade-offs:**
- <drawback 1>

**Risks:**
- <risk 1>

### Compliance check

<How to verify this decision is being followed in the codebase.></pre>

-----


== 2. ADR-001 — Three-Tier Architecture ==

'''Date:''' 2025 (inferred) 
'''Status:''' Accepted 
'''Deciders:''' Original developer 
'''Source:''' [INFERRED from source structure]


=== Context ===

A batch COBOL program could be written as a single monolithic program with all logic, SQL, and output in one place. This project chose to separate concerns into distinct compiled units.


=== Decision Drivers ===

* Demonstrate a maintainable, layered COBOL design pattern.
* Allow each tier to be tested, replaced, or modified independently.
* Keep SQL in one place so that database changes affect only one program.


=== Options Considered ===

{|
!width="24%"| Option
!width="39%"| Description
!width="18%"| Pros
!width="18%"| Cons
|-
| A
| Single monolithic program
| Simple; one file to manage
| Hard to test; all concerns coupled
|-
| B
| Three-tier (chosen)
| Separation of concerns; independently testable tiers
| More files; inter-program calling overhead
|-
| C
| Two-tier (no UI layer)
| Simpler than three
| Print formatting coupled to business logic
|}


=== Decision ===

Option B — three-tier (presentation / business logic / data access), each as a separate compiled COBOL program. A fourth orchestrating program (<code>primesmain</code>) manages the session lifecycle.


=== Consequences ===

'''Positive:''' - SQL is isolated in <code>primes.cbl</code>; database changes do not affect other programs. - Print formatting is isolated in <code>primesui.cbl</code>; output format changes do not affect logic. - Each program can be called from a test harness independently.

'''Negative / trade-offs:''' - Four programs must be compiled and linked instead of one. - Inter-program calls carry a small runtime overhead. - A shared copybook change requires recompiling all programs that use it.


=== Compliance check ===

<code>grep -l "EXEC SQL" *.cbl</code> should return only <code>primes.cbl</code>. 
<code>grep -l "OPEN.*fprinter\|WRITE.*file-buffer" *.cbl</code> should return only <code>primesui.cbl</code>.

-----


== 3. ADR-002 — Method-Dispatch Pattern ==

'''Date:''' 2025 (inferred) 
'''Status:''' Accepted 
'''Deciders:''' Original developer 
'''Source:''' [INFERRED from copybook design]


=== Context ===

COBOL does not have objects, interfaces, or function pointers in the traditional sense. When a caller invokes a subprogram, it can either call different entry points (ENTRY paragraphs) or pass a discriminator value and let the callee dispatch internally. The design must allow each subprogram to expose multiple operations without multiple entry points.


=== Decision Drivers ===

* Keep the inter-tier interface to a single <code>CALL</code> statement per tier.
* Allow new operations to be added to a tier without changing the caller’s CALL syntax.
* Use a pattern that is idiomatic in COBOL and familiar to COBOL programmers.


=== Options Considered ===

{|
!width="24%"| Option
!width="39%"| Description
!width="18%"| Pros
!width="18%"| Cons
|-
| A
| Separate CALL per operation (<code>CALL "primes-connect"</code>, <code>CALL "primes-fetch"</code> …)
| Explicit; no dispatch overhead
| Many CALL statements; callers must know all entry names
|-
| B
| ENTRY paragraph per operation (single program, multiple named entries)
| Standard COBOL; compiler-enforced
| Callers must still reference entry names; no single interface point
|-
| C
| Method-dispatch over a control block (chosen)
| Single CALL; extensible; copybook is the interface contract
| Verb strings must be kept in sync between copybooks and EVALUATE
|}


=== Decision ===

Option C — a string verb in a copybook field (<code>dal-methods</code>, <code>ui-methods</code>, <code>methods</code>) drives an <code>EVALUATE TRUE</code> inside the called program. The copybook is the published interface; the 88-level conditions make the valid verbs self-documenting.


=== Consequences ===

'''Positive:''' - Adding a new operation requires only: a new 88-level condition in the copybook and a new <code>WHEN</code> clause in the callee. - The caller’s CALL statement never changes. - The copybook 88-levels serve as the API documentation.

'''Negative / trade-offs:''' - Verb strings are not type-checked at compile time; a misspelled verb silently falls through to the <code>WHEN OTHER</code> error branch. - Result codes (0/1/9/99) are numeric constants, not named conditions at the caller site — callers must remember the convention.

'''Risks:''' - Verb string drift: if a verb is renamed in the copybook but not in the callee’s EVALUATE, the operation silently does nothing and returns result 1.


=== Compliance check ===

Every verb listed in a <code>dal-methods</code> / <code>ui-methods</code> / <code>methods</code> 88-level must have a corresponding <code>WHEN</code> clause in the callee’s EVALUATE. Verify with a diff of copybook 88-values against callee WHEN values.

-----


== 4. ADR-003 — Divisors Stored in Database ==

'''Date:''' 2025 (inferred) 
'''Status:''' Accepted 
'''Deciders:''' Original developer 
'''Source:''' [INFERRED from algorithm and SQL design]


=== Context ===

The trial-division sieve needs a list of previously found primes to use as divisors. These could be held in a COBOL working-storage table (an array), in a flat file, or in the database.


=== Decision Drivers ===

* Demonstrate database interaction as part of the algorithm (pedagogical goal).
* Keep the COBOL working-storage footprint small — avoid a large in-memory prime array.
* Persist divisors so the report can run independently of the generation run.


=== Options Considered ===

{|
!width="24%"| Option
!width="39%"| Description
!width="18%"| Pros
!width="18%"| Cons
|-
| A
| In-memory COBOL table
| Fastest; no I/O
| Fixed size; lost between runs; defeats the DB demonstration goal
|-
| B
| Flat file
| Persistent; simple
| Requires file I/O; not the DB demonstration goal
|-
| C
| Database (chosen)
| Persistent; demonstrates DB use; divisors and output in same store
| One SQL query per trial division step — potentially very slow
|}


=== Decision ===

Option C — each divisor is fetched from the <code>primes</code> table by ident using a point SELECT. Generated primes accumulate in the same table as the divisors.


=== Consequences ===

'''Positive:''' - Demonstrates the full three-tier pattern end-to-end. - All state is in the database; generation can be interrupted and (in principle) resumed.

'''Negative / trade-offs:''' - Performance is heavily dependent on the <code>SELECT prime WHERE ident = :n</code> query. Without an index on <code>ident</code>, this becomes a sequential scan that gets slower as the table grows. - The design requires prime 2 to be pre-seeded in the table before the algorithm starts, since the first divider fetch assumes ident=2 exists.

'''Risks:''' - No index on <code>ident</code> is defined in <code>primes_schema.sql</code> (see NFR-PERF-03). This is the most significant performance risk in the system.


=== Compliance check ===

Run <code>\d primes.primes</code> in psql; verify an index on <code>ident</code> is present. If absent, add: <code>CREATE INDEX idx_primes_ident ON primes.primes (ident);</code>

-----


== 5. ADR-004 — GixSQL as SQL Pre-Processor ==

'''Date:''' 2025 (inferred) 
'''Status:''' Accepted 
'''Deciders:''' Original developer 
'''Source:''' [CONFIRMED — explicit in compiler listing header and DATASRC prefix <code>pgsql://</code>]


=== Context ===

GnuCOBOL does not natively support embedded SQL. An external pre-processor is needed to translate <code>EXEC SQL … END-EXEC</code> blocks into COBOL CALL statements to a SQL runtime library.


=== Decision Drivers ===

* Open-source toolchain (no licensing cost).
* PostgreSQL support.
* Compatible with GnuCOBOL.


=== Options Considered ===

{|
!width="38%"| Option
!width="61%"| Description
|-
| ESQL/C bridge
| Write SQL in C, call from COBOL — complex
|-
| OCESQL
| Another open-source COBOL SQL pre-processor — less PostgreSQL-specific
|-
| GixSQL (chosen)
| Open-source; PostgreSQL-optimised; active development
|}


=== Decision ===

GixSQL — translates EXEC SQL to <code>GIXSQLExec</code>, <code>GIXSQLConnect</code>, <code>GIXSQLConnectReset</code> calls. Connection string prefix <code>pgsql://</code> is GixSQL-specific.


=== Consequences ===

'''Positive:''' - Standard embedded SQL syntax in COBOL source. - PostgreSQL-native driver.

'''Negative / trade-offs:''' - GixSQL-specific connection string prefix (<code>pgsql://</code>) and runtime library are not portable to other COBOL SQL pre-processors. - GixSQL is not part of the GnuCOBOL distribution; must be installed separately.


=== Compliance check ===

All SQL pre-processing must be done through GixSQL. Verify no raw <code>CALL "GIXSQLExec"</code> statements appear in handwritten source (only in generated <code>.out</code> files).

-----


== 6. ADR-005 — Copybooks as Interface Contracts ==

'''Date:''' 2025 (inferred) 
'''Status:''' Accepted 
'''Deciders:''' Original developer 
'''Source:''' [INFERRED from copybook design]


=== Context ===

In a multi-program COBOL system, data shared between programs can be defined redundantly in each program’s WORKING-STORAGE, or defined once in a copybook included by all parties.


=== Decision ===

Define each tier’s control block once in a copybook (<code>primes-session.cpy</code>, <code>primes-dal.cpy</code>, <code>primes-ui.cpy</code>) and COPY it into both the caller’s WORKING-STORAGE and the callee’s LINKAGE SECTION. The copybook is the published interface; changing it is a breaking change affecting all users.


=== Consequences ===

'''Positive:''' - Single source of truth for each interface. - Field layout guaranteed to match between caller and callee.

'''Negative / trade-offs:''' - Any field size change in a copybook requires recompiling every program that includes it. - Two nearly-identical host-variable copybooks exist (<code>primes-table.cpy</code> vs <code>primes_table.cpy</code>) — the canonical version must be designated and the other retired.


=== Compliance check ===

<code>grep -r "COPY primes-dal" *.cbl</code> — should list only <code>primesgen.cbl</code> (caller) and <code>primes.cbl</code> (callee).

-----


== 7. ADR-006 — Hard-Coded Database Credentials ==

'''Date:''' 2025 (inferred) 
'''Status:''' Accepted (as technical debt — see note) 
'''Deciders:''' Original developer 
'''Source:''' [CONFIRMED — visible in <code>primes.cbl</code> lines 14–17]


=== Context ===

Database credentials must be provided to the GixSQL CONNECT call. Options include hard-coding, environment variables, a configuration file, or a secrets manager.


=== Decision ===

Credentials are hard-coded in WORKING-STORAGE of <code>primes.cbl</code> as a pragmatic choice for a demonstration application.

<blockquote>⚠ '''Technical debt note:''' This decision is explicitly acknowledged as a security defect (NFR-SEC-01). It is documented here so that the decision is visible and the remediation can be tracked. It must not be carried forward to a production deployment.
</blockquote>

=== Recommended remediation ===

Replace <code>DBUSR</code> and <code>DBPWD</code> VALUE clauses with:

<syntaxhighlight lang="cobol">ACCEPT DBUSR FROM ENVIRONMENT "PRIMES_DB_USER"
ACCEPT DBPWD FROM ENVIRONMENT "PRIMES_DB_PASS"</syntaxhighlight>
Or read from a protected configuration file at startup.


=== Consequences ===

'''Negative:''' - Credential rotation requires recompilation and redeployment. - Credentials are visible in the binary and in any version-control history. - Violates NFR-SEC-01 and OWASP Secure Coding Practice #3.

-----


== 8. ADR-007 — No Explicit COMMIT on INSERT ==

'''Date:''' 2025 (inferred) 
'''Status:''' Accepted (status uncertain — see note) 
'''Deciders:''' Original developer 
'''Source:''' [INFERRED — COMMIT statement is commented out in <code>primes.cbl</code> r83-write-prime]


=== Context ===

The INSERT in <code>r83-write-prime</code> does not issue an explicit COMMIT. The commented-out COMMIT suggests this was a deliberate choice or a deferred decision.


=== Decision ===

Rely on PostgreSQL’s default auto-commit behaviour for individual INSERT statements outside an explicit transaction. The COMMIT is not needed because each INSERT auto-commits.

<blockquote>⚠ '''Note:''' The report path opens an explicit transaction (<code>START TRANSACTION</code>) via <code>s01-cursor</code>. If the generate path is ever run while a transaction is open (e.g. if the session management is changed), the INSERTs will not auto-commit. This is a latent risk.
</blockquote>

=== Consequences ===

'''Positive:''' - Simpler code; no COMMIT overhead per row.

'''Risks:''' - If a transaction is ever opened on the <code>primes</code> connection before <code>r83-write-prime</code>, the INSERTs will not be committed until an explicit COMMIT or ROLLBACK, and data will be lost on failure.

-----


== 9. ADR-008 — Odd-Only Sieve Starting at 3 ==

'''Date:''' 2025 (inferred) 
'''Status:''' Accepted 
'''Deciders:''' Original developer 
'''Source:''' [CONFIRMED — ADD 2 TO test-number in r82-next-test-number; initial value 3]


=== Context ===

The sieve must test whether each integer is prime. Testing every integer (2, 3, 4, 5 …) is correct but wasteful: all even numbers greater than 2 are composite and need not be tested.


=== Decision ===

Start the candidate at 3 and advance by 2 (ADD 2 TO test-number), testing only odd integers. Prime 2 is handled as a manual seed rather than by the algorithm.


=== Consequences ===

'''Positive:''' - Roughly halves the number of candidates that must be tested, improving performance.

'''Negative / trade-offs:''' - Prime 2 must be manually seeded in the database before the algorithm runs (see Assumption A-01). This is an external dependency on an operational step, not a code-enforced constraint.


=== Compliance check ===

Verify <code>test-number</code> is initialised to 3 (odd) and that only <code>ADD 2 TO test-number</code> (never ADD 1) advances the candidate in <code>r82-next-test-number</code>.

-----


== 10. Open Issues ==

{|
!width="18%"| ID
!width="18%"| Issue
!width="18%"| Owner
!width="21%"| Target
!width="21%"| Status
|-
| OI-01
| All ADRs marked [INFERRED] need confirmation from original developer
| Lead Dev
| —
| Open
|-
| OI-02
| ADR-006 remediation (credentials) has no target date
| Lead Dev
| —
| Open
|-
| OI-03
| ADR-007 (no COMMIT) — confirm the intent is auto-commit, not an oversight
| Lead Dev
| —
| Open
|-
| OI-04
| Duplicate copybooks (ADR-005) — designate canonical version and retire the other
| Developer
| —
| Open
|}
<hr/>
Terug naar: [[Design standards]] | [[Cobol and PostgreSQL]]

Architecture decision records - Revision history