Architecture decision records

Architecture Decision Records

Field	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

Version	Date	Author	Status	Change Summary
0.1	2026-03-17	—	Draft	All ADRs inferred from source

---

Table of Contents

1. Purpose and Format
2. ADR-001 — Three-Tier Architecture
3. ADR-002 — Method-Dispatch Pattern
4. ADR-003 — Divisors Stored in Database
5. ADR-004 — GixSQL as SQL Pre-Processor
6. ADR-005 — Copybooks as Interface Contracts
7. ADR-006 — Hard-Coded Database Credentials
8. ADR-007 — No Explicit COMMIT on INSERT
9. ADR-008 — Odd-Only Sieve Starting at 3
10. 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 https://adr.github.io/madr/).

ADR template

## 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.>

---

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

Option	Description	Pros	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 (primesmain) manages the session lifecycle.

Consequences

Positive: - SQL is isolated in primes.cbl; database changes do not affect other programs. - Print formatting is isolated in primesui.cbl; 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

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

---

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 CALL 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

Option	Description	Pros	Cons
A	Separate CALL per operation (CALL "primes-connect", CALL "primes-fetch" …)	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 (dal-methods, ui-methods, methods) drives an EVALUATE TRUE 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 WHEN 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 WHEN OTHER 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 dal-methods / ui-methods / methods 88-level must have a corresponding WHEN 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

Option	Description	Pros	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 primes 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 SELECT prime WHERE ident = :n query. Without an index on ident, 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 ident is defined in primes_schema.sql (see NFR-PERF-03). This is the most significant performance risk in the system.

Compliance check

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

---

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 pgsql://]

Context

GnuCOBOL does not natively support embedded SQL. An external pre-processor is needed to translate EXEC SQL … END-EXEC 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

Option	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 GIXSQLExec, GIXSQLConnect, GIXSQLConnectReset calls. Connection string prefix pgsql:// is GixSQL-specific.

Consequences

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

Negative / trade-offs: - GixSQL-specific connection string prefix (pgsql://) 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 CALL "GIXSQLExec" statements appear in handwritten source (only in generated .out 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 (primes-session.cpy, primes-dal.cpy, primes-ui.cpy) 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 (primes-table.cpy vs primes_table.cpy) — the canonical version must be designated and the other retired.

Compliance check

grep -r "COPY primes-dal" *.cbl — should list only primesgen.cbl (caller) and primes.cbl (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 primes.cbl 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 primes.cbl as a pragmatic choice for a demonstration application.

⚠ 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.

Recommended remediation

Replace DBUSR and DBPWD 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 primes.cbl r83-write-prime]

Context

The INSERT in r83-write-prime 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.

⚠ Note: The report path opens an explicit transaction (START TRANSACTION) via s01-cursor. 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.

Consequences

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

Risks: - If a transaction is ever opened on the primes connection before r83-write-prime, 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 test-number is initialised to 3 (odd) and that only ADD 2 TO test-number (never ADD 1) advances the candidate in r82-next-test-number.

---

10. Open Issues

ID	Issue	Owner	Target	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

---

Terug naar: Design standards | Cobol and PostgreSQL