GnuCOBOL/DB2/Linux - Need help setting up

[dscobol]

I need some help.

I would like to be able to create COBOL programs that use embedded SQL commands to access a DB2 database in a Linux environment.

For some background:
I have a Windows 10 system that uses both the Cygwin and MingGW environments with GnuCOBOL to create, compile and run programs for both "normal" and "DB2" programs. It works fine.

I have an ArchLinux (ArcoLinux to be precise) system with GnuCOBOL installed and can create, compile and run "normal" COBOL programs.

Looking at the IBM website for DB2 Community Edition, Ubuntu 22.04 is supported.
I created an Ubuntu-Desktop VM, installed the DB2 Community Edition 11.5.8 (v11.5.8linuxx64_server_dec) as a root user and it works.
HOWEVER...
On Windows, within the SQLLIB directory, there are a couple of directories that are used for COBOL programs.
They are include/cobol_a, cobol_i, and cobol_mf
There is also a samples/cobol_mf directory which has sample programs to try.

Within the Ubuntu/DB2 V11.5.8 version, these directories are NOT present. I don't know why not.

So, I thought, let's try the Docker container version.
Install Docker and Docker Compose.
Download the image icr.io/db2_community/db2.
Per the IBM website:
Create the .env_list file with the parameters they suggest
Create the Docker compose file with the important part being the volume
- '.db2_home:/database'

Run the container, wait a long time (the first time) and it's up and running.

AND...
within the sqllib directory, the include and samples directories are present and contain the cobol_a, cobol_i and cobol_mf directories.

BUT...
The volume parameter will create a directory on the Host computer:
db2-home/config/db2inst1/
and within that is the sqllib directory
HOWEVER...
the include and the samples directories are symbolic links to /opt/ibm/db2/V11.5 in the container.
Which means on the Host computer, those directories are not available.
No include, No copybooks, No compile.

So, here are the questions:

1) Is it just me or is this "normal": Why are the cobol directories NOT in the /include directory on the Ubuntu install or the cobol_mf directory NOT in the /samples directory?
2) I sorely lack Docker knowledge and I did search and I did try a couple of things and failed but is there a way to connect the symbolic links to the sqllib directory?

For my purposes, an answer to #2 would be the best!
I already have the dev environment setup and to create shell scripts to export parameters or add to paths is not a problem.
But I am curious about #1.

[Simon Sobisch]

To answer #1 (and also get a hint at #2) it seems best if you could ask in IBMs discussion board for their project, then come back with the result.

[Mickey White]

Also you may want to look thru this post and see that Chuck H has posted a document that explains how he did DB2 on Windows.
https://sourceforge.net/p/gnucobol/discussion/cobol/thread/c758b7deb2/

[Simon Sobisch]

Mickey, you may have misunderstood the post. the OP says that he already have that working on win32 and now tries to do the same on GNU/Linux, but strangely necessary libraries seem to be missing (or only within a docker container).

[Mickey White]

Excuse please, not enough coffee this A.M.

[dscobol]

Update:

I did post a question in the IBM DB2 area about the Docker container issue but the post isn't visible yet. I guess it has to be reviewed first?

HOWEVER...

I was able to install DB2 LUW in a Ubuntu VM and have all the stuff that was missing.

I was doing a "Typical" install but I needed to do a "Custom" install then select "Base application development tools"

So as I write this:
DB2 LUW installed with COBOL includes and sample files
GnuCobol installed
Simple COBOL programs copied over and compiled and run

On the docket for tomorrow:
Install a development environment
Create the sample db in DB2
Copy over my basic DB2 programs and see if I can get them to bind, compile and run.

[dscobol]

Almost there but need a little more info.
On Windows, in the DB2 examples, there are two scripts; one for compile and one for running the exe.

I have the bind/compile script working(I think) but I am missing something for the run.

When I run the program I get:
libcob: error module 'sqlgstrt' not found.

In the run cmd on Windows:

set COB_LIBRARY_PATH=c:\IBM\SQLLIB\BIN
set COB_PRE_LOAD=db2agapi64

I can set the COB_LIBRARY_PATH
but db2agapi64 is not available in the bin folder on Linux as it is in Windows.

