Editing Primes Software Specification (section)

== 1. Business Requirements Document ==

<span id="purpose"></span>
=== 1.1 Purpose ===

<code>Primes.cbsql</code> is a COBOL Data Access Layer (DAL) module that manages persistent storage of prime numbers in a PostgreSQL database. It is not a standalone program; it is invoked by a calling driver program that selects the desired operation via a shared linkage interface (<code>primes-dal</code>).

<span id="scope"></span>
=== 1.2 Scope ===

The module handles all database interactions for the prime number generation system, including connection lifecycle management, cursor-based sequential reads, row-by-row prime retrieval for trial division, and insertion of newly discovered primes.

<span id="system-context"></span>
=== 1.3 System Context ===

{|
! Item
! Value
|-
| '''Platform'''
| Linux (GnuCOBOL + GixSQL)
|-
| '''Database'''
| PostgreSQL 5432 @ localhost
|-
| '''Schema'''
| <code>primes</code>
|-
| '''Database name'''
| <code>primes</code>
|-
| '''DB user'''
| <code>primes_user</code>
|-
| '''UI module'''
| <code>primesui</code> (called for all status messages)
|-
| '''Linkage interface'''
| <code>primes-dal</code> (copybook)
|}

<span id="business-functions"></span>
=== 1.4 Business Functions ===

{|
!width="33%"| ID
!width="33%"| Method Flag
!width="33%"| Description
|-
| BF-01
| <code>db-connect</code>
| Establish a connection to the PostgreSQL database
|-
| BF-02
| <code>db-cursor</code>
| Begin a transaction and open a cursor for reading all primes
|-
| BF-03
| <code>next-prime</code>
| Fetch the next prime row from the open cursor
|-
| BF-04
| <code>next-divider</code>
| Retrieve a specific prime by identity index to use as a trial divisor
|-
| BF-05
| <code>write-prime</code>
| Insert a newly proven prime into the database
|-
| BF-06
| <code>db-disconnect</code>
| Close the database connection and release resources
|}

<span id="business-rules"></span>
=== 1.5 Business Rules ===

{|
!width="50%"| ID
!width="50%"| Rule
|-
| BR-01
| The initial prime value <code>2</code> is inserted as a seed record during first-run initialisation (<code>r90-generate-primes</code>)
|-
| BR-02
| All operations must set <code>dal-result</code> to <code>0</code> on success or <code>1</code> on failure
|-
| BR-03
| All status messages (success and error) must be routed through the <code>primesui</code> subprogram
|-
| BR-04
| Raw SQL error codes (<code>SQLCODE</code>) must be displayed to the console on failure
|-
| BR-05
| Trial division uses stored primes up to the square root of the candidate number
|}

<span id="assumptions-and-constraints"></span>
=== 1.6 Assumptions and Constraints ===

* The database schema and table (<code>primes.primes</code>) must exist prior to program execution.
* The calling program is responsible for managing the sequence of DAL method calls.
* <code>r90-generate-primes</code> (seed insertion) is not reachable via the DAL dispatch and must be called directly during initial setup.


-----

<span id="technical-specification-pseudocode"></span>