Editing 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*