Editing Primes Software Specification

<span id="software-specification-primes.cbsql"></span>
= Software Specification — <code>Primes.cbsql</code> =

<blockquote>'''Standard:''' IEEE 830 / ISO/IEC 29148 (Requirements) · IEEE 1016 (Design) · ISO/IEC 11179 (Data Dictionary) · UML 2.x Activity Diagrams<br />
'''Source:''' <code>Primes.cbsql</code> — GnuCOBOL + GixSQL preprocessed source<br />
'''Date:''' 2026-03-17<br />
'''Status:''' Reverse-engineered
</blockquote>

-----

<span id="table-of-contents"></span>
== Table of Contents ==

# [[#1-business-requirements-document|Business Requirements Document]]
# [[#2-technical-specification--pseudocode|Technical Specification / Pseudocode]]
# [[#3-data-dictionary|Data Dictionary]]
# [[#4-flow-diagrams|Flow Diagrams]]


-----

<span id="business-requirements-document"></span>
== 1. Business Requirements Document ==

<span id="purpose"></span>
=== 1.1 Purpose ===

<code>Primes.cbsql</code> is a COBOL Data Access Layer (DAL) module that manages persistent storage of prime numbers in a PostgreSQL database. It is not a standalone program; it is invoked by a calling driver program that selects the desired operation via a shared linkage interface (<code>primes-dal</code>).

<span id="scope"></span>
=== 1.2 Scope ===

The module handles all database interactions for the prime number generation system, including connection lifecycle management, cursor-based sequential reads, row-by-row prime retrieval for trial division, and insertion of newly discovered primes.

<span id="system-context"></span>
=== 1.3 System Context ===

{|
! Item
! Value
|-
| '''Platform'''
| Linux (GnuCOBOL + GixSQL)
|-
| '''Database'''
| PostgreSQL 5432 @ localhost
|-
| '''Schema'''
| <code>primes</code>
|-
| '''Database name'''
| <code>primes</code>
|-
| '''DB user'''
| <code>primes_user</code>
|-
| '''UI module'''
| <code>primesui</code> (called for all status messages)
|-
| '''Linkage interface'''
| <code>primes-dal</code> (copybook)
|}

<span id="business-functions"></span>
=== 1.4 Business Functions ===

{|
!width="33%"| ID
!width="33%"| Method Flag
!width="33%"| Description
|-
| BF-01
| <code>db-connect</code>
| Establish a connection to the PostgreSQL database
|-
| BF-02
| <code>db-cursor</code>
| Begin a transaction and open a cursor for reading all primes
|-
| BF-03
| <code>next-prime</code>
| Fetch the next prime row from the open cursor
|-
| BF-04
| <code>next-divider</code>
| Retrieve a specific prime by identity index to use as a trial divisor
|-
| BF-05
| <code>write-prime</code>
| Insert a newly proven prime into the database
|-
| BF-06
| <code>db-disconnect</code>
| Close the database connection and release resources
|}

<span id="business-rules"></span>
=== 1.5 Business Rules ===

{|
!width="50%"| ID
!width="50%"| Rule
|-
| BR-01
| The initial prime value <code>2</code> is inserted as a seed record during first-run initialisation (<code>r90-generate-primes</code>)
|-
| BR-02
| All operations must set <code>dal-result</code> to <code>0</code> on success or <code>1</code> on failure
|-
| BR-03
| All status messages (success and error) must be routed through the <code>primesui</code> subprogram
|-
| BR-04
| Raw SQL error codes (<code>SQLCODE</code>) must be displayed to the console on failure
|-
| BR-05
| Trial division uses stored primes up to the square root of the candidate number
|}

<span id="assumptions-and-constraints"></span>
=== 1.6 Assumptions and Constraints ===

* The database schema and table (<code>primes.primes</code>) must exist prior to program execution.
* The calling program is responsible for managing the sequence of DAL method calls.
* <code>r90-generate-primes</code> (seed insertion) is not reachable via the DAL dispatch and must be called directly during initial setup.


-----

<span id="technical-specification-pseudocode"></span>
== 2. Technical Specification / Pseudocode ==

<span id="program-entry-and-dispatch"></span>
=== 2.1 Program Entry and Dispatch ===

