Latest revision as of 22:57, 24 March 2026

Data Dictionary[edit]

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

← Technical Specification | Flow Diagrams →

Contents[edit]

Conventions
Control Blocks — Copybooks
Working-Storage Variables
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 →

Data-Dictionary: Difference between revisions

Latest revision as of 22:57, 24 March 2026

Contents

Data Dictionary[edit]

Contents[edit]

Conventions[edit]

1. Control Blocks — Copybooks[edit]

1.1 primes-session[edit]

1.2 primes-dal[edit]

1.3 primes-ui[edit]

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

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

1.6 SQLCA — SQL Communications Area[edit]

2. Working-Storage Variables[edit]

2.1 primesmain[edit]

2.2 primesgen[edit]

2.3 primes (DAL)[edit]

2.4 primesui[edit]

3. Database Objects[edit]

3.1 Schema `primes`[edit]

3.2 Table `primes.primes`[edit]

3.3 Sequence `primes.asc_ident`[edit]

3.4 Cursor `primescursor` (runtime)[edit]

Navigation menu

Data-Dictionary: Difference between revisions

Latest revision as of 22:57, 24 March 2026

Data Dictionary[edit]

Contents[edit]

Conventions[edit]

1. Control Blocks — Copybooks[edit]

1.1 primes-session[edit]

1.2 primes-dal[edit]

1.3 primes-ui[edit]

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

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

1.6 SQLCA — SQL Communications Area[edit]

2. Working-Storage Variables[edit]

2.1 primesmain[edit]

2.2 primesgen[edit]

2.3 primes (DAL)[edit]

2.4 primesui[edit]

3. Database Objects[edit]

3.1 Schema primes[edit]

3.2 Table primes.primes[edit]

3.3 Sequence primes.asc_ident[edit]

3.4 Cursor primescursor (runtime)[edit]

Navigation menu

Search

3.1 Schema `primes`[edit]

3.2 Table `primes.primes`[edit]

3.3 Sequence `primes.asc_ident`[edit]

3.4 Cursor `primescursor` (runtime)[edit]