PreviousSQL, DB2/2 and 32-bit COBOL Interface to Informix DBMSNext"

Chapter 26: 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 Server 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.

Notes :

26.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.

26.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 cob command line.

To terminate the directives to be passed to COBSQL, you must use the ENDP COBOL directive. You can do this by making the following changes to the directives:

C"preprocess(Cobsql) csqltype=oracle end-c comp5=yes endp"

When using Server Express, END-C and ENDP have the following effect:

26.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 Server 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 cob command line.

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 below), 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:

cob -V -k testprog.pco -C"p(cobsql) csqlt==ora makesyn end-c xref==yes 
   mode==ansi endp omf(gnt) list()"

26.2.2 COBSQL Directives

Specifies which precompiler to use (ORACLE, SYBASE or INFORMIX-NEW); for example, COBSQLTYPE=ORACLE .
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.

26.2.3 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.

26.3 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 the following statements:

   INCLUDE ...

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.

26.4 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, see the chapter Internationalization Support in your Programmer's Guide to Writing Programs. For details on the LANG environment variable see the appendix Micro Focus Environment Variables in your Server Express User Guide.

The Cobsql error message cobsql.lng has been translated into a number of different languages and can be found with the COBOL NLS message files. If there is not an error message cobsql.lng for the current setting of LANG, then the default error message file is used.

Note: Cobsql does not translate any error messages produced by the database precompilers.

26.5 Examples

The following examples show, for the Oracle Sybase and Informix precompilers, command lines that you can enter at the Server Express Command Prompt to compile a program using COBSQL.


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


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


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

26.6 Troubleshooting

If you experience problems using COBSQL, first of all check the following:

Then, if you still experience problems, please contact Micro Focus Support. To help Technical Support locate the cause of the problem:

26.6.1 Common Problem Areas

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

26.6.2 Oracle Considerations

If you are troubleshooting Oracle problems, consider the following:

26.6.3 Sybase Considerations

If you are troubleshooting Sybase problems, consider the following:

26.6.4 Informix Considerations

If you are troubleshooting Informix problems, consider the following:

26.7 COBSQL Error Messages

COBSQL displays four different types of message. These are as follows:

The sections below list current COBSQL messages.

CSQL-I-001: COBSQL has finished returning to the Checker

For information only. COBSQL has successfully processed the source file and has passed all the necessary information back to the COBOL Compiler. The program can now be animated or executed. If any errors have been found, these will be highlighted in the source and the error text will be made available.

CSQL-I-003: COBSQLTYPE is incorrect defaulting to Oracle

For information only. It is displayed if the last COBSQLTYPE directive has an incorrect value.COBSQL defaults to using the Oracle precompiler if the COBSQLTYPE directive is not set, is set incorrectly, or is set to an obsolete value.

COBSQL attempts to invoke the Oracle precompiler. This causes further errors if the Oracle precompiler is not present.

CSQL-I-004: Accepted cobsql-directive

Confirms that a COBSQL directive is valid.

CSQL-I-005: Passing precompiler-directive

COBSQL has encountered directives after the END-COBSQL directive. These directives are for the database precompiler and COBSQL will pass them on. This message is only displayed if the CONFIRM directive is set.

CSQL-I-006: Rejected cobsql-directive>

COBSQL has encountered an invalid directive. Either the directive is incorrect or the value supplied for the directive is incorrect.

CSQL-F-007: COBSQL/Checker incompatible -- Terminating

When COBSQL has to interact with other COBOL Integrated Preprocessors (for example, CP or HTMLPP), it needs to make sure that the subordinate preprocessor(s) are using the same line buffer size as COBSQL. If they are not, this error message is generated. Under normal execution, this message should not appear. If it does, it indicates that an old version of COBSQL is being used with a new Integrated Preprocessor, or vice versa.

CSQL-I-008: Invoking integrated-preprocessor Preprocessor

Displayed when other Integrated Preprocessors are to be invoked. It is for information only.

