Editing Data-Dictionary (section)

== 1. Control Blocks — Copybooks ==

<span id="primes-session"></span>
=== 1.1 primes-session ===

<blockquote>'''Source file:''' <code>primes-session.cpy</code><br />
'''Included by:''' <code>primesmain.cbl</code> (WORKING-STORAGE) · <code>primesgen.cbl</code> (LINKAGE SECTION)<br />
'''Purpose:''' Session-tier control block. primesmain sets <code>methods</code>; primesgen reads it and sets <code>session-result</code>.
</blockquote>
{|
!width="16%"| Level
!width="16%"| Name
!width="16%"| PIC
!width="16%"| Usage
!width="16%"| Initial
!width="16%"| Description
|-
| 01
| <code>primes-session</code>
| —
| —
| —
| Root of session control block
|-
| 03
| <code>methods</code>
| <code>X(32)</code>
| DISPLAY
| —
| Method dispatch verb — set by primesmain before calling primesgen
|-
| 88
| <code>report-primes</code>
| —
| —
| <code>&quot;report&quot;</code>
| Run the cursor report path
|-
| 88
| <code>generate-primes</code>
| —
| —
| <code>&quot;generate&quot;</code>
| Run the sieve generation path
|-
| 88
| <code>start-primes</code>
| —
| —
| <code>&quot;start&quot;</code>
| Reserved — not used in current flow
|-
| 88
| <code>stop-primes</code>
| —
| —
| <code>&quot;stop&quot;</code>
| Reserved — not used in current flow
|-
| 88
| <code>invalid-method</code>
| —
| —
| <code>&quot;bad&quot;</code>
| Sentinel for unrecognised verb
|-
| 03
| <code>session-result</code>
| <code>9(2)</code>
| DISPLAY
| 0
| Outcome code written by primesgen
|-
| 88
| <code>session-method-ok</code>
| —
| —
| 0
| Operation succeeded
|-
| 88
| <code>session-method-nok</code>
| —
| —
| 1
| Operation failed
|-
| 88
| <code>session-method-eof</code>
| —
| —
| 9
| End of data (cursor exhausted)
|}

