Primes system Design

The Primes system was written on top of my head, aimed at creating a consistent three tier object oriented set of Cobol programs using a PostgreSQL backend. It does not serve any purpose, storing prime numbers in a database actually is a bad idea.

pgcobol — Documentation Wiki

System: pgcobol — Three-Tier COBOL / PostgreSQL Prime Numbers Application

Version: 1.0 · Reverse-engineered baseline · 2026-03-17
Runtime: GnuCOBOL 4.0 · GixSQL · PostgreSQL 11 · Linux

---

Quick Navigation

	Page	What you will find
Primes system Design	This page — overview, architecture snapshot, quick-start
Business Requirements	What the system must do; stakeholders; constraints
⚙	Technical Specification	Stack; architecture; pseudocode for all four programs; SQL inventory; file spec; defect register
Data Dictionary	Every field in every copybook and working-storage section
Flow Diagrams	Eight Mermaid diagrams — call graphs, sieve loop, report loop, sequence diagrams

---

System Overview

pgcobol is a batch COBOL application that generates prime numbers by trial division, stores them in a PostgreSQL database, and produces a formatted line-printer report. It demonstrates a clean three-tier architecture entirely within COBOL.

  ┌──────────────────────────────────────────────┐
  │              primesmain                      │  Orchestrator
  │  Reads command-line arg → routes to tier     │  primesmain.cbl
  └───────────────────┬──────────────────────────┘
                      │ CALL using primes-session
          ┌───────────▼──────────────┐
          │        primesgen         │  Business Logic / Sieve Engine
          │  Sieve algorithm or      │  primesgen.cbl
          │  cursor read-loop        │
          └────────┬─────────────────┘
    CALL primes-dal│        │CALL primes-ui
       ┌───────────▼──┐  ┌──▼──────────────┐
       │    primes    │  │   primesui       │  Presentation
       │  DAL + SQL   │  │  Print file +    │  primesui.cbl
       │  primes.cbl  │  │  console log     │
       └──────┬───────┘  └──────────────────┘
              │ EXEC SQL via GixSQL
       ┌──────▼───────────────┐
       │     PostgreSQL 11    │
       │   schema: primes     │
       │   table:  primes     │
       └──────────────────────┘

---

Two Operational Modes

Argument	What happens
generate	primesgen runs the sieve from 3 → 999,999,999; each confirmed prime is inserted into the database
report	primesgen opens a cursor over the primes table; each row is written into the formatted print file primes.prt

⚠ Known defect: The generate path exists in the code but the PERFORM that invokes the sieve loop is commented out in primesmain.cbl (line 51). See Technical Specification — Defect Register.

---

Source File Inventory

File	Type	Role
primesmain.cbl	COBOL program	Entry point — session controller
primesgen.cbl	COBOL program	Business logic — sieve and report loops
primes.cbl	COBOL + GixSQL	Data access layer — all SQL
primesui.cbl	COBOL program	Presentation — print file and console
primes-session.cpy	Copybook	Session-tier control block
primes-dal.cpy	Copybook	DAL-tier control block
primes-ui.cpy	Copybook	UI-tier control block (all programs)
primes-table.cpy	Copybook	SQL host variable — character format
primes_table.cpy	Copybook	SQL host variable — COMP-3 format (duplicate — see Data Dictionary)
SQLCA.cpy	Copybook	GixSQL SQL Communications Area
primes_schema.sql	DDL	Creates schema, sequence, and table
reset-primes.sql	DDL	Drops and recreates schema for a fresh run
primes_cbsql.out	Listing	GixSQL pre-compiler expanded output

---

Inter-Tier Communication Pattern

All programs communicate through method-dispatch control blocks defined in copybooks. The pattern is the same at every tier:

1. Caller MOVEs a verb string into the control block's methods field
2. Caller CALLs the subprogram, passing the control block BY REFERENCE
3. Subprogram EVALUATEs the verb, executes the matching paragraph
4. Subprogram sets a numeric result code before EXIT PROGRAM
5. Caller inspects the result field and branches accordingly

Tier boundary	Control block	Result codes
primesmain → primesgen	primes-session	0 = ok · 1 = nok · 9 = eof
primesgen → primes	primes-dal	0 = ok · 1 = nok · 99 = eof
any → primesui	primes-ui	0 = ok · 1 = nok

---

Document Revision

Page	Document ID	Last updated
Business Requirements	PGCBL-BRD-001	2026-03-17
Technical Specification	PGCBL-TSD-001	2026-03-17
Data Dictionary	PGCBL-DDD-001	2026-03-17
Flow Diagrams	PGCBL-FLD-001	2026-03-17

---

All pages derived by reverse engineering of source artifacts. Items marked ⚠ indicate known defects or unconfirmed assumptions.