PreviousSQL Option for DB2

Chapter 11: COBSQL

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

You should use COBSQL if you are already using either of these precompilers with an earlier version of a Micro Focus COBOL product and want to migrate your application(s) to Net Express, or if you are creating applications that will be deployed on UNIX platforms and need to access either Oracle or Sybase relational databases.

For any other type of embedded SQL application development, we recommend that you use OpenESQL.

Note: The Oracle Version 1.8 precompiler does not support nested programs. COBSQL does not support Object Oriented COBOL syntax (OO COBOL). If you want to use OO COBOL, therefore, you must use OpenESQL.

11.1 Overview

You can access the SQL functions offered by the Oracle, Sybase or Informix Database Management System (DBMS) by embedding SQL statements within your COBOL program in the form:

   SQL statement

and then using the Oracle, Sybase or Informix precompiler to process the embedded SQL before passing the program to the COBOL Compiler. The database precompiler replaces embedded SQL statements with the appropriate calls to database services. Other additions are made to the source code to bind COBOL host variables to the SQL variable names known to the database system.

The advantage of embedding SQL in this way is that you do not need to know the format of individual database routine calls. The disadvantage is that the source code that you see when you animate your program is that output by the precompiler and not the original embedded SQL. You can overcome this disadvantage by using COBSQL.

COBSQL provides an integrated interface between Micro Focus COBOL and the third-party standalone precompiler, enabling you to animate a program containing EXEC SQL statements and display your original source code rather than the code produced by the precompiler.

This chapter shows you how you can use COBSQL in conjunction with either the Oracle, Sybase or Informix precompiler to compile and animate your programs.

11.2 Operation

To use COBSQL, specify the PREPROCESS"COBSQL" Compiler directive when you compile your program. All directives following it are passed from the Compiler to COBSQL. You can specify Compiler directives by using $SET statements in your program or via the Net Express Build Settings screen.

To terminate the directives to be passed to COBSQL, you must use the ENDP COBOL directive. You can do this by adding the following line either to the project settings or to the end of the Net Express Build settings:

Preprocess(Cobsql) csqltype=database_product end-c comp5=yes endp;

where database_product is one of Oracle, Sybase or Informix. For example, for Oracle:

Preprocess(Cobsql) csqltype=oracle end-c comp5=yes endp;

Note: Net Express ignores any directives placed after the semi-colon (;) in the Build settings. Therefore, if you add the above line to the Build settings, you must position the line at the end of the settings.

Since the system sets extra default Cobol directives, the above line is required when putting directives into the Build Settings dialog from within Net Express.

For both project settings and Net Express Build settings, END-C and ENDP have the following effect:

11.2.1 Specifying Directives

You specify directives to COBSQL as if they were Compiler directives, but you must put them after the directive PREPROCESS"COBSQL".

It is also possible to add the Cobsql directives to the standard Net Express directives file cobol.dir.


Alternatively, you can put COBSQL and precompiler directives in a file, cobsql.dir. This file should reside either in the current directory or in a directory specified in $COBDIR. COBSQL searches the current directory and then along the COBDIR path for a cobsql.dir file. Once COBSQL finds a cobsql.dir file, it stops searching. So, if you have a cobsql.dir file in the current directory, the COBDIR path is not searched.


COBSQL processes cobsql.dir first and then any directives specified via the Build Settings screen.

A number of the directives can be reversed by placing NO in front of them, for example, DISPLAY can be reversed using NODISPLAY. All the directives in the lists below that can have NO placed in front of them are marked with an asterisk. By default, the NO version of a directive is set.

You can specify shortened versions of some of the directives. If applicable, the shortened version of a directive is shown in the lists below, immediately after the full length version.

Some directives can be passed to COBSQL by the COBOL Compiler (see the section COBOL Directives), removing the need to specify common directives more than once. Directives that can be retrieved from the COBOL Compiler are processed before COBSQL directives.

For example, in the following command line:

cobol testprog p(cobsql) csqlt=ora makesyn end-c comp5=yes 
   mode=ansi endp omf(gnt) list();

11.2.2 COBSQL Directives

The following is a list of the COBSQL directives:

