Editing Technical specifications

<span id="technical-specification"></span>
= Technical Specification =

'''Project:''' pgcobol — Prime Numbers Application<br />
'''Version:''' 1.0 (reverse-engineered)<br />
'''Date:''' 2026-03-17


-----

<span id="technology-stack"></span>
== 1. Technology Stack ==

{|
!width="50%"| Component
!width="50%"| Technology
|-
| Runtime
| GnuCOBOL 4.0, Linux
|-
| SQL pre-processor
| GixSQL (translates EXEC SQL … END-EXEC to GIXSQLExec calls)
|-
| Database server
| PostgreSQL 11.22, localhost:5432
|-
| Database schema
| <code>primes</code>
|-
| Credentials
| user <code>primes_user</code>, password <code>pr1mes_user</code> (hard-coded)
|-
| Output file
| <code>primes.prt</code> — line-sequential, 132 chars/record, linage 56
|-
| Console
| GnuCOBOL special-name <code>scherm</code> mapped to system console
|}


-----

<span id="component-architecture"></span>
== 2. Component Architecture ==

<pre>┌─────────────────────────────────────────────────────┐
│                   primesmain                        │  ← Entry point / orchestrator
│  WORKING-STORAGE: commandline-args                  │
│  COPY: primes-session, primes-ui                    │
└────────────┬────────────────────────────────────────┘
             │ CALL &quot;primesgen&quot; USING primes-session
             ▼
┌─────────────────────────────────────────────────────┐
│                   primesgen                         │  ← Business logic / sieve engine
│  WORKING-STORAGE: primes (local), printer           │
│  COPY (linkage): primes-session                     │
│  COPY (local):   primes-ui, primes-dal              │
└────────┬──────────────────────┬─────────────────────┘
         │ CALL &quot;primes&quot;        │ CALL &quot;primesui&quot;
         │ USING primes-dal     │ USING primes-ui
         ▼                      ▼
┌──────────────────┐   ┌──────────────────────────────┐
│     primes       │   │          primesui             │  ← Presentation / output
│  (DAL + SQL)     │   │  FILE: fprinter → primes.prt  │
│  EXEC SQL via    │   │  WORKING-STORAGE: primes-table│
│  GixSQL          │   │  COPY (linkage): primes-ui    │
└──────────────────┘   └──────────────────────────────┘
         │
         ▼
┌──────────────────┐
│   PostgreSQL     │
│  schema: primes  │
│  table:  primes  │
└──────────────────┘</pre>

-----

<span id="inter-tier-interface-contracts"></span>
== 3. Inter-Tier Interface Contracts ==

All communication between tiers uses method-dispatch over shared copybook control blocks. A caller sets a verb string in the <code>methods</code> field, invokes the subprogram, and reads the result code on return.

<span id="session-tier-primes-session"></span>
=== 3.1 Session tier — <code>primes-session</code> ===

<pre>primes-session
  methods          PIC X(32)          verb sent by caller
    88 report-primes   &quot;report&quot;
    88 generate-primes &quot;generate&quot;
    88 start-primes    &quot;start&quot;
    88 stop-primes     &quot;stop&quot;
    88 invalid-method  &quot;bad&quot;
  session-result   PIC 9(2)           set by callee
    88 session-method-ok   0
    88 session-method-nok  1
    88 session-method-eof  9</pre>
<span id="dal-tier-primes-dal"></span>
=== 3.2 DAL tier — <code>primes-dal</code> ===

<pre>primes-dal
  dal-methods      PIC X(32)          verb sent by caller
    88 next-prime      &quot;next-prime&quot;
    88 next-divider    &quot;next-divider&quot;
    88 write-prime     &quot;write&quot;
    88 db-cursor       &quot;cursor&quot;
    88 db-connect      &quot;connect&quot;
    88 db-disconnect   &quot;disconnect&quot;
  primes-data                         data payload (one row)
    primes-sequence  PIC 9(9)         ident from DB
    prime-number     PIC 9(9)         prime value from DB
  dal-result       PIC 9(2)           set by callee
    88 dal-method-ok   0
    88 dal-method-nok  1
    88 dal-method-eof  99</pre>
