Martin: Created page with " = I/O Behaviour = '''Project:''' pgcobol — Prime Numbers Application
'''Version:''' 1.0 (reverse-engineered)
'''Date:''' 2026-03-17 ----- == 1. File I/O — primes.prt == === 1.1 File Definition (primesui.cbl) === SELECT fprinter ASSIGN TO "primes.prt" ORGANIZATION IS SEQUENTIAL FILE STATUS I..."

2026-03-25T16:49:49Z

Created page with " = I/O Behaviour = '''Project:''' pgcobol — Prime Numbers Application '''Version:''' 1.0 (reverse-engineered) '''Date:''' 2026-03-17 ----- == 1. File I/O — primes.prt == === 1.1 File Definition (primesui.cbl) === <syntaxhighlight lang="cobol">SELECT fprinter ASSIGN TO "primes.prt" ORGANIZATION IS SEQUENTIAL FILE STATUS I..."

New page

= I/O Behaviour =

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

-----


== 1. File I/O — primes.prt ==


=== 1.1 File Definition (primesui.cbl) ===

<syntaxhighlight lang="cobol">SELECT fprinter ASSIGN TO "primes.prt"
ORGANIZATION IS SEQUENTIAL
FILE STATUS IS primes-prt-status.

FD fprinter
LABEL RECORDS OMITTED
LINAGE 56,
FOOTING 2,
BOTTOM 2.

01 file-buffer PIC X(132).</syntaxhighlight>
{|
! 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
| last 2 lines of linage
|-
| Bottom margin
| 2 lines
|-
| Top margin
| not specified (default 0)
|-
| Open mode
| OUTPUT only
|-
| Status field
| <code>primes-prt-status</code> PIC X(2)
|}


=== 1.2 Open ===

Called by <code>r90-start-primesui</code> when <code>ui-methods = "start"</code>:

<pre>OPEN OUTPUT fprinter</pre>
* Success: <code>primes-prt-status = "00"</code>, <code>ui-method-result = 0</code>, <code>primes-idx = 1</code>.
* Failure: <code>primes-prt-status ≠ "00"</code>, <code>ui-method-result = 1</code>, status displayed on console.


=== 1.3 Write — Data Lines ===

Called by <code>r92-write-primesui</code> when <code>primes-idx</code> reaches 7 (after loading 6 entries):

<pre>MOVE primes-table TO print-buffer
WRITE file-buffer FROM print-buffer</pre>
One 132-character record is written per six prime entries. The record layout is:

<pre>[Z(9)][XX][Z(9)][XX][Z(9)][XX][Z(9)][XX][Z(9)][XX][Z(9)][XX]
seq1 sp prime1 sp seq2 sp prime2 sp seq3 sp prime3 sp ... × 6</pre>
Each cell = 9 + 2 + 9 + 2 = 22 characters; 6 cells = 132 characters exactly.


=== 1.4 Write — Page Heading (<code>r93-new-page</code>) ===

<pre>WRITE file-buffer FROM primes-heading → "primes overview" (PIC X(118))
WRITE file-buffer FROM table-header → "Sequence Prime " × 6</pre>
Triggered by <code>new-page</code> flag = 1. Flag cleared after write.


=== 1.5 Write — Page Footing (<code>r94-eop</code>) ===

Triggered when <code>linage-counter = 53</code>:

<pre>WRITE file-buffer FROM ' ' → blank separator
WRITE file-buffer FROM primes-footing → spaces(118) + "page: " + Z(3)9
ADD 1 TO page-number
SET print-new-page = 1 → next write triggers new heading</pre>

=== 1.6 Close ===

Called by <code>r99-stop-primesui</code> when <code>ui-methods = "stop"</code>:

<pre>CLOSE fprinter</pre>
Before close, a flush loop pads remaining cells with zeros until <code>new-page</code> fires, guaranteeing the last partial data line is written.

Success / failure reflected in <code>ui-method-result</code> ← <code>primes-prt-status</code>.

-----


== 2. Console Output — scherm ==


=== 2.1 Definition ===

<syntaxhighlight lang="cobol">SPECIAL-NAMES. CONSOLE IS scherm.</syntaxhighlight>
All four programs declare <code>scherm</code> as the console special-name.


=== 2.2 Structured Log Messages (via primesui) ===

<code>r98-message-ui</code> in primesui:

<pre>DISPLAY process-message UPON scherm</pre>
<code>process-message</code> is a 132-character group:

<pre>program-name PIC X(20) e.g. "primesmain "
program-paragraph PIC X(20) e.g. "r90-start-session "
program-message PIC X(92) e.g. "UI initialisation succeeded. ..."</pre>
Every caller populates <code>program-name</code>, optionally <code>program-paragraph</code>, and always <code>program-message</code> before calling <code>primesui "log-message"</code>.


=== 2.3 Direct DISPLAY Statements (diagnostic / error) ===

Several paragraphs bypass primesui and write directly to <code>scherm</code>:

