Martin: Created page with " = Technical Specification = '''Project:''' pgcobol — Prime Numbers Application
'''Version:''' 1.0 (reverse-engineered)
'''Date:''' 2026-03-17 ----- == 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 | Postgr..."

2026-03-25T16:44:47Z

Created page with " = Technical Specification = '''Project:''' pgcobol — Prime Numbers Application '''Version:''' 1.0 (reverse-engineered) '''Date:''' 2026-03-17 ----- == 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 | Postgr..."

New page

= Technical Specification =

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

-----


== 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
|}

-----


== 2. Component Architecture ==

<pre>┌─────────────────────────────────────────────────────┐
│ primesmain │ ← Entry point / orchestrator
│ WORKING-STORAGE: commandline-args │
│ COPY: primes-session, primes-ui │
└────────────┬────────────────────────────────────────┘
│ CALL "primesgen" USING primes-session
▼
┌─────────────────────────────────────────────────────┐
│ primesgen │ ← Business logic / sieve engine
│ WORKING-STORAGE: primes (local), printer │
│ COPY (linkage): primes-session │
│ COPY (local): primes-ui, primes-dal │
└────────┬──────────────────────┬─────────────────────┘
│ CALL "primes" │ CALL "primesui"
│ 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>

-----


== 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.


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

<pre>primes-session
methods PIC X(32) verb sent by caller
88 report-primes "report"
88 generate-primes "generate"
88 start-primes "start"
88 stop-primes "stop"
88 invalid-method "bad"
session-result PIC 9(2) set by callee
88 session-method-ok 0
88 session-method-nok 1
88 session-method-eof 9</pre>

=== 3.2 DAL tier — <code>primes-dal</code> ===

<pre>primes-dal
dal-methods PIC X(32) verb sent by caller
88 next-prime "next-prime"
88 next-divider "next-divider"
88 write-prime "write"
88 db-cursor "cursor"
88 db-connect "connect"
88 db-disconnect "disconnect"
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>

=== 3.3 UI tier — <code>primes-ui</code> ===

<pre>primes-ui
ui-methods PIC X(32) verb sent by caller
88 start-ui "start"
88 write-ui "write"
88 message-ui "log-message"
88 stop-ui "stop"
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>

-----


== 4. Pseudocode ==


=== 4.1 primesmain ===

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

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

CASE commandline-args OF

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

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

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

END CASE

LOG "Primes run complete, program stops."
CALL primesui("stop")
STOP
END PROGRAM</pre>

=== 4.2 primesgen — report path ===

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

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

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

LOOP UNTIL session-method-eof
SET u-sequence = primes-sequence
SET u-number = prime-number
CALL primesui("write") -- accumulate into print buffer
CALL primes-dal("next-prime") -- advance cursor
END LOOP
END PROCEDURE</pre>

=== 4.3 primesgen — generate path ===

<pre>PROCEDURE generate-path
CALL primes-dal("connect")
IF dal-method-ok THEN
SET test-divider = 2
SET old-ident = 1
SET test-number = 3
SET test-number-sqr = SQRT(3)
LOG "Database initialisation succeeded."
ELSE
LOG "Database initialisation failed."
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("next-divider")

test-divider > test-number-sqr:
-- no factor found up to sqrt; test-number is prime
CALL primes-dal("write") -- INSERT INTO primes
CALL primesui("write") -- 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("next-divider")

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

END LOOP
END PROCEDURE</pre>

=== 4.4 primes (DAL) ===

<pre>PROGRAM primes
LINKAGE: primes-dal

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

"cursor":
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

"next-prime":
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

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

"write":
EXEC SQL INSERT INTO primes (prime) VALUES (:prime)

"disconnect":
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>

=== 4.5 primesui ===

<pre>PROGRAM primesui
LINKAGE: primes-ui

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

"write":
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

"log-message":
DISPLAY process-message ON CONSOLE

"stop":
LOOP writing zero rows UNTIL new-page -- flush partial line
CLOSE fprinter

END CASE
EXIT PROGRAM
END PROGRAM</pre>

-----


== 5. Database Interface Specification ==


=== 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
|}


=== 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
|}


=== 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.

-----


== 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>"primes overview"</code> (col 1)
|-
| Column header
| <code>"Sequence Prime"</code> × 6 across
|-
| Page footing
| Spaces + <code>"page: ZZZZ9"</code> (right side)
|-
| EOP trigger
| linage-counter = 53
|}

-----


== 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]]

Technical specifications - Revision history