<pre>PROGRAM primes
  CALLED BY: external driver via LINKAGE SECTION (primes-dal)

  ON ENTRY:
    EVALUATE TRUE on dal-method flag:
      WHEN next-prime    → PERFORM r80-get-next-prime
      WHEN next-divider  → PERFORM r81-get-next-divider
      WHEN write-prime   → PERFORM r83-write-prime
      WHEN db-connect    → PERFORM s00-connect
      WHEN db-cursor     → PERFORM s01-cursor
      WHEN db-disconnect → PERFORM s99-disconnect
      WHEN OTHER         → SET dal-result = 1
    END-EVALUATE
  EXIT PROGRAM</pre>
<span id="paragraph-specifications"></span>
=== 2.2 Paragraph Specifications ===

==== r80-get-next-prime ====

<pre>PERFORM s02-fetch</pre>
==== r81-get-next-divider ====

<pre>new-ident = old-ident + 1
SQL: SELECT prime FROM primes WHERE ident = :new-ident
     INTO :test-divider
IF SQLCODE = 0
  (test-divider now holds the next divisor prime)
ELSE
  DISPLAY SQLCODE to console
  DISPLAY &quot;select new-divider nok&quot; to console
old-ident = new-ident</pre>
==== r83-write-prime ====

<pre>SQL: INSERT INTO primes (prime) VALUES (:prime)
IF SQLCODE != 0
  DISPLAY SQLCODE to console
  DISPLAY &quot;insert next prime nok&quot; + prime-number to console</pre>
<span id="r90-generate-primes-first-run-initialisation-not-via-dal-dispatch"></span>
==== r90-generate-primes ''(first-run initialisation, not via DAL dispatch)'' ====

<pre>PERFORM s00-connect
IF dal-method-ok
  SQL: INSERT INTO primes (prime) VALUES (2)   -- seed record
  IF SQLCODE = 0
    primes-sequence = 1
    prime-number    = 2
    dal-result      = 0
    LOG &quot;Initial insert ok.&quot;
  ELSE
    LOG &quot;Initial insert failed, terminating.&quot;
    dal-result = 1
CALL primesui (log-message)</pre>
==== s00-connect ====

<pre>SQL: CONNECT TO :DATASRC AS primes USER :DBUSR USING :DBPWD
IF SQLCODE = 0
  dal-result = 0
  LOG &quot;Database initialisation ok.&quot;
ELSE
  LOG &quot;Database initialisation failed, terminating.&quot;
  dal-result = 1
CALL primesui</pre>
==== s01-cursor ====

<pre>SQL: START TRANSACTION
IF SQLCODE = 0
  LOG &quot;Start transaction ok.&quot;
ELSE
  LOG &quot;Start transaction nok.&quot;
  dal-result = 1
CALL primesui

IF dal-method-ok
  OPEN CURSOR primescursor  (SELECT * FROM primes)
  IF SQLCODE = 0
    LOG &quot;Start primescursor ok.&quot;
  ELSE
    LOG &quot;Start primescursor nok.&quot;
    dal-result = 1
CALL primesui</pre>
==== s02-fetch ====

<pre>SQL: FETCH primescursor INTO :r-ident, :r-prime
IF SQLCODE = 0
  primes-sequence = r-ident
  prime-number    = r-prime
  dal-result      = 0
ELSE
  LOG &quot;Fetch row nok.&quot;
  dal-result = 1
  CALL primesui</pre>
==== s99-disconnect ====

<pre>SQL: CONNECT RESET primes
IF SQLCODE = 0
  dal-result = 0
  LOG &quot;Close database ok.&quot;
ELSE
  LOG &quot;Database initialisation failed, ending.&quot;
  dal-result = 1
CALL primesui
DISPLAY &quot;s99 disconnect from database&quot; to console
DISPLAY SQLCODE to console</pre>

-----

<span id="data-dictionary"></span>
== 3. Data Dictionary ==

<span id="working-storage-fields"></span>
=== 3.1 Working Storage Fields ===

