Data-Dictionary

From Webhuis wiki
Revision as of 22:57, 24 March 2026 by Martin (talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

Data Dictionary[edit]

Document ID: PGCBL-DDD-001 · Version: 1.0 · Status: Approved · Last updated: 2026-03-17

← Technical Specification | Flow Diagrams →


Contents[edit]

  1. Conventions
  2. Control Blocks — Copybooks
  3. Working-Storage Variables
  4. Database Objects


Conventions[edit]

Symbol Meaning
PIC X(n) Alphanumeric, n characters
PIC 9(n) Unsigned packed decimal display, n digits
PIC S9(n) Signed packed decimal display, n digits
PIC 9(n)V9(m) Unsigned numeric with m implied decimal places (no decimal point stored)
PIC Z(n) Zero-suppressed display numeric, n digits
COMP-3 Packed-decimal binary storage (2 digits per byte + sign nibble)
COMP-5 Native binary integer (platform word size)
88 Condition-name — a boolean alias tested via IF <name> or WHEN <name>
— Not applicable (group item or 88-level)
⚠️ Known issue or deviation from standard

Level hierarchy used in this codebase: 

01  Group root
 03  Sub-group or elementary item
  05  Nested elementary item
   07  Doubly-nested elementary item
   49  Special level for variable-length groups (SQLERRM in SQLCA)
88  Condition-name (under any level)

1. Control Blocks — Copybooks[edit]

1.1 primes-session[edit]

Source file: primes-session.cpy

Included by: primesmain.cbl (WORKING-STORAGE) · primesgen.cbl (LINKAGE SECTION)
Purpose: Session-tier control block. primesmain sets methods; primesgen reads it and sets session-result.

Level Name PIC Usage Initial Description
01 primes-session — — — Root of session control block
03 methods X(32) DISPLAY — Method dispatch verb — set by primesmain before calling primesgen
88 report-primes — — "report" Run the cursor report path
88 generate-primes — — "generate" Run the sieve generation path
88 start-primes — — "start" Reserved — not used in current flow
88 stop-primes — — "stop" Reserved — not used in current flow
88 invalid-method — — "bad" Sentinel for unrecognised verb
03 session-result 9(2) DISPLAY 0 Outcome code written by primesgen
88 session-method-ok — — 0 Operation succeeded
88 session-method-nok — — 1 Operation failed
88 session-method-eof — — 9 End of data (cursor exhausted)

⚠️ session-method-eof (value 9) is never explicitly set in the current code. Fetch failure sets session-result = 1 (nok), not 9. See Technical Specification — Defect T7.

1.2 primes-dal[edit]

Source file: primes-dal.cpy

Included by: primesgen.cbl (WORKING-STORAGE, caller) · primes.cbl (LINKAGE SECTION, callee)
Purpose: DAL-tier control block. primesgen sets dal-methods and reads back dal-result and primes-data.

Level Name PIC Usage Initial Description
01 primes-dal — — — Root of DAL control block
03 dal-methods X(32) DISPLAY — Method dispatch verb
88 next-prime — — "next-prime" Fetch next row from open cursor
88 next-divider — — "next-divider" SELECT a prime by ident for use as trial divisor
88 write-prime — — "write" INSERT a confirmed prime into the table
88 db-cursor — — "cursor" START TRANSACTION and OPEN primescursor
88 db-connect — — "connect" Establish the PostgreSQL connection
88 db-disconnect — — "disconnect" Release the connection
88 invalid-method — — "bad" Sentinel for unrecognised verb
03 primes-data — — — Single-row data payload (one prime)
05 primes-sequence 9(9) DISPLAY — Row identity (ident) of the fetched prime
05 prime-number 9(9) DISPLAY — The prime value itself
03 dal-result 9(2) DISPLAY 0 Outcome code written by primes
88 dal-method-ok — — 0 Operation succeeded
88 dal-method-nok — — 1 Operation failed
88 dal-method-eof — — 99 Cursor exhausted (no more rows)


1.3 primes-ui[edit]

Source file: primes-ui.cpy

Included by: all four programs
Purpose: UI-tier control block. Any program sets ui-methods and process-message / u-primes, then calls primesui; primesui sets ui-method-result.

Level Name PIC Usage Initial Description
01 primes-ui — — — Root of UI control block
03 ui-methods X(32) DISPLAY — Method dispatch verb
88 write-ui — — "write" Add one prime row to the print buffer
88 message-ui — — "log-message" Write process-message to the console
88 start-ui — — "start" Open primes.prt
88 stop-ui — — "stop" Flush print buffer and close file
03 process-message — — — Structured 132-char console log record
05 program-name X(20) DISPLAY — Name of the calling program
05 program-line — — — Location within the calling program
07 program-paragraph X(20) DISPLAY — Name of the calling paragraph
07 program-message X(92) DISPLAY — Human-readable status or error text
03 u-primes — — — One prime row for the print writer
05 u-sequence 9(9) DISPLAY — Sequence number (ident) to write to print buffer
05 u-number 9(9) DISPLAY — Prime value to write to print buffer
03 ui-method-result 9(2) DISPLAY 0 Outcome code written by primesui
88 ui-method-ok — — 0 Operation succeeded
88 ui-method-nok — — 1 Operation failed

Console message layout (132 characters, left-to-right): 

┌──────────────────────┬──────────────────────┬────────────────────────────────────────────────────────────────────────────────────────────┐
│  program-name (20)   │ program-paragraph(20)│  program-message (92)                                                                      │
└──────────────────────┴──────────────────────┴────────────────────────────────────────────────────────────────────────────────────────────┘

1.4 primes-table — SQL Host Variable (character)[edit]

Source file: primes-table.cpy

Included by: primes.cbl via EXEC SQL INCLUDE primes-table END-EXEC
Purpose: Host variable layout for GixSQL to bind the primes.primes table columns.

Level Name PIC Usage Description
01 primes-table — — Host variable group (character format)
03 ident S9(9) DISPLAY Maps to primes.ident; signed for SQL compatibility
03 prime S9(9) DISPLAY Maps to primes.prime; signed for SQL compatibility


1.5 primes_table — SQL Host Variable (packed)[edit]

Source file: primes_table.cpy

Included by: primes.cbl (alternative layout)
Purpose: COMP-3 variant of primes-table. The underscore in both the filename and root name is a deviation from the project’s hyphen convention.

Level Name PIC Usage Description
01 primes_table — — Host variable group (COMP-3 format)
03 ident S9(9) COMP-3 Row identity — packed decimal
03 prime S9(9) COMP-3 Prime value — packed decimal

⚠️ Two nearly identical copybooks exist. primes-table.cpy (hyphens, DISPLAY) is used by the cursor FETCH target (primes-row). The canonical version should be designated and the other retired. See Technical Specification — Defect T6.

1.6 SQLCA — SQL Communications Area[edit]

Source file: SQLCA.cpy

Included by: primes.cbl via EXEC SQL INCLUDE SQLCA END-EXEC
Purpose: Standard GixSQL communications area. Updated after every SQL statement.

Level Name PIC Usage Description
01 SQLCA — — SQL communications area
05 SQLCAID X(8) DISPLAY SQLCA identifier string
05 SQLCABC S9(9) COMP-5 Byte length of SQLCA structure
05 SQLCODE S9(9) COMP-5 SQL return code: 0=success · negative=error · +100=not found
05 SQLERRM — — Error message group
49 SQLERRML S9(4) COMP-5 Length of error message text
49 SQLERRMC X(70) DISPLAY Error message text from the database engine
05 SQLERRP X(8) DISPLAY Error procedure name (not used in this application)
05 SQLERRD S9(9) OCCURS 6 COMP-5 Diagnostic array; SQLERRD(3) = number of rows processed
05 SQLWARN — — Warning flags group (not used in this application)
05 SQLSTATE X(5) DISPLAY ISO/ANSI SQL state code (5-char string)

SQLCODE reference (PostgreSQL / GixSQL):

Value Meaning
0 Statement succeeded
+100 No rows found (SELECT returned empty, cursor exhausted)
negative Database error — see SQLERRMC for description


2. Working-Storage Variables[edit]

2.1 primesmain[edit]

Source: primesmain.cbl WORKING-STORAGE SECTION

Copybooks included: primes-session · primes-ui

Name PIC Usage Initial Description
filler X(32) DISPLAY "Start WS primesmain" Debug marker — locates WS start in memory dumps
commandline-args X(32) DISPLAY — Command-line argument from ACCEPT … FROM COMMAND-LINE
execute-generate (88) — — "generate" True when commandline-args = “generate”
execute-report (88) — — "report" True when commandline-args = “report”
primes-session (group) — — COPY primes-session — see §1.1
primes-ui (group) — — COPY primes-ui — see §1.3


2.2 primesgen[edit]

Source: primesgen.cbl WORKING-STORAGE SECTION

Copybooks included: primes-ui (WS) · primes-dal (WS) · primes-session (LINKAGE)

Print control group (unused — print handled by primesui):

Name PIC Initial Description
file-buffer X(132) — FD record area for fprinter — declared but file never opened here ⚠️
print-buffer X(132) — Working print line buffer
line-number 99 99 Current line within page
page-number 9999 0 Current page number

Sieve control group (01 primes, local to primesgen):

Name PIC Initial Description
gen-methods X(32) — Verb for the local primes group calls to primes.cbl
query-process (88) — "query" Internal: query
start-process (88) — "start" Internal: start
next-divider (88) — "get" Internal: fetch next divider
write-prime (88) — "put" Internal: write prime
stop-process (88) — "stop" Internal: stop
primes-result 9(2) 0 Internal result code for local DAL calls
init-primes-ok (88) — 1 Initialisation succeeded
first-divider-ok (88) — 2 First divisor retrieved
next-divider-ok (88) — 3 Next divisor retrieved
test-number 9(9) — Current candidate being tested for primality
test-number-sqr 9(9)V9(9) — Square root of test-number — upper bound for divisors
test-divider 9(9) — Current trial divisor (prime fetched from DB)
test-rest 9(9)V9(9) — Remainder: test-number MOD test-divider
old-test-number 9(9) — Previous candidate — diagnostic use only, not active
old-ident 9(9) — DB ident of the most recently fetched divisor
new-ident 9(9) — old-ident + 1 — used as key for the next divider SELECT

Other:

Name PIC Initial Description
test-quot 9(9) — Integer quotient from DIVIDE test-number BY test-divider


2.3 primes (DAL)[edit]

Source: primes.cbl WORKING-STORAGE SECTION

Copybooks included: primes-ui (WS) · SQLCA (via EXEC SQL INCLUDE) · primes-table (via EXEC SQL INCLUDE) · primes-dal (LINKAGE)

Database credentials:

Name PIC Initial Description
DATASRC X(64) "pgsql://localhost:5432/primes&default_schema=primes" GixSQL connection string ⚠️ hard-coded
DBUSR X(64) "primes_user" Database user name ⚠️ hard-coded
DBPWD X(64) "pr1mes_user" Database password ⚠️ hard-coded in plain text
CUR-STEP X(16) — Diagnostic step label ("CONNECT" / "DISCONNECT")

Cursor fetch buffer:

Name PIC Usage Description
primes-row (group) — Target group for FETCH primescursor INTO :primes-row
r-ident 9(9) COMP-3 Fetched row identity value
r-prime 9(9) COMP-3 Fetched prime value

Unused declarations:

Name PIC Note
prime-count 9(9) Declared; not written to in current flow
prime_seq 9(9) Declared; not written to
divider 9(9) Declared; not written to

Local sieve control group (01 primes, mirrors primesgen layout):

Mirrors the 01 primes group in primesgen. Contains test-divider, old-ident, new-ident etc., used internally by r81-get-next-divider. See §2.2 for field descriptions.


2.4 primesui[edit]

Source: primesui.cbl WORKING-STORAGE SECTION

Copybooks included: primes-ui (LINKAGE)

Print row buffer:

Name PIC Usage Initial Description
primes-table (01) — — — 6-element row accumulator
primes-cel OCCURS 6 INDEXED primes-idx — — One cell = one prime entry in the output line
t-ident Z(9) DISPLAY — Zero-suppressed sequence number for this cell
filler X(2) DISPLAY spaces Column separator
t-prime Z(9) DISPLAY — Zero-suppressed prime value for this cell
filler X(2) DISPLAY spaces Column separator
primes-idx INDEX — — Current cell position (1–6); set by SET primes-idx

Column header:

Name PIC Description
table-header (01) OCCURS 6 Static header row — "Sequence Prime " repeated 6 times

Print control:

Name PIC Usage Initial Description
print-buffer X(132) DISPLAY — Working buffer written to fprinter
primes-prt-status X(2) DISPLAY — File status from last fprinter operation
page-number 9(4) DISPLAY 1 Current page number
print-new-page 9 DISPLAY 1 New-page flag — 1 = heading must be written
new-page (88) — — 1 True when print-new-page = 1

Static strings:

Name PIC Value Description
primes-heading X(118) "primes overview" Left-justified page heading text
primes-footing (group) — Page footer group
filler X(118) SPACE Left padding of footer
filler X(6) "page: " Footer label
f-page-number Z(3)9 1 Formatted page number (zero-suppressed 4-digit)

Unused:

Name PIC Note
primes-line X(132) Declared; not written to in current flow
primes-count 9(8) Declared; not used


3. Database Objects[edit]

3.1 Schema primes[edit]

Object Type Owner Description
primes SCHEMA primes_user Container schema for all application objects
asc_ident SEQUENCE primes_user Auto-incrementing identity for primes.ident
primes.primes TABLE primes_user The prime numbers store


3.2 Table primes.primes[edit]

DDL source: primes_schema.sql

<syntaxhighlight lang="sql">CREATE TABLE primes.primes ( 

   ident integer DEFAULT nextval('primes.asc_ident'::regclass),
   prime integer

);</syntaxhighlight>

Column Data type Nullable Default Description
ident INTEGER YES nextval('primes.asc_ident') Auto-assigned insertion sequence; acts as primary key but has no formal PK constraint
prime INTEGER YES — The prime number value

⚠️ No PRIMARY KEY, UNIQUE constraint, or index is defined on either column. The ident column is the key used by r81-get-next-divider (SELECT prime WHERE ident = :new-ident). Without an index, this is a sequential scan. See Technical Specification — Defect T5 (performance concern).

3.3 Sequence primes.asc_ident[edit]

Attribute Value
Data type INTEGER
Start value 1
Increment 1
Minimum 1 (default)
Maximum 2,147,483,647 (INTEGER max)
Cache 1
Cycle No


3.4 Cursor primescursor (runtime)[edit]

Declared at compile time in primes.cbl. Opened and used only in the report path.

Attribute Value
Declaration DECLARE primescursor CURSOR FOR SELECT * FROM primes
Connection alias primes
Declared at Compile time in primes.cbl
Transaction Opened inside START TRANSACTION in s01-cursor
Opened at s01-cursor paragraph (EXEC SQL OPEN primescursor)
Fetch target primes-row group (r-ident, r-prime) — COMP-3 fields
Close Not explicit; closed implicitly when CONNECT RESET primes is issued

⚠️ SELECT * FROM primes is used. Best practice is to name columns explicitly (SELECT ident, prime FROM primes) to guard against schema changes. The pre-compiler listing (primes_cbsql.out) shows this was expanded from a SELECT ident, prime form in an earlier version.

← Technical Specification | Flow Diagrams →

Retrieved from "https://wiki.webhuis.nl:443/index.php?title=Data-Dictionary&oldid=4703"