Editing Cobol and PostgreSQL

This chapter contains
* The description of a complete working example of a '''Cobol''' '''PostgreSQL''' program of the sample employee database, that comes with GixSQL
* The three tier object oriented <b>primes</b> program, using a PostgreSQL database.
GixSQL is the Open Source way in which Cobol programs are able to use modern database management systems in a Linux environment.
= Primes program =
A prime number is defined by the fact that it can only be divided by 1 and itself. The [[primes]] program is a simple program to demonstrate the implementation of a three tier object oriented Cobol program. It consists of:
* A main program to invoke the process
* A UI layer
* A business logic layer, that is responsible for the logic involving prime numbers
* Database layer, for data storage.
The subprograms are al invoked by means of methods, in such a way that the PostgreSQL database could easily be replaced by MariaDB.
== Making sense of IT ==
The Primes program is just a one off, written for demonstration purposes and on top of my head without design apart from a few notes on the edge of a news paper. Budget constraints put pressure on projects, time to market of features comes first, testing comes second and documentation in this day and age of program focused delivery at best comes last,
=== The forgotten design ===
Standards are lacking, because of political issues, time constraints and a too rapid pace of developments. Of course, there should have been a design, lacking standards, accidents or laziness are another cause of missing, insufficient or outdated documentation. It can go as bad as programs running in production of which nobody has a clue of what they are doing exactly, the only certainty is that things go wrong whenever the program goes wrong.</br>
I wrote the non nonsensical primes programs set on top of my head as an example three tier oriented system system, just to demonstrate the working of such a system. The challenge was to have some documentation at least, which is in line with the running joke in so many organisations: 'The program source is the best and most reliable source of information'. This is true under the condition that the program source is available, which is not always the case. There are loads of programs running in production today of which no one has a clue of what the program is doing, but everybody knows the program has to run to avoid problems. I did not go to the extend of re-engineering cobol source from the running executable (yet).
Thanks to [https://claude.ai Claude.ai]there is at least some documentation now.
* The primes system design [[Primes system Design]].
* Design standards [[Design standards]].
=== The forgotten documentation ===
On top of of the design and program specifications documents we require design standards and programming standards. The [[Cobol programming standards]] below have been generated in my hown grown ailab.
* The primes program specification [[Primes programs specifications]].
* One page [[Primes Software Specification]]
* Cobol programming standards [[Cobol programming standards]].
= Employee program =
The setup of the lab environment, source code and a simple compilation workflow are below.
* Program name: pgcobol
* Source code: pgcobol.cbl
* Intermediate preprocessed source code file: pgcobol.cbsql
* Cobol compiler output: pgcobol.out
* Database: Employee, with table emptable
* pgcobol print output file: pgcobol.prt
== Cobol ==
Cobol has been around for more than 60 years and will stay around for the foreseeable future, estimates are that there are about 800 billion lines of Business Cobol code around. The programs are heavily used, servicing about 80% of all financial and business transactions world wide.<br /><br />
The reason behind this endurance lies in the fact that Cobol is a standardised language, a program written in 1974 can be compiled today with a modern compiler. The resulting executable program still runs today, without the need of adaptation. This very fact is of high value to enterprises, their investments are safe and well protected on the long term.<br /><br />
Traditionally Cobol programs have their application in big business mainframe environments. These large enterprises, however, are shifting more and more of their applications to the Linux platform. The broad adoption of Linux in the enterprise environment started around 2010. So, it is no wonder that Cobol gradually is being made available for the Linux platform, enter [https://gnucobol.sourceforge.io/ GNUCobol].
=== GNUCobol ===
Is an Open Source Cobol compiler, the project originally started in 2002 [https://en.wikipedia.org/wiki/GnuCOBOL GNUCobol] as OpenCobol. GNUCobol now is a full blown Cobol compiler.

== GixSQL links PostgreSQL and Cobol ==
PostgreSQL is getting more and more traction around the world, also in the big enterprises. Big enterprises have ample reason to stick to their Cobol program stack, in which they invested huge amounts of money. So if PostgreSQL is to make it to the business applications of the big enterprises, it has to find a way to interact in a reliable manner with Cobol. Enter the [https://github.com/mridoni/gixsql GixSQL] SQL preprocessor for Cobol.
=== An SQL statement in Cobol ===
This is the way the SQL code is embedded in the Cobol program:
<pre>
           EXEC SQL
              CONNECT TO :DATASRC AS cobol_sql USER :DBUSR USING :DBPWD
           END-EXEC.
</pre>
The example shows the program making a connection to the database with the variables DATASRC, DBUSR and DBPWD.

= Practical introduction to GixSQL =
This chapter provides guidance to set up a working GixSQL for GNUCobol with PostgreSQL development environment.
== Prerequisites ==
* Debian 12
* GnuCobol4
* libmariadb-dev libmariadb-dev-compat libpq5 unixodbc libfmt9
* GixSQL, find the link below
* optionally the PostgreSQL database server on the same machine.
GixSQL is available here: [https://github.com/mridoni/gixsql/releases/download/v1.0.21dev/gixsql-debian-12-x64-1.0.21dev-1.deb GixSQL].
Just install the software in the sequence as described above and the system is ready to go.<br />
For reasons of convenience add the follow lines to /etx/profile:
<pre>
LD_DIRECTORY_PATH="/usr/local/src/gix/gixisql/runtime/libgixsql:/usr/local/src/gix/gixsql/common:/usr/local/src/gix/gixsql/common"
export LD_DIRECTORY_PATH
</pre>

== Workflow ==
Once the editing of the program is finished, the program has to be compiled. This is done in various steps, but this can also be done by using the Python script below. <br />
The steps are:
# The precompile process
# Inspect (but do not edit the output)
# The compilation process
# Inspect the compilation listing
# Run the program
== Simple Workflow script ==
The python script [[gixc.py]] implements the GixSQL Cobol compilation workflow. It is invoked with a single parameter, being the program_name suffixed by either 'cbl or 'cob'. People that like to get their hands dirty follow the two steps below.
=== gixsql precompilation ===
The command invoking the precompile process is as follows:<br/>
<pre>
/usr/bin/gixsql pgcobol.cbl pgcobol.cbsql -S -I . -e ".,*.cpy,*.CPY"
</pre>
The input file is pgcobol.cbl, the preprocessing output file is [[pgcobol.cbsql]]. It is very important to leave the cbsql file as is, because meddling with the file easily leads to errors in the next step of the workflow.<br /><br />
The result of the precompile step of the SQL stement above looks like this:
<pre>
GIXSQL*    EXEC SQL
GIXSQL*       CONNECT TO :DATASRC AS cobol_sql USER :DBUSR USING :DBPWD
GIXSQL*    END-EXEC.
GIXSQL     CALL STATIC "GIXSQLConnect" USING
GIXSQL         BY REFERENCE SQLCA
GIXSQL         BY REFERENCE DATASRC
GIXSQL         BY VALUE 64
GIXSQL         BY REFERENCE "cobol_sql" & x"00"
GIXSQL         BY VALUE 0
GIXSQL         BY REFERENCE x"00"
GIXSQL         BY VALUE 0
GIXSQL         BY REFERENCE DBUSR
GIXSQL         BY VALUE 64
GIXSQL         BY REFERENCE DBPWD
GIXSQL         BY VALUE 64
GIXSQL     END-CALL.
</pre>
The precompile program translated the SQL statement in to a standardised Cobol call.

=== The cobc GNUCobol compilation ===
The command invoking the precompile process is as follows:
<pre>
/usr/bin/cobc -x pgcobol.cbsql -l:libgixsql.so -T pgcobol.out
</pre>
This results in the executable program file '''pgcobol''' and the compilation listing [[pgcobol.out]].

== Sample Program ==
The sample program [[pgcobol.cbl]] makes use of the sample database: employee. When executed pgcobol puts out the file [[pgcobol.prt]].<br />
The pgcobol program file is available for download here: [https://wiki.webhuis.nl/images/pgcobol.cbl pgcobol.cbl ].

== Sample database ==
The [[employee database]] is a very simple database, with one table containing three lines. The pg_dump file is in the link.
<hr/>
Back to: [[voorpagina]]