{|
!width="25%"| Field
!width="25%"| PIC
!width="25%"| COBOL Type
!width="25%"| Description
|-
| <code>DATASRC</code>
| <code>X(64)</code>
| Alphanumeric
| PostgreSQL connection string
|-
| <code>DBUSR</code>
| <code>X(64)</code>
| Alphanumeric
| Database login username
|-
| <code>DBPWD</code>
| <code>X(64)</code>
| Alphanumeric
| Database login password
|-
| <code>CUR-STEP</code>
| <code>X(16)</code>
| Alphanumeric
| Current processing step label
|-
| <code>prime-count</code>
| <code>9(9)</code>
| Numeric
| Count of primes (declared; populated by driver)
|-
| <code>prime_seq</code>
| <code>9(9)</code>
| Numeric
| Prime sequence number (declared; populated by driver)
|-
| <code>divider</code>
| <code>9(9)</code>
| Numeric
| Trial divider working field
|}

<span id="group-primes-row-database-fetch-buffer"></span>
=== 3.2 Group: <code>primes-row</code> — Database Fetch Buffer ===

{|
!width="25%"| Field
!width="25%"| PIC
!width="25%"| COBOL Type
!width="25%"| Description
|-
| <code>r-ident</code>
| <code>9(9) COMP-3</code>
| Packed decimal
| Row identity key fetched from cursor
|-
| <code>r-prime</code>
| <code>9(9) COMP-3</code>
| Packed decimal
| Prime value fetched from cursor
|}

<span id="group-primes-primality-test-working-storage"></span>
=== 3.3 Group: <code>primes</code> — Primality Test Working Storage ===

{|
!width="33%"| Field
!width="33%"| PIC / Value
!width="33%"| Description
|-
| <code>primes-result</code>
| <code>9(2)</code>
| Status code: <code>1</code>=init ok · <code>2</code>=first divider ok · <code>3</code>=next divider ok
|-
| <code>88 init-primes-ok</code>
| value <code>1</code>
| Condition name: initialisation succeeded
|-
| <code>88 first-divider-ok</code>
| value <code>2</code>
| Condition name: first trial divisor retrieved
|-
| <code>88 next-divider-ok</code>
| value <code>3</code>
| Condition name: subsequent trial divisor retrieved
|-
| <code>test-number</code>
| <code>9(9)</code>
| Candidate number under primality test
|-
| <code>test-number-sqr</code>
| <code>9(9)v9(9)</code>
| Square root of <code>test-number</code> — upper bound for divisor loop
|-
| <code>test-divider</code>
| <code>9(9)</code>
| Current prime divisor retrieved from DB
|-
| <code>test-rest</code>
| <code>9(9)v9(9)</code>
| Remainder of <code>test-number ÷ test-divider</code>
|-
| <code>old-test-number</code>
| <code>9(9)</code>
| Previous candidate number
|-
| <code>old-ident</code>
| <code>9(9)</code>
| Row identity of the last retrieved divisor
|-
| <code>new-ident</code>
| <code>9(9)</code>
| Row identity of the next divisor (<code>old-ident + 1</code>)
|}

<span id="copybook-references"></span>
=== 3.4 Copybook References ===

{|
!width="50%"| Copybook
!width="50%"| Contents
|-
| <code>primes-table</code>
| COBOL record layout mirroring the <code>primes</code> DB table
|-
| <code>SQLCA</code>
| Standard SQL Communication Area (<code>SQLCODE</code>, <code>SQLERRM</code>, etc.)
|-
| <code>primes-ui</code>
| Data structure for <code>primesui</code> subprogram (messages, program name, methods)
|-
| <code>primes-dal</code>
| DAL linkage interface — method flags and <code>dal-result</code> return code
|}

<span id="prepared-sql-statements"></span>
=== 3.5 Prepared SQL Statements ===

{|
!width="33%"| Ref
!width="33%"| SQL Text
!width="33%"| Used in
|-
| <code>SQ0001</code>
| <code>SELECT * FROM primes</code>
| Cursor declaration (s01-cursor)
|-
| <code>SQ0002</code>
| <code>SELECT prime FROM primes WHERE ident = $1</code>
| r81-get-next-divider
|-
| <code>SQ0003</code>
| <code>INSERT INTO primes (prime) VALUES ($1)</code>
| r83-write-prime
|-
| <code>SQ0004</code>
| <code>INSERT INTO primes (prime) VALUES (2)</code>
| r90-generate-primes (seed)
|-
| <code>SQ0005</code>
| <code>START TRANSACTION</code>
| s01-cursor
|}

<span id="database-table-primes.primes"></span>
=== 3.6 Database Table: <code>primes.primes</code> ===

