Editing 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.
<!-- _sidebar.md is loaded automatically by most wiki renderers (GitHub Wiki, Docsify, etc.) -->
<span id="pgcobol-documentation-wiki"></span>
= pgcobol — Documentation Wiki =

<blockquote>'''System:''' pgcobol — Three-Tier COBOL / PostgreSQL Prime Numbers Application<br />
'''Version:''' 1.0 · Reverse-engineered baseline · 2026-03-17<br />
'''Runtime:''' GnuCOBOL 4.0 · GixSQL · PostgreSQL 11 · Linux
</blockquote>

-----

<span id="quick-navigation"></span>
== Quick Navigation ==

{|
!width="33%"|
!width="33%"| Page
!width="33%"| What you will find
|-
| 🏠| '''[[Home]]'''
| This page — overview, architecture snapshot, quick-start
|-
| 📋| '''[[Business-Requirements|Business Requirements]]'''
| What the system must do; stakeholders; constraints
|-
| ⚙
| '''[[Technical-Specification|Technical Specification]]'''
| Stack; architecture; pseudocode for all four programs; SQL inventory; file spec; defect register
|-
| 📖| '''[[Data-Dictionary|Data Dictionary]]'''
| Every field in every copybook and working-storage section
|-
| 🔀| '''[[Flow-Diagrams|Flow Diagrams]]'''
| Eight Mermaid diagrams — call graphs, sieve loop, report loop, sequence diagrams
|}


-----

<span id="system-overview"></span>
== 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.

<pre>  ┌──────────────────────────────────────────────┐
  │              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     │
       └──────────────────────┘</pre>

-----

<span id="two-operational-modes"></span>
== Two Operational Modes ==

{|
!width="50%"| Argument
!width="50%"| What happens
|-
| <code>generate</code>
| primesgen runs the sieve from 3 → 999,999,999; each confirmed prime is inserted into the database
|-
| <code>report</code>
| primesgen opens a cursor over the primes table; each row is written into the formatted print file <code>primes.prt</code>
|}

<blockquote>⚠ '''Known defect:''' The <code>generate</code> path exists in the code but the PERFORM that invokes the sieve loop is commented out in <code>primesmain.cbl</code> (line 51). See [[Technical-Specification#7-known-technical-issues|Technical Specification — Defect Register]].
</blockquote>

-----

<span id="source-file-inventory"></span>
== Source File Inventory ==

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


-----

<span id="inter-tier-communication-pattern"></span>
== Inter-Tier Communication Pattern ==

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

<pre>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</pre>
{|
!width="33%"| Tier boundary
!width="33%"| Control block
!width="33%"| Result codes
|-
| primesmain → primesgen
| <code>primes-session</code>
| 0 = ok · 1 = nok · 9 = eof
|-
| primesgen → primes
| <code>primes-dal</code>
| 0 = ok · 1 = nok · 99 = eof
|-
| any → primesui
| <code>primes-ui</code>
| 0 = ok · 1 = nok
|}


-----

<span id="document-revision"></span>
== Document Revision ==

{|
!width="33%"| Page
!width="33%"| Document ID
!width="33%"| Last updated
|-
| [[Business-Requirements|Business Requirements]]
| PGCBL-BRD-001
| 2026-03-17
|-
| [[Technical-Specification|Technical Specification]]
| PGCBL-TSD-001
| 2026-03-17
|-
| [[Data-Dictionary|Data Dictionary]]
| PGCBL-DDD-001
| 2026-03-17
|-
| [[Flow-Diagrams|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.''