Martin: Created page with " = Technical Specification =
'''Document ID:''' PGCBL-TSD-001 · '''Version:''' 1.0 · '''Status:''' Approved · '''Last updated:''' 2026-03-17
'''← Business Requirements''' | Data Dictionary → ----- == Contents == # System Architecture #* Three-Tier Model #* #12-inter-..."

2026-03-24T21:28:31Z

Created page with " = Technical Specification = <blockquote>'''Document ID:''' PGCBL-TSD-001 · '''Version:''' 1.0 · '''Status:''' Approved · '''Last updated:''' 2026-03-17 </blockquote> '''← Business Requirements''' | Data Dictionary → ----- == Contents == # System Architecture #* Three-Tier Model #* #12-inter-..."

New page

= Technical Specification =

<blockquote>'''Document ID:''' PGCBL-TSD-001 · '''Version:''' 1.0 · '''Status:''' Approved · '''Last updated:''' 2026-03-17
</blockquote>
'''← [[Business-Requirements|Business Requirements]]''' | [[Data-Dictionary|Data Dictionary →]]

-----


== Contents ==

# [[#1-system-architecture|System Architecture]]
#* [[#11-three-tier-model|Three-Tier Model]]
#* [[#12-inter-tier-communication-pattern|Inter-Tier Communication Pattern]]
# [[#2-component-inventory|Component Inventory]]
# [[#3-pseudocode|Pseudocode]]
#* [[#31-primesmain|primesmain]]
#* [[#32-primesgen--generate-path|primesgen — Generate Path]]
#* [[#33-primesgen--report-path|primesgen — Report Path]]
#* [[#34-primes-dal|primes (DAL)]]
#* [[#35-primesui|primesui]]
# [[#4-database-connection-parameters|Database Connection Parameters]]
# [[#5-sql-statement-inventory|SQL Statement Inventory]]
# [[#6-file-io-specification|File I/O Specification]]
# [[#7-known-technical-issues|Known Technical Issues]]

-----


== 1. System Architecture ==


=== 1.1 Three-Tier Model ===

<pre>┌──────────────────────────────────────────────────────┐
│ primesmain │
│ Orchestrator · session controller · entry point │
│ Source: primesmain.cbl │
└───────────────────────┬──────────────────────────────┘
│ CALL "primesgen" USING primes-session
┌─────────▼──────────────┐
│ primesgen │
│ Business Logic tier │
│ Sieve algorithm or │
│ cursor read-loop │
│ Source: primesgen.cbl │
└──────┬─────────────────┘
CALL "primes" │ │ CALL "primesui"
USING primes-dal │ │ USING primes-ui
┌─────────▼──┐ ┌───▼──────────────┐
│ primes │ │ primesui │
│ Data │ │ Presentation │
│ Access │ │ Print file │
│ Layer │ │ Console log │
│ All SQL │ │ primesui.cbl │
│ primes.cbl│ └───────────────────┘
└──────┬─────┘ │
│ EXEC SQL │ WRITE to
│ via GixSQL │ primes.prt
┌──────▼─────────────┐ │
│ PostgreSQL 11 │ │
│ schema: primes │ ▼
│ table: primes │ (file system)
└────────────────────┘</pre>
'''Design rule:''' SQL appears only in <code>primes.cbl</code>. File I/O appears only in <code>primesui.cbl</code>. All other programs use the method-dispatch pattern to delegate to these two.


=== 1.2 Inter-Tier Communication Pattern ===

Every program-to-program call uses the same protocol:

<pre>Step 1 Caller MOVEs a verb string into the control block's methods field
MOVE "connect" TO dal-methods

Step 2 Caller invokes the subprogram, passing the control block by reference
CALL "primes" USING primes-dal

Step 3 Callee EVALUATEs the verb and performs the matching paragraph
EVALUATE TRUE
WHEN db-connect → PERFORM s00-connect
...

Step 4 Callee sets a result code before EXIT PROGRAM
MOVE 0 TO dal-result ← success

