IO behaviour

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	fprinter
Physical name	primes.prt (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	primes-prt-status PIC X(2)

1.2 Open

Called by r90-start-primesui when ui-methods = "start":

OPEN OUTPUT fprinter

• Success: primes-prt-status = "00", ui-method-result = 0, primes-idx = 1.
• Failure: primes-prt-status ≠ "00", ui-method-result = 1, status displayed on console.

1.3 Write — Data Lines

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

MOVE primes-table TO print-buffer
WRITE file-buffer FROM print-buffer

One 132-character record is written per six prime entries. The record layout is:

[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

Each cell = 9 + 2 + 9 + 2 = 22 characters; 6 cells = 132 characters exactly.

1.4 Write — Page Heading (r93-new-page)

WRITE file-buffer FROM primes-heading    → "primes overview" (PIC X(118))
WRITE file-buffer FROM table-header      → "Sequence  Prime " × 6

Triggered by new-page flag = 1. Flag cleared after write.

1.5 Write — Page Footing (r94-eop)

Triggered when linage-counter = 53:

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

1.6 Close

Called by r99-stop-primesui when ui-methods = "stop":

CLOSE fprinter

Before close, a flush loop pads remaining cells with zeros until new-page fires, guaranteeing the last partial data line is written.

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

---

2. Console Output — scherm

2.1 Definition

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

2.2 Structured Log Messages (via primesui)

r98-message-ui in primesui:

DISPLAY process-message UPON scherm

process-message is a 132-character group:

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

Every caller populates program-name, optionally program-paragraph, and always program-message before calling primesui "log-message".

2.3 Direct DISPLAY Statements (diagnostic / error)

Several paragraphs bypass primesui and write directly to scherm:

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

---

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

3.1 Connection Management

Operation	SQL	Paragraph
Connect	CONNECT TO :DATASRC AS primes USER :DBUSR USING :DBPWD	s00-connect
Disconnect	CONNECT RESET primes	s99-disconnect

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

3.2 Cursor Lifecycle (report path only)

Operation	SQL	Paragraph
Declare	DECLARE primescursor CURSOR FOR SELECT * FROM primes	compile-time
Begin transaction	START TRANSACTION	s01-cursor
Open	OPEN primescursor	s01-cursor
Fetch one row	FETCH primescursor INTO :primes-row	s02-fetch
(Close)	not explicitly closed — connection reset closes it	—

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

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

3.3 DML (generate path)

Operation	SQL	Paragraph
Insert prime	INSERT INTO primes (prime) VALUES (:prime)	r83-write-prime

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

3.4 Queries (generate path — divider lookup)

Operation	SQL	Paragraph
Get next divider	SELECT prime INTO :test-divider FROM primes WHERE ident = :new-ident	r81-get-next-divider

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

3.5 Error Handling Pattern

Every SQL statement uses the same pattern:

EXEC SQL ... END-EXEC
IF SQLCODE = 0 THEN
  [success actions]
ELSE
  [log error / set result code]

No WHENEVER directives are used.

---

4. Command-Line Input

Program	Statement	Variable	Length
primesmain	ACCEPT commandline-args FROM COMMAND-LINE	commandline-args PIC X(32)	32 chars

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

---

5. Known I/O Defects

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

---

Terug naar: Primes_programs_specifications | Cobol and PostgreSQL