Martin at 23:01, 24 March 2026

2026-03-24T23:01:35Z

← Older revision		Revision as of 23:01, 24 March 2026
Line 445:		Line 445:
	-----		-----

	'''← [[Data-Dictionary\|Data Dictionary]]''' \| [[~~Home~~\|~~Home~~ →]]		'''← [[Data-Dictionary\|Data Dictionary]]''' \| [[Primes system Design\|Primes system Design →]]

Martin at 23:00, 24 March 2026

2026-03-24T23:00:51Z

← Older revision		Revision as of 23:00, 24 March 2026
Line 5:		Line 5:
	'''Notation:''' Mermaid <code>flowchart TD</code> and <code>sequenceDiagram</code>		'''Notation:''' Mermaid <code>flowchart TD</code> and <code>sequenceDiagram</code>
	</blockquote>		</blockquote>
	'''← [[Data-Dictionary\|Data Dictionary]]''' \| [[~~Home~~\|~~Home~~ →]]		'''← [[Data-Dictionary\|Data Dictionary]]''' \| [[Primes system Design\|Primes system Design →]]

Martin: Created page with " = Flow Diagrams =
'''Document ID:''' PGCBL-FLD-001 · '''Version:''' 1.0 · '''Status:''' Approved · '''Last updated:''' 2026-03-17
'''Notation:''' Mermaid `flowchart TD` and `sequenceDiagram`
'''← Data Dictionary''' | Home → ----- == Contents == # Top-Level Application Flow # #2-prim..."

2026-03-24T22:58:53Z

Created page with " = Flow Diagrams = <blockquote>'''Document ID:''' PGCBL-FLD-001 · '''Version:''' 1.0 · '''Status:''' Approved · '''Last updated:''' 2026-03-17 '''Notation:''' Mermaid <code>flowchart TD</code> and <code>sequenceDiagram</code> </blockquote> '''← Data Dictionary''' | Home → ----- == Contents == # Top-Level Application Flow # #2-prim..."

New page

= Flow Diagrams =

<blockquote>'''Document ID:''' PGCBL-FLD-001 · '''Version:''' 1.0 · '''Status:''' Approved · '''Last updated:''' 2026-03-17 
'''Notation:''' Mermaid <code>flowchart TD</code> and <code>sequenceDiagram</code>
</blockquote>
'''← [[Data-Dictionary|Data Dictionary]]''' | [[Home|Home →]]

-----


== Contents ==

# [[#1-top-level-application-flow|Top-Level Application Flow]]
# [[#2-primesgen-dispatch-flow|primesgen Dispatch Flow]]
# [[#3-prime-generation-sieve-loop|Prime Generation — Sieve Loop]]
# [[#4-prime-report-loop|Prime Report — Cursor Loop]]
# [[#5-dal-primescbl-method-dispatch|DAL (primes.cbl) Method Dispatch]]
# [[#6-ui-primesui-method-dispatch|UI (primesui.cbl) Method Dispatch]]
# [[#7-inter-program-call-sequence--generate-run|Inter-Program Call Sequence — Generate Run]]
# [[#8-inter-program-call-sequence--report-run|Inter-Program Call Sequence — Report Run]]

-----


== 1. Top-Level Application Flow ==

'''Program:''' <code>primesmain.cbl</code> 
'''What it shows:''' How <code>primesmain</code> reads the command-line argument, initialises the UI layer, routes to the correct processing path, and shuts down cleanly.

