Editing IO behaviour (section)

= I/O Behaviour =

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


-----

<span id="file-io-primes.prt"></span>
== 1. File I/O — primes.prt ==

<span id="file-definition-primesui.cbl"></span>
=== 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)
|}

<span id="open"></span>
=== 1.2 Open ===

Called by <code>r90-start-primesui</code> when <code>ui-methods = &quot;start&quot;</code>:

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

<span id="write-data-lines"></span>
=== 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.

<span id="write-page-heading-r93-new-page"></span>
=== 1.4 Write — Page Heading (<code>r93-new-page</code>) ===

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

<span id="write-page-footing-r94-eop"></span>
=== 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) + &quot;page: &quot; + Z(3)9
ADD 1 TO page-number
SET print-new-page = 1                  → next write triggers new heading</pre>
<span id="close"></span>
=== 1.6 Close ===

Called by <code>r99-stop-primesui</code> when <code>ui-methods = &quot;stop&quot;</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>.


-----

<span id="console-output-scherm"></span>
== 2. Console Output — scherm ==

<span id="definition"></span>
=== 2.1 Definition ===

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

<span id="structured-log-messages-via-primesui"></span>
=== 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. &quot;primesmain          &quot;
program-paragraph PIC X(20)   e.g. &quot;r90-start-session   &quot;
program-message   PIC X(92)   e.g. &quot;UI initialisation succeeded.         ...&quot;</pre>
Every caller populates <code>program-name</code>, optionally <code>program-paragraph</code>, and always <code>program-message</code> before calling <code>primesui &quot;log-message&quot;</code>.

<span id="direct-display-statements-diagnostic-error"></span>
=== 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 &quot;Emergency console message…&quot; 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 &quot;select new-divider nok&quot; UPON scherm</code>
|
|-
| primes r83
| <code>DISPLAY SQLCODE UPON scherm</code>
| SQL error on insert
|-
| primes r83
| <code>DISPLAY &quot;primes.cbl insert next prime nok…&quot; UPON scherm</code>
|
|-
| primes s00
| <code>DISPLAY &quot;connect to database&quot; UPON scherm</code>
| Always shown on connect
|-
| primes s00
| <code>DISPLAY SQLCODE UPON scherm</code>
|
|-
| primes s99
| <code>DISPLAY &quot;s99 disconnect from database&quot; 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
|}


-----

<span id="database-io-primes.cbl-via-gixsql"></span>
== 3. Database I/O (primes.cbl via GixSQL) ==

<span id="connection-management"></span>
=== 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&amp;default_schema=primes</code><br />
Connection alias: <code>primes</code> (used in all <code>EXEC SQL AT primes</code> statements)

<span id="cursor-lifecycle-report-path-only"></span>
=== 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).

<span id="dml-generate-path"></span>
=== 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>.

<span id="queries-generate-path-divider-lookup"></span>
=== 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>.

<span id="error-handling-pattern"></span>
=== 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.


-----

<span id="command-line-input"></span>
== 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.


-----

<span id="known-io-defects"></span>
== 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]]