CSQL-F-009: Irrecoverable error in integrated-preprocessor -- Terminating

The Integrated Preprocessor that COBSQL invoked has returned a fatal error message. COBSQL passes this message to the COBOL Compiler and aborts.

For more information about what might have caused the other Integrated Preprocessor to abort, refer to its documentation.

CSQL-F-010: Irrecoverable error writing STK record

In a stacked environment (for example when COBSQL invokes another Integrated Preprocessor such as CP), COBSQL stores information returned from the other Integrated Preprocessor in a side file that has an extension of STK. The file has the same basename as the input file.

This message is displayed if COBSQL receives a COBOL error while trying to write out a record to the STK side file. COBSQL also displays error message CSQL-E-023 (file I/O error) giving the COBOL I/O error message.

CSQL-F-011: Environment unsupported by COBSQL/Informix

COBSQL is being run with a version of COBOL for which, to the best of our knowledge, no Informix COBOL precompiler is available. This message is also displayed if the wrong Informix COBSQLTYPE is specified for the COBOL release that COBSQL is running with.

CSQL-F-012: INFORMIXDIR must be set for Informix Support

To be able to use the Informix Precompiler, the environment variable INFORMIXDIR must be set. COBSQL uses the value of the INFORMIXDIR environment variable to locate the ESQL/COBOL precompiler.

CSQL-F-013: Unable to access: filename

This error can occur when COBSQL tries to open the source code file, or tries to process a copy statement in the expanded code. COBSQL attempts to open the source file before it invokes the database precompiler. If it cannot open the file, it reports this error.

This error might also be displayed if COBSQL cannot open a copyfile that appears in the expanded source code. COBSQL needs to process copy statements that are inserted by the database precompiler. If COBSQL did not do this, the COBOL Compiler would treat the copy statement as though it appeared in the original source, and expand it.

Once COBSQL has displayed this error, it will also display error message CSQL-E-023 (file I/O error) giving the COBOL I/O error message.

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

This message is displayed when running under UNIX. On UNIX this is NOT a fatal error. If a database precompiler came across errors in the source file, it is likely it would produce a non-zero return code. Because this might happen, COBSQL will continue after displaying this message.

CSQL-I-017: Creating filename

COBSQL displays this message, for information only, when the expanded source file is to be kept.

CSQL-I-018: Invoking precompiler Precompiler/Translator

COBSQL displays this message, for information only, to let the user know which database precompiler is about to be called.

CSQL-F-019: Irrecoverable error Opening STK file

COBSQL has attempted to open the STK side file. This file is only used when COBSQL is stacked with other Integrated Precompilers.

COBSQL also displays error message CSQL-E-023 (file I/O error) giving the COBOL I/O error message.

CSQL-I-020: Processing output of precompiler Precompiler

COBSQL displays this message once it has successfully called the database precompiler and is about to start processing the expanded code.

CSQL-F-021: Precompiler did not complete -- Terminating

After calling the database precompiler COBSQL checks to make sure that it completed. It does this by trying to open the files that the precompiler should have produced. If it cannot open the files, it reports this error.

If this message is displayed and the precompiler has created both a listing file and the expanded source code, then either COBSQL does not have read permissions on the files, or they have been created in the wrong directory. Ensure that the current directory is set correctly before running COBSQL.

CSQL-F-022: Irrecoverable error Reopening ORG file

As part of the processing performed after the database precompiler has completed, COBSQL reopens the original source code file. If COBSQL cannot open the file, it displays this error message.

COBSQL also displays error message CSQL-E-023 (file I/O error) giving the COBOL I/O error message.

CSQL-E-023: File Status file-status

COBSQL displays this error message after a file operation has failed. This message is normally preceded by another COBSQL error message identifying the file in error.

CSQL-E-024: Encountered an I/O on file filename

Displayed when a write error occurs on either the trace or the debug file.

COBSQL also displays error message CSQL-E-023 (file I/O error) giving the COBOL I/O error message.

CSQL-F-025: Unable to Create virtual-heap