What is db2agapi64?
Do I really need that or is there something else in the Linux DB2 bin that I should use instead?

Or, am I missing something in the compile script?

PGM=SQTEST2
export SQLCOPY="$DB2_HOME/include/cobol_mf"
export COBCOPY="$SQLCOPY"
export LOADLIB="$DB2_HOME/lib64"

The DB2 bind stuff here

cobc -std=default -x -o $PGM $PGM.cbl -I $COBCOPY -L $LOADLIB -l db2

[Simon Sobisch]

I'd try to add

-K sqlgstrt

to cobc and see if compiling still works. If yes then you could preload libdb2, if you want the"old" way.

[dscobol]

Okay... First and foremost Yes! That did work! Thank You!

But... it brings up a big question.

The "If you want the "old" way" statement. Is there a new way?

I have been searching for days and the only examples I have seen are all for Windows, and those are what I used to get it up and running on Windows, especially the stuff by László Erdős .

There were some very terse posts on (I think) a Micro Focus website but they just said something "Customer complained about this so I fixed it for them"

I even looked through GitHub repos looking for Linux examples.

Can you point me to "The New Way"?

[Simon Sobisch]

With "new way" I've meant specifying the necessary entry points as static via command line option -K.
This is actually preferable to the preloading, but it doesn't work on Win 32 (at least not easily) because of stdcall related issues.

Chuck has made a presentation about DB2 on Windows, you may want to search for his notes, too.

What did you now go with on GNU/Linux? -K or preload?

[dscobol]

Actually, I think I found it and it was right in front of me the whole time.

cobc $PGM.cbl -static -Wall -I $COBCOPY -L $LOADLIB -l db2 -v -x -O

But, if you've seen a "better" way, I'll try it out.

[dscobol]

I think we were typing at the same time.

I added the -K to the compile and the COB_PRE_LOAD=libdb2 to the run and that worked.

Then I saw the cobc line from the DB2twilight blog post and said "let's try this again" and that worked.
I must have mis-typed it before as it didn't work a day or two ago so I looked for another example.

Then I took out the stuff I didn't want "-t xxx.lst and the -save-temps directive and that also worked.

OKAY...

Now, on to the next step.
All the files for this program are in one directory.
I will break out the files so they are in their own directory and then bring it all together in the shell script.

[Mickey White]

Where is ' -K ' defined or explained. What is it? I do not see it in the cobc --help compile list options.

[Vincent (Bryan) Coen]

On 27/02/2023 21:54, Mickey White wrote:

Where is ' -K ' defined or explained. What is it? I do not see it in
the cobc --help compile list options.

That's one of the secret  one's

So secret in fact that it is not listed in cobc/help.c

Or,  he is checking to see if you are awake :)

[Brian Tiffin]

...
  -A <options>          add <options> to the C compile phase
  -Q <options>          add <options> to the C link phase
  -D <define>           define <define> for COBOL compilation
  -K <entry>            generate CALL to <entry> as static
  ...

At least in trunk 4 pre-rel, and it was in 2.2.

https://gnucobol.sourceforge.io/faq/index.html#for-2-0-that-becomes

There might be plans to segment help in the 3.2 branch? Which would be cool, if help was all in or just the highlights sans the -f's and -w's.

From svn log --diff help.c (in cobc/) it looks like it happened at rev r4906, as a typo in an ordering change. svn log --diff file or the more rude svn blame filename subcommands are handy. But no blames. (Richard Hipp from Fossil uses praise as the subcommand. Then took heat for not being "what everyone's used to" and put in a blame alias, with a little sadness). ;-)

Have good,
Blue

[Simon Sobisch]

Actually svn --help shows that svn blame comes with the two aliases annotate (or ann) and praise :-)

[Vincent (Bryan) Coen]

These including the option -K are shown in the Programmers Reference and
the Programmers Guide manuals obtainable from the SF website under
Manuals and Guides at :

https://gnucobol.sourceforge.io/guides.html

and under section :

--

  GnuCOBOL Documentation

Start Here with Gary's Guide, Updated by Vincent Coen

It is just the help option in cobc that does not show the option -K in
v3.2 rc-2.
There again the option for -Xref is showing my cross reference tool and
not the internal one which is a more recent facility.