{|
!width="33%"| Location
!width="33%"| Statement
!width="33%"| Purpose
|-
| primesmain r90
| <code>DISPLAY "Emergency console message…" UPON scherm</code>
| Hard abort if UI fails
|-
| primes r81
| <code>DISPLAY SQLCODE UPON scherm</code>
| SQL error on next-divider
|-
| primes r81
| <code>DISPLAY "select new-divider nok" UPON scherm</code>
|
|-
| primes r83
| <code>DISPLAY SQLCODE UPON scherm</code>
| SQL error on insert
|-
| primes r83
| <code>DISPLAY "primes.cbl insert next prime nok…" UPON scherm</code>
|
|-
| primes s00
| <code>DISPLAY "connect to database" UPON scherm</code>
| Always shown on connect
|-
| primes s00
| <code>DISPLAY SQLCODE UPON scherm</code>
|
|-
| primes s99
| <code>DISPLAY "s99 disconnect from database" UPON scherm</code>
| Always shown on disconnect
|-
| primes s99
| <code>DISPLAY SQLCODE UPON scherm</code>
|
|-
| primesui r90
| <code>DISPLAY primes-prt-status UPON scherm</code>
| File open failure
|-
| primesui r99
| <code>DISPLAY primes-prt-status UPON scherm</code>
| File close failure
|}

-----


== 3. Database I/O (primes.cbl via GixSQL) ==


=== 3.1 Connection Management ===

{|
!width="33%"| Operation
!width="33%"| SQL
!width="33%"| Paragraph
|-
| Connect
| <code>CONNECT TO :DATASRC AS primes USER :DBUSR USING :DBPWD</code>
| s00-connect
|-
| Disconnect
| <code>CONNECT RESET primes</code>
| s99-disconnect
|}

Connection string: <code>pgsql://localhost:5432/primes&default_schema=primes</code> 
Connection alias: <code>primes</code> (used in all <code>EXEC SQL AT primes</code> statements)


=== 3.2 Cursor Lifecycle (report path only) ===

{|
!width="33%"| Operation
!width="33%"| SQL
!width="33%"| Paragraph
|-
| Declare
| <code>DECLARE primescursor CURSOR FOR SELECT * FROM primes</code>
| compile-time
|-
| Begin transaction
| <code>START TRANSACTION</code>
| s01-cursor
|-
| Open
| <code>OPEN primescursor</code>
| s01-cursor
|-
| Fetch one row
| <code>FETCH primescursor INTO :primes-row</code>
| s02-fetch
|-
| (Close)
| not explicitly closed — connection reset closes it
| —
|}

Each <code>FETCH</code> populates <code>primes-row</code> (r-ident, r-prime), which is then copied to <code>primes-sequence</code> and <code>prime-number</code> in <code>primes-dal</code> for the caller.

End-of-cursor is signalled by <code>SQLCODE ≠ 0</code>; <code>dal-result</code> is set to 1, which primesgen maps to <code>session-method-eof</code> implicitly (by checking <code>session-method-eof</code> condition, value 9 — note: there is a mapping gap; dal-result=1 does not equal session-result=9; the report loop relies on <code>session-method-eof</code> which is never explicitly set in the current code — see defect D-RPT-01 below).


=== 3.3 DML (generate path) ===

{|
!width="33%"| Operation
!width="33%"| SQL
!width="33%"| Paragraph
|-
| Insert prime
| <code>INSERT INTO primes (prime) VALUES (:prime)</code>
| r83-write-prime
|}

* Host variable <code>:prime</code> maps to <code>prime-number</code> in <code>primes-dal.primes-data</code>.
* No explicit COMMIT in the current code (statement is commented out).
* PostgreSQL default auto-commit applies per statement unless inside the transaction opened by <code>s01-cursor</code>.


=== 3.4 Queries (generate path — divider lookup) ===

{|
!width="33%"| Operation
!width="33%"| SQL
!width="33%"| Paragraph
|-
| Get next divider
| <code>SELECT prime INTO :test-divider FROM primes WHERE ident = :new-ident</code>
| r81-get-next-divider
|}

* <code>:new-ident</code> = <code>old-ident + 1</code> (computed inline before the SELECT).
* <code>:test-divider</code> is in the local <code>primes</code> working-storage group in primesgen, not in <code>primes-dal</code>.


=== 3.5 Error Handling Pattern ===

Every SQL statement uses the same pattern:

<pre>EXEC SQL ... END-EXEC
IF SQLCODE = 0 THEN
[success actions]
ELSE
[log error / set result code]</pre>
No <code>WHENEVER</code> directives are used.

-----


== 4. Command-Line Input ==

{|
!width="25%"| Program
!width="25%"| Statement
!width="25%"| Variable
!width="25%"| Length
|-
| primesmain
| <code>ACCEPT commandline-args FROM COMMAND-LINE</code>
| <code>commandline-args</code> PIC X(32)
| 32 chars
|}

Only the first 32 characters of the command-line argument are stored. The value is copied to <code>methods</code> in the session control block and also logged to the console via primesui after session start.

-----


== 5. Known I/O Defects ==

{|
!width="50%"| ID
!width="50%"| Description
|-
| D-RPT-01
| The report loop condition <code>session-method-eof</code> (value 9) is never set in the code path; when a fetch fails, <code>session-result</code> is set to 1 (nok), not 9, causing the loop to terminate on error rather than on true EOF.
|-
| D-IO-01
| <code>primesgen</code> declares a <code>SELECT fprinter</code> and <code>FD fprinter</code> but never opens or uses the file; print output is delegated entirely to primesui.
|-
| D-IO-02
| Connection reset in <code>s99-disconnect</code> targets alias <code>primes</code>; the pre-compiler listing (<code>primes_cbsql.out</code>) shows <code>primesdb</code> used in earlier iterations, which would cause a runtime alias-not-found error.
|}
<hr/>
Terug naar: [[Primes_programs_specifications]] | [[Cobol and PostgreSQL]]

IO behaviour - Revision history