To process the source file and the expanded code, COBSQL needs to create a number of virtual heaps. If there is a problem when COBSQL tries to create a heap, this message is displayed indicating which heap COBSQL had problems creating.

The most likely cause of this problem is that not enough memory is available or that too many virtual heaps have already been created. The solution is to close down some COBOL applications to free up memory or virtual file slots.

CSQL-F-026: Premature end of expanded source...

CSQL-F-026: Premature end of expanded source. Check for
CSQL-F-026: precompiler abort when run standalone. This
CSQL-F-026: error is unrecoverable. Hit any key to abort
CSQL-F-026: Source Lines could not be matched by COBSQL
CSQL-F-026: COBSQL was processing: area- of- code
CSQL-F-026: Source lines around line in error are

lines of source code

COBSQL has reached the end of the expanded source code before it reached the end of the original source code. There are two possible reasons for this.

  1. The precompiler could not complete the creation of the expanded source code.

  2. COBSQL found a mismatch between a line in the original source code and the expanded source code.

The item area-of-code corresponds to the position within the original source code that COBSQL was processing. These areas include Working-Storage, Procedure Division and SQL statements.

The item lines of source code identifies the original source code lines that COBSQL was processing. These are displayed as they can indicate where the problem lies in the original source code.

CSQL-I-027: Detected Working Section, now processing it

Displayed, for information only, when COBSQL is running in VERBOSE mode. It indicates that COBSQL has encountered the Working Storage Section and is about to process it.

CSQL-I-028: Now processing through Procedure Division

Displayed, for information only, when COBSQL is running in VERBOSE mode. It indicates that COBSQL has encountered the Procedure Division and is about to process it.

CSQL-I-029: Found an EXEC SQL Statement, processing it

Displayed, for information only, when COBSQL is running in VERBOSE mode. It indicates that COBSQL has encountered an EXEC SQL statement within the procedure division of a program and is about to process it.

CSQL-E-036: Unable to open the precompiler file: filename

As part of the processing performed after the database precompiler has completed, COBSQL opens the expanded source code file. If COBSQL cannot open the file, it displays this message.

COBSQL also displays error message CSQL-E-023 (file I/O error) giving the COBOL I/O error message.

CSQL-F-037: Wrong Version of COBOL used, please upgrade

COBSQL is being run with an old version of COBOL and will not work correctly. Because of this, COBSQL terminates rather than trying to continue.

CSQL-I-038: The following directive is now Obsolete: cobsql-directive

COBSQL has encountered a directive that is now marked as obsolete.

CSQL-I-039: The ORG & the CBL files were out of synch

COBSQL sometimes tries to re-position itself when working through the original source file (ORG) and the source produced by the database precompiler (CBL). It does this by scanning ahead in the CBL file to try to find a matching line. If it does, it displays this message.

The usual reason for a mismatch between the two source files is that the precompiler has produced code that COBSQL is not able to cope with. Until COBSQL is altered to cope with this, using the SQLDEBUG directive provides a temporary work-around.

The code produced when this message has been displayed may not function correctly because some of the original source may have been removed so that COBSQL can re-position itself.

CSQL-W-040: Pro*COBOL commented out the following line: source-line

Pro*COBOL has commented out a line of code that was not a part of an EXEC SQL statement. This may alter the way that the program executes and care should be taken if the application is run.

CSQL-F-041: Cannot read the COBOL runtime switches

COBSQL tries to determine how the current run-time is configured by examining the settings of the run-time switches. This error is displayed if COBSQL cannot read the current settings.

This error causes COBSQL to abort.

CSQL-F-042: Cannot set the COBOL runtime switches

Some external code generators produce COBOL code which contains null characters. COBSQL reads the settings of the run-time switches and attempts to change the settings of the relevant switches in order to enable it to read code containing null characters.

This message is displayed if COBSQL has successfully read the run-time switches but has failed in its attempt to set them.

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

PreviousSQL, DB2/2 and 32-bit COBOL Interface to Informix DBMSNext"