Personally I prefer mine as the output is more familiar to me from other
compiler cross reference outputs which take into account from Micro
Focus, IBM  and other mainframes I have used over the years.

Though I mostly use it to spot references not used (with a pinch of
salt) as data vars can be within records layouts and procedure
paragraphs / section names could be exits etc.

Useful to clean the code up after testing.

Vince

On 28/02/2023 03:08, Brian Tiffin wrote:

|... -A <options> add <options> to the C compile phase -Q <options>
add <options> to the C link phase -D <define> define <define> for
COBOL compilation -K <entry> generate CALL to <entry> as static ... |</entry></entry></define></define></options></options></options></options>

At least in trunk 4 pre-rel, and it was in 2.2.

https://gnucobol.sourceforge.io/faq/index.html#for-2-0-that-becomes

There might be plans to segment help in the 3.2 branch? Which would be
cool, if help was all in or just the highlights sans the -f's and -w's.

From |svn log --diff help.c| (in cobc/) it looks like it happened at
rev r4906, as a typo in an ordering change. |svn log --diff file| or
the more rude |svn blame filename| subcommands are handy. /But no
blames/. (Richard Hipp from Fossil uses |praise| as the subcommand.
Then took heat for not being "what everyone's used to" and put in a
|blame| alias, with a little sadness). ;-)

[Mickey White]

OK, I couldn't find it in the FAQ, either, as it is difficult to find just one letter that has a dash before it. thanks for the info.

[Simon Sobisch]

I've screwed [r4918], so "yay" for not pushing the 3.2 final yet (I likely need another week to tackle the pending bug reports). Fixed with [r5010].

[dscobol]

As another follow-up:
Still have not gotten a response about the "Docker/symbolic link" problem.
I'll have to do some "learning" about Docker to see if I can figure that out.

HOWEVER...

Thanks to help from Simon and others, I was able to write, compile and run GnuCOBOL/DB2 programs in a Gnu/Linux environment.

There is a GitHub repository and a Website to document my progress.

Thank You again! to all who helped me figure this out.

[Simon Sobisch]

Most interesting question for me: is there a place where you host the sources for the docs? It seems you only host the generated HTML pages. Note: while I'm not quite familiar with the process it seems you could place all the MD source files in a GH repo and use an GH action there to run MkDocs to generate the website content, then pushing that to the GH website - or just switch to "keep only MD" and "live generation" via https://readthedocs.io

Reading a bit into the docs;

• it confuses what GnuCOBOL does and what it doesn't; as a COBOL compiler it does not handle any SQL so you need to run the SQL preprocessor, and that may be limited with IBM DB2 LUW compared to IBM DB2 on AIX and/or zOS
• EXEC SQL INCLUDE should likely work in any case, so "making it compile" either would mean to "run dclgen" - if this is available on LUW, or manually create the copybooks
• most environments will place the connection details in either a file or read them from environment variables (also because many of those will run without user-input)
• you may want to have a look at "third version" of your compile script by defining a Makefile instead
• Any idea why you need i386 for your install?
• you may consider using SQL / COBOL source identifiers in your MD files to improve highlighting

[dscobol]

Documentation source and highlighting:
I do use MkDocs. The source is on my computer. MkDocs has a gh-deploy script which takes the site directory, builds it and then pushes it to the repo on GitHub.
I did update a lot of the md files to add "bash", "sql", or "cobol" to the 3 backtics but it seems "cobol" is not a supported language for markdown highlighting on GitHub. Or maybe that is something I need to fix in MkDocs. I'll look into that.

i386 for install:
I honestly don't know. Every installation guide/tutorial I read from IBM or other websites said it is required. I probably read the reason somewhere but I don't remember.

Makefile:
I'm familiar with them but I am kinda trying to emulate the environment on the Mainframe.
One "JCL" member to prep, bind, compile and link, another to run the program.

Environment variables:
I am also familiar with .env files (dev, test, stage, prod etc) and exporting variables in bash scripts.

DB2 LUW seems to be a little different and I learned that from the examples by László Erdős. In his examples, he uses the screen program to prompt the user for data and with that, the userid and password are entered and passed through the Linkage Section to the program and used to connect to the DB.