<span id="ui-tier-primes-ui"></span>
=== 3.3 UI tier — <code>primes-ui</code> ===

<pre>primes-ui
  ui-methods       PIC X(32)          verb sent by caller
    88 start-ui        &quot;start&quot;
    88 write-ui        &quot;write&quot;
    88 message-ui      &quot;log-message&quot;
    88 stop-ui         &quot;stop&quot;
  process-message                     structured console message
    program-name     PIC X(20)
    program-paragraph PIC X(20)
    program-message  PIC X(92)
  u-primes                            one prime row for print output
    u-sequence       PIC 9(9)
    u-number         PIC 9(9)
  ui-method-result PIC 9(2)           set by callee
    88 ui-method-ok    0
    88 ui-method-nok   1</pre>

-----

<span id="pseudocode"></span>
== 4. Pseudocode ==

<span id="primesmain"></span>
=== 4.1 primesmain ===

<pre>PROGRAM primesmain
  INPUT: command-line argument → commandline-args

  CALL primesui(&quot;start&quot;)
  IF ui-method-ok THEN
    LOG &quot;UI initialisation succeeded.&quot;
    LOG commandline-args
  ELSE
    DISPLAY emergency message on console
    STOP

  CASE commandline-args OF

    &quot;report&quot;:
      LOG &quot;Primes report generation starts.&quot;
      SET methods = &quot;report&quot;
      CALL primesgen(primes-session)       -- report flow

    &quot;generate&quot;:
      LOG &quot;Primes generation starts.&quot;
      SET methods = &quot;generate&quot;
      -- NOTE: CALL primesgen commented out in current source

    OTHER:
      LOG &quot;Bad parameter, program initialisation failed.&quot;
      CALL primesui(&quot;stop&quot;)
      STOP

  END CASE

  LOG &quot;Primes run complete, program stops.&quot;
  CALL primesui(&quot;stop&quot;)
  STOP
END PROGRAM</pre>
<span id="primesgen-report-path"></span>
=== 4.2 primesgen — report path ===

<pre>PROCEDURE report-path
  CALL primes-dal(&quot;connect&quot;)
  IF dal-method-ok THEN
    LOG &quot;Database initialisation succeeded.&quot;
  ELSE
    LOG &quot;Database initialisation failed.&quot;
    SET session-result = 1
    RETURN

  CALL primes-dal(&quot;cursor&quot;)           -- START TRANSACTION + OPEN primescursor
  IF dal-method-ok THEN
    LOG &quot;Cursor initialisation succeeded.&quot;
  ELSE
    LOG &quot;Cursor initialisation failed.&quot;
    SET session-result = 1
    RETURN

  FETCH first row via primes-dal(&quot;next-prime&quot;)
  IF fetch fails THEN
    LOG &quot;Fetch first row nok.&quot;
    SET dal-result = 1

  LOOP UNTIL session-method-eof
    SET u-sequence = primes-sequence
    SET u-number   = prime-number
    CALL primesui(&quot;write&quot;)            -- accumulate into print buffer
    CALL primes-dal(&quot;next-prime&quot;)     -- advance cursor
  END LOOP
END PROCEDURE</pre>
<span id="primesgen-generate-path"></span>
=== 4.3 primesgen — generate path ===

