PrimesSQL Design
- pgcobol Wiki
> **pgcobol** — Three-tier GnuCOBOL / PostgreSQL prime-numbers application · v1.0 · reverse-engineered 2026-03-17
---
- 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 ```
---
- 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).
---
- 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 |
---
- 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 |
---
- 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 |
---
- 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.
---
- 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) |
---
- 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*