<blockquote>⚠️ The <code>generate</code> branch calls <code>r92-generate-primes</code> but the PERFORM inside that paragraph that drives the sieve is commented out. See [[Technical-Specification#7-known-technical-issues|Technical Specification — Defect T1]].
</blockquote>
<pre class="mermaid">flowchart TD
A([START]) --> B[ACCEPT commandline-args\nFROM COMMAND-LINE]
B --> C[MOVE commandline-args TO methods\nMOVE 'primesmain' TO program-name]
C --> D[r90-start-session\nMOVE 'start' TO ui-methods\nCALL primesui USING primes-ui]

D --> E{ui-method-ok?}
E -->|No| F[DISPLAY emergency msg\nUPON scherm\nSTOP RUN]
E -->|Yes| G[LOG 'UI initialisation succeeded.'\nLOG commandline-args]

G --> H{EVALUATE\ncommandline-args}

H -->|'report'| I[LOG 'Primes report generation starts.'\nMOVE 'report' TO methods]
I --> J[r92-generate-primes\nCALL primesgen USING primes-session]

H -->|'generate'| K[LOG 'Primes generation starts.'\nMOVE 'generate' TO methods]
K --> L["⚠️ r92-generate-primes\n[PERFORM commented out in source]"]

H -->|other| M[LOG 'Bad parameter'\nCALL primesui 'stop'\nSTOP RUN]

J --> N[LOG 'Primes run complete, program stops.']
L --> N
N --> O[r99-stop-session\nMOVE 'stop' TO ui-methods\nCALL primesui USING primes-ui]
O --> P([STOP RUN])</pre>
'''Key paragraphs:'''

{|
!width="50%"| Paragraph
!width="50%"| Action
|-
| <code>r90-start-session</code>
| Opens <code>primes.prt</code>; hard-stops if open fails
|-
| <code>r92-generate-primes</code>
| Single CALL to primesgen; passes <code>primes-session</code> by reference
|-
| <code>r99-stop-session</code>
| Flushes print buffer and closes <code>primes.prt</code>
|}

-----


== 2. primesgen Dispatch Flow ==

'''Program:''' <code>primesgen.cbl</code> 
'''What it shows:''' How primesgen reads the <code>methods</code> field in <code>primes-session</code> and routes to either the generation or report path, then always performs cleanup.

<pre class="mermaid">flowchart TD
A([ENTRY — primesgen\nUSING primes-session]) --> B{EVALUATE TRUE\non methods}

B -->|report-primes| C[PERFORM r90-start-primes-report]
B -->|generate-primes| D[PERFORM r91-start-primes-generation]
B -->|other| E[LOG 'Bad method, primes process failed.']

C --> F{session-method-ok?}
F -->|Yes| G[PERFORM r86-report-primes\nUNTIL session-method-eof]
F -->|No| Z

D --> H{session-method-ok?}
H -->|Yes| I[PERFORM r80-test-number\nUNTIL test-number = 999999999]
H -->|No| Z

G --> Z
I --> Z
E --> Z

Z[r99-close-primes\nMOVE 'disconnect' TO dal-methods\nCALL primes USING primes-dal] --> END([EXIT PROGRAM])</pre>

-----


== 3. Prime Generation — Sieve Loop ==

'''Program:''' <code>primesgen.cbl</code> (r80-series paragraphs) + <code>primes.cbl</code> (r81, r83) 
'''What it shows:''' The trial-division sieve — how each candidate is tested, how composites are skipped, and how confirmed primes are persisted.

'''Algorithm in words:''' 1. Start at candidate = 3. Load first divisor (prime at ident 1 = prime 2, assumed pre-seeded). 2. Divide candidate by current divisor. 3. If remainder = 0 → composite. Add 2, reset divisor to first prime. 4. If divisor > √candidate → prime confirmed. Write to DB and print buffer. Add 2, reset divisor. 5. Otherwise → try next divisor (fetch next prime from DB by ident).

<pre class="mermaid">flowchart TD
A([r91-start-primes-generation]) --> B[CALL primes 'connect']
B --> C{dal-method-ok?}
C -->|No| FAIL([session-result = 1\nEXIT])
C -->|Yes| D[test-divider = 2\nold-ident = 1\ntest-number = 3\ntest-number-sqr = SQRT 3]
D --> LOG1[LOG 'Database initialisation succeeded.']

LOG1 --> LOOP{test-number\n= 999999999?}
LOOP -->|Yes| CLOSE([r99-close-primes\nEXIT PROGRAM])

LOOP -->|No| DIV[r80-test-number\nDIVIDE test-number BY test-divider\nGIVING test-quot REMAINDER test-rest]

DIV --> EVAL{EVALUATE TRUE}

EVAL -->|test-rest = 0\ncomposite| NEXT[r82-next-test-number]
EVAL -->|test-divider > test-number-sqr\nprime confirmed| WRITE[r85-write-prime\nCALL primes 'write'\nINSERT INTO primes prime\nCALL primesui 'write'\nadd to print buffer]
EVAL -->|otherwise\ntry next divisor| GETDIV[r89-get-next-divider\nCALL primes 'next-divider'\nSELECT prime WHERE ident = old-ident+1]

WRITE --> NEXT
GETDIV --> LOOP

NEXT --> NA[ADD 2 TO test-number\nCOMPUTE test-number-sqr = test-number ** 0.5\nMOVE 1 TO old-ident\nr89-get-next-divider\nload first divisor]
NA --> LOOP</pre>
'''Data flow through the sieve:'''

<pre>test-number (candidate) ──→ DIVIDE ──→ test-rest
test-divider (from DB) ──→ DIVIDE ──→ test-quot
test-number-sqr (SQRT) ──→ compare to test-divider
old-ident (DB row pointer) ──→ SELECT prime WHERE ident = old-ident+1 ──→ test-divider
prime-number (confirmed) ──→ INSERT INTO primes (prime) ──→ database
──→ u-number / u-sequence ──→ primesui print buffer</pre>

-----


== 4. Prime Report — Cursor Loop ==

'''Program:''' <code>primesgen.cbl</code> (r86, r90, r94) + <code>primes.cbl</code> (s01, s02) 
'''What it shows:''' How the report path opens a cursor over the database, fetches rows one at a time, and sends each to the print buffer.

<pre class="mermaid">flowchart TD
A([r90-start-primes-report]) --> B[CALL primes 'connect'\ndal-methods = 'connect']
B --> C{dal-method-ok?}
C -->|No| FAIL1([LOG 'Database init failed.'\nsession-result = 1\nGOTO close])
C -->|Yes| D[LOG 'Database initialisation succeeded.'\nCALL primes 'cursor'\ndal-methods = 'cursor']

D --> E[s01-cursor:\nEXEC SQL START TRANSACTION\nEXEC SQL OPEN primescursor]
E --> F{dal-method-ok?}
F -->|No| FAIL2([LOG 'Cursor init failed.'\nsession-result = 1\nGOTO close])
F -->|Yes| G[LOG 'Cursor initialisation succeeded.'\nr94-fetch → CALL primes 'next-prime'\nFETCH primescursor INTO primes-row]

G --> H{dal-method-ok?}
H -->|No| FAIL3([LOG 'Fetch first row nok.'\ndal-result = 1\nGOTO close])
H -->|Yes| I[LOG 'Fetch first row ok.'\ndal-result = 0]

I --> LOOP{session-method-eof?}
LOOP -->|Yes| CLOSE[r99-close-primes\nCALL primes 'disconnect']
CLOSE --> END([EXIT PROGRAM])

LOOP -->|No| WRITE[r86-report-primes\nMOVE primes-data TO u-primes\nCALL primesui 'write']
WRITE --> FETCH[r94-fetch\nCALL primes 'next-prime'\nFETCH primescursor INTO primes-row]
FETCH --> FCHECK{dal-method-ok?}
FCHECK -->|Yes| LOOP
FCHECK -->|No| ERR[LOG 'Fetch failed.'\nsession-result = 1]
ERR --> LOOP</pre>
<blockquote>⚠️ <code>session-result = 1</code> (nok) is set on fetch failure, but the loop condition tests <code>session-method-eof</code> (value 9). These values do not match — the loop will continue rather than exit cleanly on cursor exhaustion. See [[Technical-Specification#7-known-technical-issues|Technical Specification — Defect T7]].
</blockquote>

-----


== 5. DAL (primes.cbl) Method Dispatch ==

'''Program:''' <code>primes.cbl</code> 
'''What it shows:''' The complete method-dispatch EVALUATE inside the DAL and the SQL operations each verb triggers. Each invocation handles exactly one operation.

<pre class="mermaid">flowchart TD
A([ENTRY — primes\nUSING primes-dal]) --> B{EVALUATE TRUE\non dal-methods}

B -->|db-connect| C["s00-connect\nEXEC SQL\n CONNECT TO :DATASRC AS primes\n USER :DBUSR USING :DBPWD"]
B -->|db-cursor| D["s01-cursor\nEXEC SQL AT primes START TRANSACTION\nEXEC SQL OPEN primescursor"]
B -->|next-prime| E["r80-get-next-prime → s02-fetch\nEXEC SQL FETCH primescursor\n INTO :primes-row\nprimes-sequence = r-ident\nprime-number = r-prime"]
B -->|next-divider| F["r81-get-next-divider\nnew-ident = old-ident + 1\nEXEC SQL AT primes\n SELECT prime INTO :test-divider\n FROM primes WHERE ident = :new-ident\nold-ident = new-ident"]
B -->|write-prime| G["r83-write-prime\nEXEC SQL AT primes\n INSERT INTO primes (prime)\n VALUES (:prime)\n⚠️ COMMIT commented out"]
B -->|db-disconnect| H["s99-disconnect\nEXEC SQL CONNECT RESET primes\n⚠️ cbsql.out shows 'primesdb'"]
B -->|other| I[dal-result = 1]

C --> SC{SQLCODE = 0?}
SC -->|Yes| SOK[dal-result = 0\nLOG ok]
SC -->|No| SNOK[dal-result = 1\nLOG error]

D --> Z([EXIT PROGRAM])
E --> Z
F --> Z
G --> Z
H --> Z
I --> Z
SOK --> Z
SNOK --> Z</pre>
'''Verb → SQL mapping (summary):'''

{|
!width="33%"| Verb
!width="33%"| SQL
!width="33%"| Notes
|-
| <code>connect</code>
| <code>CONNECT TO :DATASRC AS primes …</code>
| Sets connection alias <code>primes</code>
|-
| <code>cursor</code>
| <code>START TRANSACTION</code> + <code>OPEN primescursor</code>
| Report path only
|-
| <code>next-prime</code>
| <code>FETCH primescursor INTO :primes-row</code>
| Report path only
|-
| <code>next-divider</code>
| <code>SELECT prime WHERE ident = :new-ident</code>
| Generate path only
|-
| <code>write</code>
| <code>INSERT INTO primes (prime) VALUES (:prime)</code>
| Generate path only
|-
| <code>disconnect</code>
| <code>CONNECT RESET primes</code>
| Both paths
|}

-----


== 6. UI (primesui.cbl) Method Dispatch ==

'''Program:''' <code>primesui.cbl</code> 
'''What it shows:''' How primesui routes each verb to the correct paragraph, and the detail of the <code>write</code> path — page management, line accumulation, and EOP handling.

<pre class="mermaid">flowchart TD
A([ENTRY — primesui\nUSING primes-ui]) --> B{EVALUATE TRUE\non ui-methods}

B -->|start-ui| C[r90-start-primesui\nOPEN OUTPUT fprinter\nprimes.prt]
B -->|write-ui| D[r92-write-primesui]
B -->|message-ui| E[r98-message-ui\nDISPLAY process-message\nUPON scherm]
B -->|stop-ui| F[r99-stop-primesui]
B -->|other| G[ui-method-result = 1]

C --> C1{primes-prt-status\n= '00'?}
C1 -->|Yes| C2[SET primes-idx TO 1\nui-method-result = 0\nLOG 'Open printer Ok']
C1 -->|No| C3[ui-method-result = 1\nDISPLAY status on console]

D --> D1[t-ident at primes-idx = u-sequence\nt-prime at primes-idx = u-number\nSET primes-idx UP BY 1]
D1 --> D2{new-page?}
D2 -->|Yes| D3[r93-new-page\nWRITE primes-heading\nWRITE table-header\nprint-new-page = 0]
D2 -->|No| D4{primes-idx = 7?}
D3 --> D4
D4 -->|Yes| D5[WRITE primes-table line\n132-char data record\nSET primes-idx TO 1]
D4 -->|No| D6{linage-counter = 53?}
D5 --> D6
D6 -->|Yes| D7[r94-eop\nWRITE blank line\nWRITE primes-footing\npage-number += 1\nprint-new-page = 1]
D6 -->|No| Z

F --> F1[MOVE 0 TO u-sequence and u-number\nPERFORM r92-write-primesui\nUNTIL new-page — flush partial line]
F1 --> F2[LOG 'close printer'\nCLOSE fprinter\nui-method-result = primes-prt-status]

C2 --> Z
C3 --> Z
D7 --> Z
E --> Z
F2 --> Z
G --> Z
Z([EXIT PROGRAM])</pre>
'''Page management state machine:'''

<pre>print-new-page = 1 (initial)
│
▼ (on any "write" call)
IF new-page → r93-new-page:
WRITE heading + column header
print-new-page = 0
│
▼ (accumulate 6 entries)
IF primes-idx = 7 → WRITE data line, reset idx to 1
│
▼
IF linage-counter = 53 → r94-eop:
WRITE blank + footing
page-number += 1
print-new-page = 1 ← triggers new heading on next write</pre>

-----


== 7. Inter-Program Call Sequence — Generate Run ==

'''What it shows:''' All CALL interactions between programs during a <code>generate</code> invocation, including the sieve loop, each divisor lookup, each prime insertion, and the shutdown sequence.

<pre class="mermaid">sequenceDiagram
participant OS as OS / Shell
participant main as primesmain
participant gen as primesgen
participant dal as primes (DAL)
participant ui as primesui
participant db as PostgreSQL

OS->>main: execute with arg "generate"

main->>ui: CALL "primesui" ui-methods="start"
ui-->>main: ui-method-result=0 / primes.prt opened

main->>ui: CALL "primesui" ui-methods="log-message" "Primes generation starts."
ui->>OS: DISPLAY on console

main->>gen: CALL "primesgen" methods="generate"

gen->>dal: CALL "primes" dal-methods="connect"
dal->>db: EXEC SQL CONNECT TO primes
db-->>dal: SQLCODE=0
dal-->>gen: dal-result=0

gen->>ui: LOG "Database initialisation succeeded."

loop sieve: test-number 3 → 999,999,999
gen->>gen: DIVIDE test-number BY test-divider → test-rest

alt test-rest = 0 (composite)
gen->>gen: r82-next-test-number (test-number += 2, sqrt recalc)
gen->>dal: CALL "primes" dal-methods="next-divider"
dal->>db: SELECT prime WHERE ident = :new-ident
db-->>dal: test-divider value
dal-->>gen: dal-result=0

else test-divider > √test-number (prime confirmed)
gen->>ui: CALL "primesui" ui-methods="write" u-sequence, u-number
ui->>ui: accumulate in 6-column buffer\nwrite line to primes.prt every 6 entries
gen->>dal: CALL "primes" dal-methods="write"
dal->>db: INSERT INTO primes (prime) VALUES (:prime)
db-->>dal: SQLCODE=0
dal-->>gen: dal-result=0
gen->>gen: r82-next-test-number

else otherwise (try next divisor)
gen->>dal: CALL "primes" dal-methods="next-divider"
dal->>db: SELECT prime WHERE ident = :new-ident
db-->>dal: test-divider value
dal-->>gen: dal-result=0
end
end

gen->>dal: CALL "primes" dal-methods="disconnect"
dal->>db: EXEC SQL CONNECT RESET primes
db-->>dal: SQLCODE=0
dal-->>gen: dal-result=0
gen-->>main: session-result=0 / EXIT PROGRAM

main->>ui: CALL "primesui" ui-methods="log-message" "Primes run complete."
main->>ui: CALL "primesui" ui-methods="stop"
ui->>ui: flush partial line\nCLOSE primes.prt
ui-->>main: ui-method-result=0
main->>OS: STOP RUN</pre>

-----


== 8. Inter-Program Call Sequence — Report Run ==

'''What it shows:''' All CALL interactions during a <code>report</code> invocation — UI setup, database connection, transaction and cursor lifecycle, the fetch loop, and shutdown.

<pre class="mermaid">sequenceDiagram
participant OS as OS / Shell
participant main as primesmain
participant gen as primesgen
participant dal as primes (DAL)
participant ui as primesui
participant db as PostgreSQL
participant prt as primes.prt

OS->>main: execute with arg "report"

main->>ui: CALL "primesui" ui-methods="start"
ui->>prt: OPEN OUTPUT
prt-->>ui: file-status="00"
ui-->>main: ui-method-result=0

main->>gen: CALL "primesgen" methods="report"

gen->>dal: CALL "primes" dal-methods="connect"
dal->>db: EXEC SQL CONNECT TO primes
db-->>dal: SQLCODE=0
dal-->>gen: dal-result=0
gen->>ui: LOG "Database initialisation succeeded."

gen->>dal: CALL "primes" dal-methods="cursor"
dal->>db: EXEC SQL AT primes START TRANSACTION
dal->>db: EXEC SQL OPEN primescursor
db-->>dal: SQLCODE=0
dal-->>gen: dal-result=0
gen->>ui: LOG "Cursor initialisation succeeded."

gen->>dal: r94-fetch → dal-methods="next-prime"
dal->>db: EXEC SQL FETCH primescursor INTO :primes-row
db-->>dal: first row (ident, prime)
dal-->>gen: primes-sequence, prime-number / dal-result=0
gen->>ui: LOG "Fetch first row ok."

loop for each row until cursor exhausted
gen->>ui: CALL "primesui" ui-methods="write" u-sequence / u-number
ui->>prt: accumulate in 6-col buffer\nwrite 132-char line every 6 entries\nwrite heading+footing at page boundaries
gen->>dal: r94-fetch → dal-methods="next-prime"
dal->>db: EXEC SQL FETCH primescursor
db-->>dal: next row or SQLCODE≠0 (no more rows)
dal-->>gen: dal-result=0 (row) or dal-result=1 (eof/error)
note over gen: ⚠️ session-method-eof (9) never set;\nloop exits on error (1), not clean eof
end

gen->>dal: CALL "primes" dal-methods="disconnect"
dal->>db: EXEC SQL CONNECT RESET primes
db-->>dal: SQLCODE=0
dal-->>gen: dal-result=0
gen-->>main: session-result=0 / EXIT PROGRAM

main->>ui: CALL "primesui" ui-methods="log-message" "Primes run complete."
main->>ui: CALL "primesui" ui-methods="stop"
ui->>ui: pad remaining cells with zeros\nPERFORM r92 UNTIL new-page\nCLOSE fprinter
ui->>prt: CLOSE
prt-->>ui: file-status="00"
ui-->>main: ui-method-result=0
main->>OS: STOP RUN</pre>

-----

'''← [[Data-Dictionary|Data Dictionary]]''' | [[Home|Home →]]

Flow-Diagrams - Revision history

Martin at 23:01, 24 March 2026

Martin at 23:00, 24 March 2026