Step 5 Caller inspects the result code
IF dal-method-ok THEN ...</pre>
{|
!width="25%"| Tier boundary
!width="25%"| Control block
!width="25%"| Verbs
!width="25%"| Result codes
|-
| primesmain → primesgen
| [[Data-Dictionary#11-primes-session|<code>primes-session</code>]]
| <code>report</code> · <code>generate</code>
| 0=ok · 1=nok · 9=eof
|-
| primesgen → primes
| [[Data-Dictionary#12-primes-dal|<code>primes-dal</code>]]
| <code>connect</code> · <code>cursor</code> · <code>next-prime</code> · <code>next-divider</code> · <code>write</code> · <code>disconnect</code>
| 0=ok · 1=nok · 99=eof
|-
| any → primesui
| [[Data-Dictionary#13-primes-ui|<code>primes-ui</code>]]
| <code>start</code> · <code>write</code> · <code>log-message</code> · <code>stop</code>
| 0=ok · 1=nok
|}

-----


== 2. Component Inventory ==


=== Programs ===

{|
!width="20%"| Program
!width="20%"| Source file
!width="20%"| Tier
!width="20%"| Contains SQL
!width="20%"| Opens files
|-
| <code>primesmain</code>
| <code>primesmain.cbl</code>
| Orchestrator
| No
| No
|-
| <code>primesgen</code>
| <code>primesgen.cbl</code>
| Business logic
| No
| No (FD declared but unused)
|-
| <code>primes</code>
| <code>primes.cbl</code>
| Data access
| Yes — via GixSQL
| No
|-
| <code>primesui</code>
| <code>primesui.cbl</code>
| Presentation
| No
| Yes — <code>primes.prt</code>
|}


=== Copybooks ===

{|
!width="25%"| Copybook
!width="25%"| Root record
!width="25%"| Used by
!width="25%"| Purpose
|-
| <code>primes-session.cpy</code>
| <code>primes-session</code>
| primesmain · primesgen
| Session-tier control block
|-
| <code>primes-dal.cpy</code>
| <code>primes-dal</code>
| primesgen · primes
| DAL-tier control block
|-
| <code>primes-ui.cpy</code>
| <code>primes-ui</code>
| all four
| UI-tier control block
|-
| <code>primes-table.cpy</code>
| <code>primes-table</code>
| primes
| SQL host variables — character format
|-
| <code>primes_table.cpy</code>
| <code>primes_table</code>
| primes
| SQL host variables — COMP-3 format ⚠ duplicate
|-
| <code>SQLCA.cpy</code>
| <code>SQLCA</code>
| primes
| GixSQL SQL Communications Area
|}

Full field definitions: [[Data-Dictionary#1-control-blocks-copybooks|Data Dictionary → Control Blocks]]

-----


== 3. Pseudocode ==


=== 3.1 primesmain ===

<pre>PROGRAM primesmain
ACCEPT commandline-args FROM COMMAND-LINE ← PIC X(32)

MOVE commandline-args TO methods ← load session control block
MOVE "primesmain" TO program-name

CALL primesui("start") ← open primes.prt
IF ui-method-result ≠ 0 THEN
DISPLAY "Emergency: UI failed" ON console
STOP RUN ← hard abort, no cleanup

LOG "UI initialisation succeeded."
LOG commandline-args

EVALUATE commandline-args
WHEN "report"
LOG "Primes report generation starts."
MOVE "report" TO methods
CALL primesgen USING primes-session ← report path

WHEN "generate"
LOG "Primes generation starts."
MOVE "generate" TO methods
── CALL primesgen commented out ── ← ⚠ Defect T1

WHEN OTHER
LOG "Bad parameter, program initialisation failed."
CALL primesui("stop")
STOP RUN
END-EVALUATE

LOG "Primes run complete, program stops."
CALL primesui("stop") ← flush + close primes.prt
STOP RUN
END PROGRAM</pre>

-----


=== 3.2 primesgen — Generate Path ===

<pre>PROCEDURE r91-start-primes-generation
CALL primes("connect")
IF dal-method-ok THEN
test-divider = 2 ← first divisor
old-ident = 1
test-number = 3 ← first candidate (odd)
test-number-sqr = SQRT(3) ← COMPUTE test-number ** 0.5
LOG "Database initialisation succeeded."
ELSE
LOG "Database initialisation failed."
session-result = 1
RETURN ← falls through to r99-close-primes

MAIN LOOP — PERFORM r80-test-number UNTIL test-number = 999999999

PROCEDURE r80-test-number
DIVIDE test-number BY test-divider
GIVING test-quot REMAINDER test-rest

EVALUATE TRUE
WHEN test-rest = 0 ← divisible → composite
PERFORM r82-next-test-number

WHEN test-divider > test-number-sqr ← no factor ≤ √N → prime
PERFORM r85-write-prime
PERFORM r82-next-test-number

WHEN OTHER ← keep trying
PERFORM r89-get-next-divider

PROCEDURE r82-next-test-number
ADD 2 TO test-number ← skip even numbers
COMPUTE test-number-sqr = test-number ** 0.5
MOVE 1 TO old-ident
PERFORM r89-get-next-divider ← reload first divisor

PROCEDURE r85-write-prime
MOVE "write" TO ui-methods
CALL primes USING primes-dal ← INSERT INTO primes (prime)
CALL primesui USING primes-ui ← accumulate in print buffer

PROCEDURE r89-get-next-divider
MOVE "get" TO gen-methods ← verb for the local primes group
CALL primes USING primes ← SELECT prime WHERE ident = old-ident+1
← sets test-divider

END LOOP
CALL primes("disconnect")
EXIT PROGRAM</pre>

-----


=== 3.3 primesgen — Report Path ===

<pre>PROCEDURE r90-start-primes-report
CALL primes("connect")
IF NOT dal-method-ok THEN
LOG "Database initialisation failed."
session-result = 1
GOTO r99-close-primes

CALL primes("cursor") ← START TRANSACTION; OPEN primescursor
IF NOT dal-method-ok THEN
LOG "Cursor initialisation failed."
session-result = 1
GOTO r99-close-primes

PERFORM r94-fetch ← position cursor on first row
IF dal-method-ok THEN
LOG "Fetch first row ok."
MOVE 0 TO dal-result
ELSE
LOG "Fetch first row nok."
MOVE 1 TO dal-result

REPORT LOOP — PERFORM r86-report-primes UNTIL session-method-eof

PROCEDURE r86-report-primes
MOVE "write" TO ui-methods
MOVE primes-data TO u-primes ← primes-sequence + prime-number → u-sequence + u-number
CALL primesui USING primes-ui ← write to 6-column print buffer
PERFORM r94-fetch ← advance cursor

PROCEDURE r94-fetch
MOVE "next-prime" TO dal-methods
CALL primes USING primes-dal ← FETCH primescursor INTO :primes-row
IF NOT dal-method-ok THEN
LOG "Fetch failed."
session-result = 1 ← ⚠ sets nok (1), not eof (9) — loop may not terminate
← See Defect T7 in defect register

END LOOP
CALL primes("disconnect")
EXIT PROGRAM</pre>

-----


=== 3.4 primes (DAL) ===

<pre>PROGRAM primes USING primes-dal

EVALUATE TRUE on dal-methods
WHEN db-connect → PERFORM s00-connect
WHEN db-cursor → PERFORM s01-cursor
WHEN next-prime → PERFORM r80-get-next-prime (→ s02-fetch)
WHEN next-divider → PERFORM r81-get-next-divider
WHEN write-prime → PERFORM r83-write-prime
WHEN db-disconnect → PERFORM s99-disconnect
WHEN OTHER → MOVE 1 TO dal-result
END-EVALUATE
EXIT PROGRAM

── s00-connect ──────────────────────────────────────────────────────
EXEC SQL
CONNECT TO :DATASRC AS primes USER :DBUSR USING :DBPWD
END-EXEC
IF SQLCODE = 0 THEN dal-result = 0
ELSE LOG error; dal-result = 1

── s01-cursor ───────────────────────────────────────────────────────
EXEC SQL AT primes START TRANSACTION END-EXEC
IF SQLCODE = 0 THEN LOG "Start transaction ok."
ELSE dal-result = 1

IF dal-method-ok THEN
EXEC SQL OPEN primescursor END-EXEC
IF SQLCODE = 0 THEN LOG "Start primescursor ok."
ELSE dal-result = 1

── s02-fetch (called by r80-get-next-prime) ─────────────────────────
EXEC SQL FETCH primescursor INTO :primes-row END-EXEC
IF SQLCODE = 0 THEN
primes-sequence = r-ident
prime-number = r-prime
dal-result = 0
ELSE LOG error; dal-result = 1

── r81-get-next-divider ─────────────────────────────────────────────
ADD 1 TO old-ident GIVING new-ident
EXEC SQL AT primes
SELECT prime INTO :test-divider
FROM primes WHERE ident = :new-ident
END-EXEC
IF SQLCODE ≠ 0 THEN DISPLAY SQLCODE; DISPLAY "select new-divider nok"
MOVE new-ident TO old-ident

── r83-write-prime ──────────────────────────────────────────────────
EXEC SQL AT primes
INSERT INTO primes (prime) VALUES (:prime)
END-EXEC
IF SQLCODE ≠ 0 THEN DISPLAY SQLCODE; DISPLAY "insert nok: " prime-number
── COMMIT is commented out ── ← ⚠ Defect T3

── s99-disconnect ───────────────────────────────────────────────────
EXEC SQL CONNECT RESET primes END-EXEC ← ⚠ Defect T2: cbsql.out shows "primesdb"
IF SQLCODE = 0 THEN dal-result = 0
ELSE dal-result = 1
DISPLAY "s99 disconnect from database"
DISPLAY SQLCODE</pre>

-----


=== 3.5 primesui ===

<pre>PROGRAM primesui USING primes-ui

EVALUATE TRUE on ui-methods
WHEN start-ui → PERFORM r90-start-primesui
WHEN write-ui → PERFORM r92-write-primesui
WHEN message-ui → PERFORM r98-message-ui
WHEN stop-ui → PERFORM r99-stop-primesui
WHEN OTHER → MOVE 1 TO ui-method-result
END-EVALUATE
EXIT PROGRAM

── r90-start-primesui ───────────────────────────────────────────────
OPEN OUTPUT fprinter (primes.prt)
IF primes-prt-status = "00" THEN
SET primes-idx TO 1
MOVE 0 TO ui-method-result
LOG "Open printer Ok"
ELSE
MOVE 1 TO ui-method-result
DISPLAY primes-prt-status ON console

── r92-write-primesui ───────────────────────────────────────────────
t-ident(primes-idx) = u-sequence ← load into current cell
t-prime(primes-idx) = u-number
SET primes-idx UP BY 1 ← advance index

IF new-page THEN PERFORM r93-new-page ← heading + column header

IF primes-idx = 7 THEN ← 6 entries filled
WRITE file-buffer FROM primes-table ← 132-char data line
SET primes-idx TO 1

IF linage-counter = 53 THEN ← 3 lines from page end
PERFORM r94-eop ← footing + page increment

── r93-new-page ─────────────────────────────────────────────────────
WRITE primes-heading (="primes overview")
WRITE table-header (="Sequence Prime " × 6)
MOVE ZERO TO print-new-page ← clear flag

── r94-eop ──────────────────────────────────────────────────────────
WRITE blank line
WRITE primes-footing (right-aligned "page: ZZZZ9")
ADD 1 TO page-number
MOVE 1 TO print-new-page ← trigger heading on next write

── r98-message-ui ───────────────────────────────────────────────────
DISPLAY process-message UPON scherm ← program-name + paragraph + message

── r99-stop-primesui ────────────────────────────────────────────────
MOVE 0 TO u-sequence
MOVE 0 TO u-number
PERFORM r92-write-primesui UNTIL new-page ← flush partial line with zeros
LOG "close printer"
CLOSE fprinter
MOVE primes-prt-status TO ui-method-result</pre>

-----


== 4. Database Connection Parameters ==

{|
!width="50%"| Parameter
!width="50%"| Value
|-
| Driver
| <code>pgsql</code> (GixSQL native PostgreSQL driver)
|-
| Host
| <code>localhost</code>
|-
| Port
| <code>5432</code>
|-
| Database name
| <code>primes</code>
|-
| Schema
| <code>primes</code> (set via <code>default_schema=primes</code> in connection string)
|-
| Connection alias
| <code>primes</code> (used in all <code>EXEC SQL AT primes</code> clauses)
|-
| User
| <code>primes_user</code>
|-
| Password
| <code>pr1mes_user</code> ⚠ hard-coded — see [[#7-known-technical-issues|Defect T5]]
|-
| Full connection string
| <code>pgsql://localhost:5432/primes&default_schema=primes</code>
|}

-----


== 5. SQL Statement Inventory ==

{|
!width="25%"| ID
!width="25%"| Statement
!width="25%"| Paragraph
!width="25%"| Path
|-
| S1
| <code>CONNECT TO :DATASRC AS primes USER :DBUSR USING :DBPWD</code>
| <code>s00-connect</code>
| Both
|-
| S2
| <code>START TRANSACTION</code>
| <code>s01-cursor</code>
| Report only
|-
| S3
| <code>DECLARE primescursor CURSOR FOR SELECT * FROM primes</code>
| Compile-time
| Report only
|-
| S4
| <code>OPEN primescursor</code>
| <code>s01-cursor</code>
| Report only
|-
| S5
| <code>FETCH primescursor INTO :primes-row</code>
| <code>s02-fetch</code>
| Report only
|-
| S6
| <code>SELECT prime INTO :test-divider FROM primes WHERE ident = :new-ident</code>
| <code>r81-get-next-divider</code>
| Generate only
|-
| S7
| <code>INSERT INTO primes (prime) VALUES (:prime)</code>
| <code>r83-write-prime</code>
| Generate only
|-
| S8
| <code>CONNECT RESET primes</code>
| <code>s99-disconnect</code>
| Both
|}

'''Host variable mappings:'''

{|
!width="25%"| SQL host variable
!width="25%"| COBOL field
!width="25%"| PICTURE
!width="25%"| Source
|-
| <code>:DATASRC</code>
| <code>DATASRC</code>
| <code>PIC X(64)</code>
| WS — <code>primes.cbl</code>
|-
| <code>:DBUSR</code>
| <code>DBUSR</code>
| <code>PIC X(64)</code>
| WS — <code>primes.cbl</code>
|-
| <code>:DBPWD</code>
| <code>DBPWD</code>
| <code>PIC X(64)</code>
| WS — <code>primes.cbl</code>
|-
| <code>:primes-row</code>
| <code>primes-row</code> group
| r-ident + r-prime <code>COMP-3</code>
| WS — <code>primes.cbl</code>
|-
| <code>:test-divider</code>
| <code>test-divider</code>
| <code>PIC 9(9)</code>
| WS — <code>primes.cbl</code> local <code>primes</code> group
|-
| <code>:new-ident</code>
| <code>new-ident</code>
| <code>PIC 9(9)</code>
| WS — <code>primes.cbl</code> local <code>primes</code> group
|-
| <code>:prime</code>
| <code>prime-number</code>
| <code>PIC 9(9)</code>
| Linkage — <code>primes-dal.primes-data</code>
|}

-----


== 6. File I/O Specification ==


=== Print file <code>primes.prt</code> ===

{|
! Property
! Value
|-
| Logical name
| <code>fprinter</code>
|-
| Physical name
| <code>primes.prt</code> (relative to working directory)
|-
| Organisation
| Line-sequential
|-
| Record length
| 132 characters
|-
| Linage
| 56 lines per page
|-
| Footing area
| Lines 55–56 (last 2 of linage)
|-
| Bottom margin
| 2 lines
|-
| Top margin
| 0 (not specified)
|-
| Open mode
| <code>OUTPUT</code> (write-only; created fresh each run)
|-
| File-status field
| <code>primes-prt-status</code> <code>PIC X(2)</code>
|-
| EOP trigger
| <code>linage-counter = 53</code> (3 lines before page end)
|}


=== Record types ===

{|
!width="33%"| Record
!width="33%"| Content
!width="33%"| Width
|-
| Page heading
| <code>"primes overview"</code> left-justified
| 118 + 14 padding = 132
|-
| Column header
| <code>"Sequence Prime "</code> × 6
| 132
|-
| Data line
| 6 × (<code>Z(9)</code> seq + <code>X(2)</code> sp + <code>Z(9)</code> prime + <code>X(2)</code> sp)
| 132
|-
| Blank separator
| Spaces
| 132
|-
| Page footing
| 118 spaces + <code>"page: "</code> + <code>Z(3)9</code>
| 132
|}

-----


== 7. Known Technical Issues ==

{|
!width="25%"| ID
!width="25%"| Severity
!width="25%"| Description
!width="25%"| Impact
|-
| T1
| 🔴 High
| Generate loop (<code>PERFORM r80-test-number</code>) is commented out in <code>primesmain.cbl</code> line 51
| <code>generate</code> mode does not execute the sieve
|-
| T2
| 🔴 High
| <code>primes_cbsql.out</code> shows disconnect targeting alias <code>primesdb</code>; runtime code uses alias <code>primes</code>
| Disconnect call will fail with alias-not-found error at runtime
|-
| T3
| 🟡 Medium
| COMMIT after INSERT is commented out in <code>r83-write-prime</code>
| Relies on PostgreSQL auto-commit; INSERTs will not commit if an explicit transaction is open
|-
| T4
| 🟡 Medium
| Prime 2 is not seeded by the algorithm; sieve starts at 3 with <code>old-ident = 1</code>, assuming a row exists at <code>ident = 2</code>
| Divider lookup will fail or return wrong value on a fresh empty database
|-
| T5
| 🟠 Medium
| Database credentials hard-coded in <code>primes.cbl</code> WORKING-STORAGE
| Credential rotation requires recompile; credentials visible in binary
|-
| T6
| 🔵 Low
| Two near-duplicate host-variable copybooks: <code>primes-table.cpy</code> (char) and <code>primes_table.cpy</code> (COMP-3, underscore)
| Ambiguity about which is canonical; risk of one being stale
|-
| T7
| 🟡 Medium
| On fetch failure, <code>session-result</code> is set to 1 (nok), not 9 (eof); the report loop condition <code>session-method-eof</code> (value 9) is never triggered by normal cursor exhaustion
| Report loop may not terminate cleanly at end of data
|}

-----

'''← [[Business-Requirements|Business Requirements]]''' | [[Data-Dictionary|Data Dictionary →]]

Technical-Specification - Revision history