PrimesSQL Design

pgcobol Wiki

> **pgcobol** — Three-tier GnuCOBOL / PostgreSQL prime-numbers application · v1.0 · reverse-engineered 2026-03-17

---

1. What is pgcobol?

pgcobol is a batch COBOL application that demonstrates a clean three-tier architecture on Linux. It generates prime numbers by trial division, persists each prime in a PostgreSQL database, and produces a paginated printed report of all stored primes. There is no interactive interface; everything is driven from a single command-line argument.

``` primesmain generate → primesgen → primes (DAL) → PostgreSQL primesmain report → primesgen → primes (DAL) → primesui → primes.prt ```

---

1. Quick Start

| Goal | Command | |---|---| | Generate primes | `./primesmain generate` | | Produce report | `./primesmain report` | | Reset database | `psql -f reset-primes.sql` |

- Prerequisites:** GnuCOBOL 4.0, GixSQL pre-processor, PostgreSQL 11+, schema initialised with `primes_schema.sql`, prime 2 manually inserted.

> ⚠ **Known issue:** The generate loop is commented out in `primesmain.cbl` line 51. Generation mode does not execute the sieve in the current source. See [Technical Specification › Known Issues](design/technical-spec.md#7-known-technical-issues).

---

1. Source Files

| File | Type | Role | |---|---|---| | `primesmain.cbl` | COBOL | Entry point and session orchestrator | | `primesgen.cbl` | COBOL | Business logic — sieve algorithm and report loop | | `primes.cbl` | COBOL + GixSQL | Data access layer — all SQL | | `primesui.cbl` | COBOL | Presentation — print file and console | | `primes-session.cpy` | Copybook | Session-tier interface contract | | `primes-dal.cpy` | Copybook | DAL-tier interface contract | | `primes-ui.cpy` | Copybook | UI-tier interface contract (all programs) | | `primes-table.cpy` | Copybook | SQL host variable — character format | | `primes_table.cpy` | Copybook | SQL host variable — COMP-3 packed (alternate) | | `SQLCA.cpy` | Copybook | GixSQL SQL Communications Area | | `primes_schema.sql` | DDL | Schema, sequence, table definition | | `reset-primes.sql` | DDL | Drop and recreate for a clean test run |

---

1. Design-Level Documentation

These pages describe **what** the system does and how it is structured.

| Page | Contents | |---|---| | [Business Requirements](design/business-requirements.md) | Functional requirements (FR-01–FR-06), non-functional requirements, stakeholders, constraints | | [Technical Specification](design/technical-spec.md) | Architecture diagram, component inventory, full pseudocode for all four programs, database connection parameters, SQL statement inventory, file I/O specification, known defects | | [Data Dictionary](design/data-dictionary.md) | Every field in every copybook and working-storage section — name, level, picture, usage, semantic description, all 88-level conditions; database schema objects | | [Flow Diagrams](design/flow-diagrams.md) | Eight Mermaid diagrams: top-level flow, primesgen dispatch, generate sieve loop, report loop, DAL dispatch, UI dispatch, generate sequence diagram, report sequence diagram |

---

1. Program-Level Documentation

These pages describe **how** each program works internally.

> 🔧 *Program-level pages are listed here for completeness. Contents are defined in the program-level specification set.*

| Page | Contents | |---|---| | Program Logic | Step-by-step paragraph logic for all four programs | | Business Rules | Primality algorithm rules, validation, formatting rules, error-handling conventions | | I/O Behaviour | File handling, console output, database call patterns | | Control Flow | PERFORM/CALL/EVALUATE trees, loop structure, paragraph maps |

---

1. Architecture at a Glance

``` ┌───────────────────────────────────────────┐ │ primesmain │ Orchestrator │ Reads arg → dispatches → shuts down │ └──────────────────┬────────────────────────┘

                  │  CALL using primes-session
       ┌──────────▼──────────┐
       │      primesgen      │  Business Logic
       │  sieve / report     │
       └───┬─────────────────┘
           │ primes-dal          │ primes-ui
  ┌────────▼──────┐    ┌────────▼──────────┐
  │    primes     │    │    primesui        │  Presentation
  │  (DAL / SQL)  │    │  primes.prt        │
  └───────┬───────┘    └────────────────────┘
          │
  ┌───────▼───────┐
  │  PostgreSQL   │
  │  primes.primes│
  └───────────────┘

```

All inter-program communication uses **method-dispatch**: the caller moves a verb string into a control-block field, calls the subprogram, and reads a numeric result code on return. The control blocks are defined in copybooks (`primes-session.cpy`, `primes-dal.cpy`, `primes-ui.cpy`) which serve as the published interface contracts between tiers.

---

1. Result Code Convention

Used consistently across all three control blocks:

| Code | Meaning | |---|---| | `0` | Success | | `1` | Error / failure | | `9` | End of data (session tier) | | `99` | End of data (DAL tier) |

---

1. Open Issues

| ID | Severity | Description | See | |---|---|---|---| | T1 | High | Generate loop commented out — generation does not run | [Tech Spec §7](design/technical-spec.md#7-known-technical-issues) | | T2 | High | Connection alias mismatch (`primes` vs `primesdb`) | [Tech Spec §7](design/technical-spec.md#7-known-technical-issues) | | T3 | Medium | COMMIT on INSERT is commented out | [Tech Spec §7](design/technical-spec.md#7-known-technical-issues) | | T4 | Medium | Prime 2 not seeded before sieve starts | [Business Requirements §5](design/business-requirements.md#5-assumptions-and-constraints) | | T5 | Low | Database credentials hard-coded in source | [Data Dictionary §2.3](design/data-dictionary.md#23-primes-dal) | | T6 | Low | Two near-duplicate host-variable copybooks | [Data Dictionary §1.4](design/data-dictionary.md#14-primes-table--sql-host-variable-character) |

---

Last updated: 2026-03-17 · Source: reverse-engineered from pgcobol v1.0 artifacts*

PrimesSQL Design

Navigation menu

Search