<blockquote>⚠️ <code>session-method-eof</code> (value 9) is never explicitly set in the current code. Fetch failure sets <code>session-result = 1</code> (nok), not 9. See [[Technical-Specification#7-known-technical-issues|Technical Specification — Defect T7]].
</blockquote>

-----

<span id="primes-dal"></span>
=== 1.2 primes-dal ===

<blockquote>'''Source file:''' <code>primes-dal.cpy</code><br />
'''Included by:''' <code>primesgen.cbl</code> (WORKING-STORAGE, caller) · <code>primes.cbl</code> (LINKAGE SECTION, callee)<br />
'''Purpose:''' DAL-tier control block. primesgen sets <code>dal-methods</code> and reads back <code>dal-result</code> and <code>primes-data</code>.
</blockquote>
{|
!width="16%"| Level
!width="16%"| Name
!width="16%"| PIC
!width="16%"| Usage
!width="16%"| Initial
!width="16%"| Description
|-
| 01
| <code>primes-dal</code>
| —
| —
| —
| Root of DAL control block
|-
| 03
| <code>dal-methods</code>
| <code>X(32)</code>
| DISPLAY
| —
| Method dispatch verb
|-
| 88
| <code>next-prime</code>
| —
| —
| <code>&quot;next-prime&quot;</code>
| Fetch next row from open cursor
|-
| 88
| <code>next-divider</code>
| —
| —
| <code>&quot;next-divider&quot;</code>
| SELECT a prime by ident for use as trial divisor
|-
| 88
| <code>write-prime</code>
| —
| —
| <code>&quot;write&quot;</code>
| INSERT a confirmed prime into the table
|-
| 88
| <code>db-cursor</code>
| —
| —
| <code>&quot;cursor&quot;</code>
| START TRANSACTION and OPEN primescursor
|-
| 88
| <code>db-connect</code>
| —
| —
| <code>&quot;connect&quot;</code>
| Establish the PostgreSQL connection
|-
| 88
| <code>db-disconnect</code>
| —
| —
| <code>&quot;disconnect&quot;</code>
| Release the connection
|-
| 88
| <code>invalid-method</code>
| —
| —
| <code>&quot;bad&quot;</code>
| Sentinel for unrecognised verb
|-
| 03
| <code>primes-data</code>
| —
| —
| —
| Single-row data payload (one prime)
|-
| 05
| <code>primes-sequence</code>
| <code>9(9)</code>
| DISPLAY
| —
| Row identity (<code>ident</code>) of the fetched prime
|-
| 05
| <code>prime-number</code>
| <code>9(9)</code>
| DISPLAY
| —
| The prime value itself
|-
| 03
| <code>dal-result</code>
| <code>9(2)</code>
| DISPLAY
| 0
| Outcome code written by primes
|-
| 88
| <code>dal-method-ok</code>
| —
| —
| 0
| Operation succeeded
|-
| 88
| <code>dal-method-nok</code>
| —
| —
| 1
| Operation failed
|-
| 88
| <code>dal-method-eof</code>
| —
| —
| 99
| Cursor exhausted (no more rows)
|}


-----

<span id="primes-ui"></span>
=== 1.3 primes-ui ===

<blockquote>'''Source file:''' <code>primes-ui.cpy</code><br />
'''Included by:''' all four programs<br />
'''Purpose:''' UI-tier control block. Any program sets <code>ui-methods</code> and <code>process-message</code> / <code>u-primes</code>, then calls primesui; primesui sets <code>ui-method-result</code>.
</blockquote>
{|
!width="16%"| Level
!width="16%"| Name
!width="16%"| PIC
!width="16%"| Usage
!width="16%"| Initial
!width="16%"| Description
|-
| 01
| <code>primes-ui</code>
| —
| —
| —
| Root of UI control block
|-
| 03
| <code>ui-methods</code>
| <code>X(32)</code>
| DISPLAY
| —
| Method dispatch verb
|-
| 88
| <code>write-ui</code>
| —
| —
| <code>&quot;write&quot;</code>
| Add one prime row to the print buffer
|-
| 88
| <code>message-ui</code>
| —
| —
| <code>&quot;log-message&quot;</code>
| Write <code>process-message</code> to the console
|-
| 88
| <code>start-ui</code>
| —
| —
| <code>&quot;start&quot;</code>
| Open <code>primes.prt</code>
|-
| 88
| <code>stop-ui</code>
| —
| —
| <code>&quot;stop&quot;</code>
| Flush print buffer and close file
|-
| 03
| <code>process-message</code>
| —
| —
| —
| Structured 132-char console log record
|-
| 05
| <code>program-name</code>
| <code>X(20)</code>
| DISPLAY
| —
| Name of the calling program
|-
| 05
| <code>program-line</code>
| —
| —
| —
| Location within the calling program
|-
| 07
| <code>program-paragraph</code>
| <code>X(20)</code>
| DISPLAY
| —
| Name of the calling paragraph
|-
| 07
| <code>program-message</code>
| <code>X(92)</code>
| DISPLAY
| —
| Human-readable status or error text
|-
| 03
| <code>u-primes</code>
| —
| —
| —
| One prime row for the print writer
|-
| 05
| <code>u-sequence</code>
| <code>9(9)</code>
| DISPLAY
| —
| Sequence number (ident) to write to print buffer
|-
| 05
| <code>u-number</code>
| <code>9(9)</code>
| DISPLAY
| —
| Prime value to write to print buffer
|-
| 03
| <code>ui-method-result</code>
| <code>9(2)</code>
| DISPLAY
| 0
| Outcome code written by primesui
|-
| 88
| <code>ui-method-ok</code>
| —
| —
| 0
| Operation succeeded
|-
| 88
| <code>ui-method-nok</code>
| —
| —
| 1
| Operation failed
|}

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

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

-----

<span id="primes-table-sql-host-variable-character"></span>
=== 1.4 primes-table — SQL Host Variable (character) ===

<blockquote>'''Source file:''' <code>primes-table.cpy</code><br />
'''Included by:''' <code>primes.cbl</code> via <code>EXEC SQL INCLUDE primes-table END-EXEC</code><br />
'''Purpose:''' Host variable layout for GixSQL to bind the <code>primes.primes</code> table columns.
</blockquote>
{|
!width="20%"| Level
!width="20%"| Name
!width="20%"| PIC
!width="20%"| Usage
!width="20%"| Description
|-
| 01
| <code>primes-table</code>
| —
| —
| Host variable group (character format)
|-
| 03
| <code>ident</code>
| <code>S9(9)</code>
| DISPLAY
| Maps to <code>primes.ident</code>; signed for SQL compatibility
|-
| 03
| <code>prime</code>
| <code>S9(9)</code>
| DISPLAY
| Maps to <code>primes.prime</code>; signed for SQL compatibility
|}


-----

<span id="primes_table-sql-host-variable-packed"></span>
=== 1.5 primes_table — SQL Host Variable (packed) ===

<blockquote>'''Source file:''' <code>primes_table.cpy</code><br />
'''Included by:''' <code>primes.cbl</code> (alternative layout)<br />
'''Purpose:''' COMP-3 variant of <code>primes-table</code>. The underscore in both the filename and root name is a deviation from the project’s hyphen convention.
</blockquote>
{|
! Level
! Name
! PIC
! Usage
! Description
|-
| 01
| <code>primes_table</code>
| —
| —
| Host variable group (COMP-3 format)
|-
| 03
| <code>ident</code>
| <code>S9(9)</code>
| COMP-3
| Row identity — packed decimal
|-
| 03
| <code>prime</code>
| <code>S9(9)</code>
| COMP-3
| Prime value — packed decimal
|}

<blockquote>⚠️ Two nearly identical copybooks exist. <code>primes-table.cpy</code> (hyphens, DISPLAY) is used by the cursor FETCH target (<code>primes-row</code>). The canonical version should be designated and the other retired. See [[Technical-Specification#7-known-technical-issues|Technical Specification — Defect T6]].
</blockquote>

-----

<span id="sqlca-sql-communications-area"></span>
=== 1.6 SQLCA — SQL Communications Area ===

<blockquote>'''Source file:''' <code>SQLCA.cpy</code><br />
'''Included by:''' <code>primes.cbl</code> via <code>EXEC SQL INCLUDE SQLCA END-EXEC</code><br />
'''Purpose:''' Standard GixSQL communications area. Updated after every SQL statement.
</blockquote>
{|
!width="20%"| Level
!width="20%"| Name
!width="20%"| PIC
!width="20%"| Usage
!width="20%"| Description
|-
| 01
| <code>SQLCA</code>
| —
| —
| SQL communications area
|-
| 05
| <code>SQLCAID</code>
| <code>X(8)</code>
| DISPLAY
| SQLCA identifier string
|-
| 05
| <code>SQLCABC</code>
| <code>S9(9)</code>
| COMP-5
| Byte length of SQLCA structure
|-
| 05
| <code>SQLCODE</code>
| <code>S9(9)</code>
| COMP-5
| '''SQL return code:''' 0=success · negative=error · +100=not found
|-
| 05
| <code>SQLERRM</code>
| —
| —
| Error message group
|-
| 49
| <code>SQLERRML</code>
| <code>S9(4)</code>
| COMP-5
| Length of error message text
|-
| 49
| <code>SQLERRMC</code>
| <code>X(70)</code>
| DISPLAY
| Error message text from the database engine
|-
| 05
| <code>SQLERRP</code>
| <code>X(8)</code>
| DISPLAY
| Error procedure name (not used in this application)
|-
| 05
| <code>SQLERRD</code>
| <code>S9(9)</code> OCCURS 6
| COMP-5
| Diagnostic array; <code>SQLERRD(3)</code> = number of rows processed
|-
| 05
| <code>SQLWARN</code>
| —
| —
| Warning flags group (not used in this application)
|-
| 05
| <code>SQLSTATE</code>
| <code>X(5)</code>
| 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 <code>SQLERRMC</code> for description
|}


-----

<span id="working-storage-variables"></span>