Specifies which precompiler to use (ORACLE, SYBASE or INFORMIX-NEW); for example, COBSQLTYPE=ORACLE .
Forces COBSQL to load the database support modules at execution time
Forces COBSQL to load the stop run module that performs a rollback if the application terminates abnormally
Creates a debug (.deb) file
Displays precompiler statistics. Should only be used when initially verifying that COBSQL is correctly calling the standalone precompiler.
Signals the end of COBSQL directives; remaining directives, if any, are passed to the precompiler
KEEPCBL Saves precompiled source file (.cbl)
MAKESYN Converts all COMP host variables to COMP-5 host variables. The default situation, if MAKESYN is not set, is that all variables (not just host variables) are converted from COMP to COMP-5.
NOMAKESYN No conversion of COMP-5 variables or host variables is carried out
SQLDEBUG Creates a number of files that can be used by Micro Focus to debug COBSQL. These files include the output file from the precompiler (normally this has a .cbl extension), the listing file produced by the precompiler (this has a .lis extension), plus a COBSQL debug file which has a .sdb extension. SQLDEBUG will also turn on KEEPCBL and TRACE.
TRACE* Creates a trace file (.trc)
VERBOSE Displays all precompiler messages and gives status updates as the program is processed. You should only use this when initially verifying that COBSQL is calling the standalone precompiler correctly.

11.2.3 COBOL Directives

The following is a list of the COBOL directives:

BELL* Controls whether COBSQL sounds the bell when an error occurs.
BRIEF* Controls whether COBSQL shows SQL error text as well as the error number.
CONFIRM* Displays accepted/rejected COBSQL directives.
LIST* Saves the precompiler listing file (.lis).
WARNING* Determines the lowest severity of SQL errors to report.

11.3 Building COBSQL Applications

It is beyond the scope of this document to list the database support modules that are required when shipping on a COBSQL application. It is assumed that the end-user machine already has all the required support modules installed and that it is correctly configured to communicate with the database server.

When linking COBSQL applications, use the import library csqlsupp.lib. This resolves the calls inserted by COBSQL to the COBSQL init and stop run modules. The calls are actually handled by the module csqlsupp.dll which needs to be shipped with the application. This general support module is required for both Oracle and Sybase applications.

Specify the library csqlsupp.lib as one of the libraries to use when linking the application. The library csqlsupp.lib resides in the directory Net Express\base\lib. The module csqlsupp.dll resides in the directory Net Express\base\bin.

If you split the application into a main exe and a number of sub DLL's, then you only need to link csqlsupp.lib into the modules that you have compiled with the COBSQL directives CSTART or CSTOP.

If you compile all programs with CSTART or CSTOP, then you must link csqlsupp.lib into all the modules. Linking csqlsupp.lib to each module causes each module to be slightly larger than required. Only one version of csqlsupp.dll is loaded when the application runs.

If you compile the main program only with CSTART and CSTOP, then you need to link in the library csqlsupp.lib with the main program only. Any program that you compile with either the CSTART or the CSTOP COBSQL directive, you then need to link csqlsupp.lib with the module for that program.

11.4 Using the CP Preprocessor to Expand Copyfiles

The complete set of methods used within COBOL to manipulate copyfiles is not available with database precompilers and COBSQL itself cannot handle included copyfiles. These problems can be overcome, however, by using the Micro Focus Copyfile Preprocessor (CP).

CP is a preprocessor that has been written to provide other preprocessors, such as COBSQL, with a mechanism for handling copyfiles. CP follows the same rules as the COBOL Compiler for handling copyfiles so any copyfile-related Compiler directives are automatically picked up and copyfiles are searched for using the COBCPY environment variable. CP will also expand:

   INCLUDE ...

statements. For more information on CP, refer to the Net Express online help (look under "CP" in the help file index).

Oracle uses .pco and .cob extensions, Sybase uses .pco and .cbl extensions and Informix uses .eco, .cob and .mf2 extensions.

Oracle and Sybase:
For CP to resolve copyfiles and include statements correctly, use the following COBOL Compiler directives for Sybase and Oracle:

copyext (pco,cbl,cpy,cob) osext(pco)

For Informix, use:

copyext (eco,mf2,cbl,cpy,cob) osext(eco)

COBSQL can call CP to expand copyfiles before the database precompiler is invoked. This means that all the copy-related commands are already resolved so that it appears to the database precompiler that a single source file is being used.

The other advantage of using CP is that it makes copyfiles visible when animating.

When CP sees an INCLUDE SQLCA statement, it does the following:

Note: Using the file sqlca.cpy can result in errors when the program is run.

You can specify the CP preprocessor's SY directive to prevent CP expanding the SQLCA include file, for example:

preprocess"cobsql" preprocess"cp" sy endp

