Chapter 6: Using COBSQL with Database Applications

COBSQL is an integrated preprocessor designed to work with COBOL precompilers supplied by relational database vendors. It is intended for use with:

Oracle Pro*COBOL Version 1.8
Oracle Pro*COBOL Version 8
Informix ESQL/COBOL version 7.3
Sybase Open Client Embedded SQL/COBOL Version 11

You should use COBSQL if you are creating applications that will be deployed on UNIX platforms and need to access either Oracle or Sybase relational databases.

6.1 Developing a Deployable Database Application

To create a database application using COBSQL on Net Express that can be deployed to a UNIX system, first set up database software:

Install the UNIX database server on the UNIX system. See the installation instructions for the database server for details.
Install the client software on both the PC and the UNIX deployment system. See the installation instructions for the database server for details. Ensure the database server and clients can communicate.
Prepare a new COBOL run-time system on the UNIX platform by linking in database libraries. Makefiles (or possibly shell scripts) are usually supplied with the database precompilers. These should be used to relink the COBOL run-time incorporating the database support modules. This should be done once for each database on each platform

You would normally only need to perform these steps once. If you install a new release of the COBOL system on UNIX, or update the database client, you will have to relink the COBOL run-time system with the database support modules.

Develop the database application using COBSQL and the database precompiler in Net Express. See the Database Access (DBpubb03.htm) book for more information on how to invoke COBSQL under Net Express. There are normally sample programs supplied with the database precompiler that show how to code a COBOL program using Embedded SQL statements. Animate or run the application on Net Express, and, when the application is working as expected, copy the database application to the UNIX system:

Add the file cobsql.dir to the source pool for your project. This file should contain all the COBSQL directives needed on UNIX. You need only do this once.
Click UNIX, Setup. Configure the Publisher as required for this project (see the chapter Publisher Set-up for details on setting-up Publisher). In particular, check Don't Build On Server. This specifies that Publisher should copy the project to the UNIX system, but not rebuild it.
Publish the project. The files are copied to the UNIX system, and a Makefile created, but the application is not rebuilt.
In the publish directory on the UNIX machine, copy the Makefile to a new file; for example, CSQLMakefile.
Alter the CSQLMakefile so that the command line used to compile a program includes the –k option and the –C"p(cobsql)" directive. For example:
```
Animtst1.int: Animtst1.pco

./mfenv.sh cob Animtst.pco
```
becomes:
```
Animtst1.int: Animtst1.pco

./mfenv.sh cob –k Animtst.pco –C"p(cobsql)"
```
Use make with this modified version of CSQLMakefile to create versions of the programs that can be debugged on the UNIX system.
Note: If required, once you have set up the CSQLMakefile correctly, you can use Publisher to automate this step. Publisher enables you to specify UNIX commands to be performed before a build takes place.
1. Click UNIX, Setup, Server, Settings, Prebuild
2. Enter the command make –f makefilename in the Pre-Build Command field. makefilename should be the name of your edited Makefile (in this example, CSQLMakefile).
  Click .
3. Click the Server tab, and check Don't Build On Server.
If you do this, then when you publish the project, the automatically-generated build will fail, but the build created using your makefile (CSQLMakefile in this example) will rebuild the application successfully.
Animate or run the application on the UNIX system.
Manually compare the results obtained by running the application on the UNIX system with those obtained by running the application under Net Express to verify that the application runs as expected.

6.2 UNIX Considerations

If you are developing an application on Net Express that you want to deploy on a UNIX system, you should note the following:

Under UNIX the normal extensions that the cob command takes are .cob and .cbl. To override the default extension, use the -k option before the filename. It is also possible to configure cob and add the .pco and .eco extensions to the list of default file extensions. Refer to the section on cob in your documentation for more details.
When passing directives to COBSQL via the cob command line, a directive which requires an equals sign (=) must be preceded by two equals signs. This is because cob removes a single equals sign and encloses the value that follows in brackets. When cob sees two equals signs, it strips out the first and leaves in the second to be passed to COBSQL. So, for example, to set the COBSQL directive:
```
COBSQLTYPE=ORACLE
```
enter:
```
COBSQLTYPE==ORACLE
```
This only applies to directives placed on the cob command line. It does not apply to directives in the cobsql.dir file.
The normal way to include database support is to re-link the COBOL run-time to create a new run-time. This new run-time should be used when running database applications.

Note: To be able to re-link the COBOL run-time a version of the "C" development system must be available on the machine.

The makefile to recreate the COBOL runtime is provided with the database precompiler. This makefile should include the database runtime support libraries plus the definition of the module names so that the new run-time can resolve the names of the database routines at exection time.
To animate using the new run-time, you should export the COBSW environment variable. This should be set to +A. To animate the application, enter:
```
new-run-time program-name
```
where new-run-time is the name of the re-linked run-time and program-name is the name of the application.
The following message is for information only, not a fatal error:
```
* CSQL-F-016: UNIX Exec error  Return Code is return code
```
This indicates that errors occurred and so the precompilation did not execute correctly.
If COBSQL cannot execute the precompiler, the following COBSQL error message is displayed and COBSQL terminates:
```
* CSQL-F-021: Precompiler did not complete -- Terminating
```

6.2.1 Example Command Lines

The following example shows the command lines required to compile a COBSQL program for Oracle under UNIX:

cob -a -v -k sample.pco -C "p(cobsql) cstop cobsqltype==ORACLE"

The following example shows the command lines required to compile a COBSQL program for Sybase under UNIX:

cob -a -v -P -k example1.pco -C"p(cobsql) nocst csp CSQLT==syb"

6.2.2 Error Messages

The following COBSQL error messages only appear on UNIX systems.

CSQL-F-002: Unable to connect with Micro Focus CDI2

As part of the initialisation process COBSQL tries to connect to the internal Micro Focus module CDI2. CDI2 provides COBSQL with CSI information about variables within the program being compiled. CDI2 is an integral part of the Toolbox or Object COBOL environment, so under normal execution it should always be present. This error would usually only be displayed if there are memory problems. Shutting down the Toolbox environment or the Object COBOL Development Environment Menu System, and restarting should clear the problem.

CSQL-F-016: UNIX Exec error Return Code is return-code

On UNIX this is NOT a fatal error. If a database precompiler finds errors in the source file, it is likely to produce a non-zero return code. Because this might happen, COBSQL will continue after displaying this message.

Importing UNIX Applications into Net Express

Tips and Troubleshooting