<pre>PROCEDURE generate-path
  CALL primes-dal(&quot;connect&quot;)
  IF dal-method-ok THEN
    SET test-divider   = 2
    SET old-ident      = 1
    SET test-number    = 3
    SET test-number-sqr = SQRT(3)
    LOG &quot;Database initialisation succeeded.&quot;
  ELSE
    LOG &quot;Database initialisation failed.&quot;
    SET session-result = 1
    RETURN

  LOOP UNTIL test-number = 999,999,999

    DIVIDE test-number BY test-divider → test-quot REMAINDER test-rest

    CASE OF
      test-rest = 0:
        -- test-number is composite; move to next candidate
        ADD 2 TO test-number
        SET test-number-sqr = SQRT(test-number)
        SET old-ident = 1
        FETCH divider[old-ident+1] via primes-dal(&quot;next-divider&quot;)

      test-divider &gt; test-number-sqr:
        -- no factor found up to sqrt; test-number is prime
        CALL primes-dal(&quot;write&quot;)      -- INSERT INTO primes
        CALL primesui(&quot;write&quot;)        -- add to print buffer
        ADD 2 TO test-number
        SET test-number-sqr = SQRT(test-number)
        SET old-ident = 1
        FETCH divider[old-ident+1] via primes-dal(&quot;next-divider&quot;)

      OTHERWISE:
        -- try next divider from DB
        FETCH divider[old-ident+1] via primes-dal(&quot;next-divider&quot;)
    END CASE

  END LOOP
END PROCEDURE</pre>
<span id="primes-dal"></span>
=== 4.4 primes (DAL) ===

<pre>PROGRAM primes
  LINKAGE: primes-dal

  CASE dal-methods OF
    &quot;connect&quot;:
      EXEC SQL CONNECT TO datasrc AS primes USER dbusr USING dbpwd
      IF SQLCODE = 0 THEN dal-result = 0 ELSE dal-result = 1

    &quot;cursor&quot;:
      EXEC SQL AT primes START TRANSACTION
      IF SQLCODE = 0 THEN
        EXEC SQL OPEN primescursor
        IF SQLCODE = 0 THEN dal-result = 0 ELSE dal-result = 1
      ELSE dal-result = 1

    &quot;next-prime&quot;:
      EXEC SQL FETCH primescursor INTO :primes-row
      IF SQLCODE = 0 THEN
        primes-sequence = r-ident
        prime-number    = r-prime
        dal-result = 0
      ELSE dal-result = 1

    &quot;next-divider&quot;:
      new-ident = old-ident + 1
      EXEC SQL SELECT prime INTO :test-divider
               FROM primes WHERE ident = :new-ident
      old-ident = new-ident

    &quot;write&quot;:
      EXEC SQL INSERT INTO primes (prime) VALUES (:prime)

    &quot;disconnect&quot;:
      EXEC SQL CONNECT RESET primes
      IF SQLCODE = 0 THEN dal-result = 0 ELSE dal-result = 1

    OTHER:
      dal-result = 1
  END CASE
  EXIT PROGRAM
END PROGRAM</pre>
<span id="primesui"></span>
=== 4.5 primesui ===

<pre>PROGRAM primesui
  LINKAGE: primes-ui

  CASE ui-methods OF
    &quot;start&quot;:
      OPEN OUTPUT fprinter (primes.prt)
      IF file-status = &quot;00&quot; THEN
        ui-method-result = 0
        primes-idx = 1
      ELSE
        ui-method-result = 1

    &quot;write&quot;:
      t-ident(primes-idx) = u-sequence
      t-prime(primes-idx) = u-number
      primes-idx = primes-idx + 1
      IF new-page THEN write heading + column header
      IF primes-idx = 7 THEN
        WRITE primes-table line to fprinter
        primes-idx = 1
      IF linage-counter = 53 THEN write footing, increment page

    &quot;log-message&quot;:
      DISPLAY process-message ON CONSOLE

    &quot;stop&quot;:
      LOOP writing zero rows UNTIL new-page   -- flush partial line
      CLOSE fprinter

  END CASE
  EXIT PROGRAM
END PROGRAM</pre>

-----

<span id="database-interface-specification"></span>
== 5. Database Interface Specification ==

<span id="connection"></span>
=== 5.1 Connection ===