In the programs I wrote that run on Windows using his examples as a base, I have the following note:

      *    There are some differences between the GnuCOBOL and 
      *       ZOS DB2 programs.
      *
      *    The biggest difference is the 9800-Connect-to-DB1 paragraph.
      *
      *    On ZOS, the JCL makes the connection so there is no need for
      *       passing the username and password for the database.

László used LNMOD1 to pass the parameters into the program, I created a static program.

I will continue to explore this but my understanding is zOS/DB2: JCL/RACF handles the permissions. DB2 LUW: need to pass the parameters to verify permission.
But, I will look into this more.

DCLGEN, INCLUDE and the SQL Precompiler:
DCLGEN creates a copybook that has a EXEC SQL DECLARE statement for the table definition and an 01- record (but not within a EXEC SQL DECLARE statement) for the COBOL host variables.

When a program is precompiled, the INCLUDE statement is replaced by source statements.

I read this as: INCLUDE is the "SQL EXEC" version of COBOL's COPY statement but it happens in the precompile step.

There is a db2dclgn command included with IBM DB2 LUW but it does not generate the table definition at all so also not within a "EXEC SQL DECLARE" statement. It only defines the COBOL host variables, also not within a "EXEC SQL DECLARE" statement.

But, here is another note in the Windows programs:

*******************
      *    This is another BIG difference between GnuCOBOL
      *    and ZOS. If the Host Variables are not DECLAREd
      *    in GnuCOBOL, it is an error and it won't bind.
      *    On ZOS, DECLAREing them is not required and if 
      *    present, will cause a Warning(RC=04) for the compile.

This is probably something else that I discovered creating the programs on Windows.

As far as

it confuses what GnuCOBOL does and what it doesn't; as a COBOL compiler it does not handle any SQL so you need to run the SQL preprocessor, and that may be limited with IBM DB2 LUW compared to IBM DB2 on AIX and/or zOS

I think I wrote the docs with a mindset of "document how to get a 'Gnu/Linux-GnuCOBOL-IBM DB2 LUW' environment up and running"

I do put notes in the compile scripts to describe what is happening:
"# DB2 Prep and Bind" and "# Compile" but...

I could/should write something that describes the "phases" going from source code to executable and what is doing what to what.

[Simon Sobisch]

I do use MkDocs. The source is on my computer. MkDocs has a gh-deploy script which takes the site directory, builds it and then pushes it to the repo on GitHub.

Why not putting the source on GitHub and let a GH action create the docs "online" - or let readthedocs do that and drop the semi-/manual generation?

Environment variables

Yes the difference is where the setup is done with LUW - but I think it is more reasonable to ACCEPT dbname FROM ENVIRONMENT 'db2name' (or query something like DB2CONNECT and UNSTRING dbconnect DELIMITED BY '@' INTO db2user db2name. You can then set those up in a shell/bat file that dos the setup "similar to JCL".

mindset of "document how to get a 'Gnu/Linux-GnuCOBOL-IBM DB2 LUW' environment up and running"

exactly the quote:

      *    This is another BIG difference between GnuCOBOL
      *    and ZOS. If the Host Variables are not DECLAREd
      *    in GnuCOBOL, it is an error and it won't bind.

This is not GnuCOBOL, but the preprocessor (LUW) that errors / not create the fields accordingly. I think there were ore similar statements in the docs.

[dscobol]

Source for documentation:
I've always just kept the source on my computer.
I've used MkDocs, Nikola, and some other website generator tools.
I build it and then push the build to the website, whether it be GitHub pages or to a "regular" website.

Variables:
That is something I will look into and implement.
"Might not be the "BEST" way but it is "A" way."

Whose fault is it:
I've changed that comment in the code to:

      *******************
      *    This is another difference between DB2 LUW
      *    and zOS DB2.
      * 
      *    With DB2 LUW, if the Host Variables are not DECLAREd
      *    in the code, it is an error and it won't bind.
      *
      *    With zOS DB2, DECLAREing them is not required and if 
      *    present, will cause a Warning(RC=04) for the compile.

[dscobol]

I have updated all the GnuCOBOL/DB2 programs and documentation to use ACCEPT FROM ENVIRONMENT instead of GETDBID.

There is a GitHub repository and a Website to document my progress.