{|
!width="33%"| Column
!width="33%"| Type
!width="33%"| Description
|-
| <code>ident</code>
| INTEGER (serial / sequence)
| Auto-generated row identity / primary key
|-
| <code>prime</code>
| INTEGER
| The prime number value stored in this row
|}


-----

<span id="flow-diagrams"></span>
== 4. Flow Diagrams ==

<span id="program-entry-dal-dispatch"></span>
=== 4.1 Program Entry — DAL Dispatch ===

<pre>                    ┌──────────────────────────┐
                    │  ENTRY — primes program  │
                    │  (called with primes-dal) │
                    └────────────┬─────────────┘
                                 │
                      ┌──────────▼──────────┐
                      │  EVALUATE dal-method │
                      └──────────┬──────────┘
         ┌──────────┬────────────┼───────────┬────────────┬──────────┐
         ▼          ▼            ▼           ▼            ▼          ▼
    next-prime  next-divider  write-prime db-connect  db-cursor  db-disconnect
         │          │            │           │            │          │
         ▼          ▼            ▼           ▼            ▼          ▼
     r80-get-   r81-get-    r83-write-  s00-connect  s01-cursor s99-disconnect
     next-prime next-divider  prime
         │          │            │           │            │          │
         └──────────┴────────────┴───────────┴────────────┴──────────┘
                                 │
                    ┌────────────▼────────────┐
                    │  SET dal-result          │
                    │  0 = success             │
                    │  1 = failure             │
                    └────────────┬────────────┘
                                 │
                    ┌────────────▼────────────┐
                    │      EXIT PROGRAM        │
                    └─────────────────────────┘</pre>
<span id="database-connection-lifecycle"></span>
=== 4.2 Database Connection Lifecycle ===

<pre>  Driver calls db-connect          Driver calls db-cursor
         │                                  │
         ▼                                  ▼
   s00-connect                        s01-cursor
   SQL CONNECT                        SQL START TRANSACTION
         │                                  │
    SQLCODE=0?                         SQLCODE=0?
    ├─ yes → dal-result=0              ├─ yes → OPEN primescursor
    └─ no  → dal-result=1             └─ no  → dal-result=1
         │                                  │
   CALL primesui                      CALL primesui
                                           │
                              ┌────────────▼──────────────┐
                              │  Loop: Driver calls        │
                              │  next-prime repeatedly     │
                              │          │                 │
                              │    r80 → s02-fetch         │
                              │    FETCH primescursor      │
                              │    → primes-sequence       │
                              │    → prime-number          │
                              │    SQLCODE=0? loop / stop  │
                              └────────────┬──────────────┘
                                           │
                              Driver calls db-disconnect
                                           │
                                    s99-disconnect
                                    SQL CONNECT RESET
                                           │
                                      CALL primesui</pre>
<span id="prime-discovery-flow-cross-module-context"></span>
=== 4.3 Prime Discovery Flow (cross-module context) ===

<pre>  Driver: candidate number N to test
          │
          ▼
  Set old-ident = 0
          │
  ┌───────▼────────────────────────────────┐
  │  LOOP: call next-divider               │
  │    → r81: new-ident = old-ident + 1    │
  │    → SQL SELECT prime WHERE ident=new  │
  │    → test-divider returned             │
  │                                        │
  │  IF test-divider &gt; SQRT(N) → PRIME!    │
  │  IF N MOD test-divider = 0 → NOT prime │
  │  ELSE continue loop                    │
  └───────────────────────────────────────┘
          │
     N is prime?
     ├─ yes → call write-prime
     │          → r83: INSERT INTO primes VALUES (N)
     └─ no  → discard, try N+1 (even numbers typically skipped)</pre>
<span id="cursor-fetch-detail"></span>
=== 4.4 Cursor Fetch Detail ===

<pre>  s02-fetch
      │
  GIXSQLStartSQL
      │
  GIXSQLSetResultParams (:r-ident)
  GIXSQLSetResultParams (:r-prime)
      │
  GIXSQLCursorFetchOne (primes_primescursor)
      │
  GIXSQLEndSQL
      │
  SQLCODE = 0?
  ├─ yes → primes-sequence = r-ident
  │         prime-number   = r-prime
  │         dal-result     = 0
  └─ no  → LOG &quot;Fetch row nok.&quot;
            dal-result = 1
            CALL primesui</pre>

-----

''End of specification.''