{|
! Parameter
! Value
|-
| Driver
| GixSQL pgsql
|-
| Host
| localhost
|-
| Port
| 5432
|-
| Database
| primes
|-
| Schema search path
| primes
|-
| Connection alias
| primes
|-
| User
| primes_user
|-
| Password
| pr1mes_user
|}

<span id="sql-statements"></span>
=== 5.2 SQL Statements ===

{|
!width="33%"| ID
!width="33%"| Statement
!width="33%"| Called from
|-
| S-01
| <code>CONNECT TO :DATASRC AS primes USER :DBUSR USING :DBPWD</code>
| s00-connect
|-
| S-02
| <code>START TRANSACTION</code>
| s01-cursor
|-
| S-03
| <code>DECLARE primescursor CURSOR FOR SELECT * FROM primes</code>
| compile-time
|-
| S-04
| <code>OPEN primescursor</code>
| s01-cursor
|-
| S-05
| <code>FETCH primescursor INTO :primes-row</code>
| s02-fetch
|-
| S-06
| <code>SELECT prime INTO :test-divider FROM primes WHERE ident = :new-ident</code>
| r81-get-next-divider
|-
| S-07
| <code>INSERT INTO primes (prime) VALUES (:prime)</code>
| r83-write-prime
|-
| S-08
| <code>CONNECT RESET primes</code>
| s99-disconnect
|}

<span id="error-handling"></span>
=== 5.3 Error Handling ===

* All SQL paths test <code>SQLCODE = 0</code> for success.
* On failure, a diagnostic string is moved to <code>program-message</code> and logged via primesui.
* <code>dal-result</code> is set to <code>1</code> (nok) on SQL errors; callers check <code>dal-method-ok</code> before continuing.
* No retry logic is implemented; errors cause the current operation to be skipped or the session to terminate.


-----

<span id="output-file-specification"></span>
== 6. Output File Specification ==

{|
! Property
! Value
|-
| Filename
| <code>primes.prt</code>
|-
| Organisation
| Line-sequential
|-
| Record length
| 132 characters
|-
| Linage
| 56 lines per page
|-
| Footing area
| 2 lines from bottom
|-
| Bottom margin
| 2 lines
|-
| Records per data line
| 6 primes (sequence + value pairs)
|-
| Page heading
| <code>&quot;primes overview&quot;</code> (col 1)
|-
| Column header
| <code>&quot;Sequence  Prime&quot;</code> × 6 across
|-
| Page footing
| Spaces + <code>&quot;page: ZZZZ9&quot;</code> (right side)
|-
| EOP trigger
| linage-counter = 53
|}


-----

<span id="known-defects-and-limitations"></span>
== 7. Known Defects and Limitations ==

{|
!width="33%"| ID
!width="33%"| Severity
!width="33%"| Description
|-
| D-01
| High
| Generate loop (<code>PERFORM r80-test-number</code>) is commented out in primesmain; generation mode does not execute the sieve.
|-
| D-02
| Medium
| Prime 2 is never seeded; generation starts at 3 with first divider = 2 retrieved from DB, but DB is empty at start of a fresh run.
|-
| D-03
| Medium
| <code>primes_cbsql.out</code> shows disconnect using alias <code>primesdb</code>; primes.cbl uses alias <code>primes</code> — alias mismatch will cause runtime SQL error.
|-
| D-04
| Low
| Database credentials are hard-coded in WORKING-STORAGE of primes.cbl.
|-
| D-05
| Low
| No COMMIT after INSERT in r83-write-prime (statement is commented out); relies on PostgreSQL auto-commit or session-level transaction semantics.
|-
| D-06
| Low
| Two almost-identical host-variable copybooks (<code>primes-table.cpy</code> vs <code>primes_table.cpy</code>) suggest unresolved refactoring.
|}
<hr/>
Terug naar: [[Primes_programs_specifications]] | [[Cobol and PostgreSQL]]