You should always use CP's SY directive when processing Sybase code because Sybase expects to expand the SQLCA itself.

As Oracle can produce code with either COMP or COMP-5 variables, it has two sets of copyfiles. The standard sqlca.cob, oraca.cob and sqlda.cob all have COMP data items. The sqlca5.cob, oraca5.cob and sqlda5.cob files have COMP-5 data items. If you are using the comp5=yes Oracle directive, you must set the COBSQL directive MAKESYN to convert the COMP items in the SQLCA to COMP-5.

If CP produces errors when attempting to locate copyfiles, check to make sure that the OSEXT and COPYEXT Compiler directives are set up correctly. COPYEXT should be set first and should include as its first entry the extension used for source files (.pco or .eco, for example).

If these are set correctly, ensure that the copyfile is either in the current directory or in a directory on the COBCPY path.

When using CP in conjunction with COBSQL, SQL errors inside included copyfiles will be reported correctly. Without CP, the line counts will be wrong, and the error will either go unreported or will appear on the wrong line.

11.5 National Language Support (NLS)

COBSQL error messages can be displayed in different languages depending on the setting of the LANG environment variable. For full details on NLS and how to set the LANG environment variable, look up NLS and LANG in the help file index.

Most database clients include some NLS capability but their requirements for the setting of the LANG environment variable differ from those of this COBOL system. We recommend, therefore, that you use the alternative environment variable, COBLANG.

The setting of COBLANG only affects this COBOL system, allowing the LANG environment variable to be used by the database client. Note that for COBLANG to work correctly, mflangnn.lbr, where nn is the setting of COBLANG, must be available in the Net Express \bin directory. So if COBLANG=05 (UK NLS messages), the file mflang05.lbr must be present in Net Express\Base\Bin.

The setting of COBLANG only affects the COBSQL error messages; error messages produced by the database precompiler are not translated by COBSQL.

11.6 Examples

The following examples show, for the Oracle, Sybase and Informix precompilers, command lines which can be entered at the Net Express Command Prompt to compile a program using COBSQL.

11.6.1 Oracle

cobol sample.pco anim nognt preprocess(cobsql)
   cstart cstop CSQLT=ORA end-c comp5=yes endp;


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

11.6.2 Sybase

cobol example1.pco confirm preprocess(cobsql)
   cstop csp cobsqltype=sybase preprocess(cp) sy endp;


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

11.6.3 Informix


cob -a -k -C "p(cobsql) cobsqltype==informix-new"

11.7 Troubleshooting

Initially, you should check each of the items outlined below.

If you continue to have problems, please contact Micro Focus Support. To help Technical Support locate the cause of the problem:

11.7.1 Common Problem Areas

If you cannot locate the source of the problem, check each of the following:

11.7.2 Oracle Considerations

You can use Oracle Pro*COBOL 1.8 or Oracle Pro*COBOL 8.x. The following sections describe the items to consider for each of these versions. Oracle Pro*COBOL 1.8 Considerations

11.7.3 Oracle Pro*COBOL 8.x Considerations

Support for Pro*COBOL 8.0 has been added to COBSQL which now works correctly with the Pro*COBOL 8.0 4.0 precompiler. Directives

To use COBSQL with Oracle 8, you should use the following directives:

This puts calls into the Oracle 8 specific support modules ora8prot and ora8lib. Both of these modules are built into csqlsupp.dll.
EXEC SQL preprocessor. Use the options ORACLE8 and ORA8 to use Pro*COBOL 8.x with COBSQL. Directives

If you are migrating programs from Pro*COBOL 1.x to 8.x, you should be aware of the following: Micro Focus COBOL

Some Micro Focus COBOL language extensions, data definitions and section headings are rejected by Pro*COBOL 8.x:

To overcome this you need to put these items into copybooks which are not opened by Pro*COBOL. However, this does not work if you use CP which expands copybooks before Pro*COBOL is invoked. This could cause a problem if you are using htmlpp which calls CP to expand copybooks. You must therefore invoke htmlpp before COBSQL.

For example, the following compile line works:


whereas this line does not:


You must define at least one variable within the Working-Storage Section for Pro*COBOL 8.0.4 to add its variables to the generated .cbl file.

11.7.4 Sybase Considerations

11.7.5 Informix Considerations

Copyright © 2000 MERANT International Limited. All rights reserved.
This document and the proprietary marks and names used herein are protected by international law.

PreviousSQL Option for DB2