Overview
COBOL85 accesses ODBC databases through standard SQL syntax. Consequently there are a couple of extra steps required to establish the connectivity.

The connection structure is illustrated in Figure 1, and consists of the following elements:

• COBOL source uses a "server name" to refer to a database (and SQL syntax to refer to tables).
• The server names are defined in a source file called the "ODBC Information File".
• In the ODBC Information File each server name is mapped to an ODBC Data Source Name (DSN).
• Each Data Source Name is mapped to an ODBC driver/database combination using the ODBC Data Source Administrator (invoked from the Windows Control Panel).
• The COBOL system is given the name of the ODBC Information File through the "@ODBC_Inf" COBOL environment variable.

One element not shown in the figure is that you can specify one of the server names to be the default. You connect to this database when you code "CONNECT TO DEFAULT" in your COBOL program. The default is specified in the ODBC Information File.

Figure 1. COBOL85 ODBC Setup Elements

Steps to Setup Your System to Access an ODBC Database
To setup your system so that you can access an ODBC database from your COBOL85 program you essentially work from the bottom of Figure 1 upwards. The following steps are expanded in the sections below.

• First create your database and place it on your server or local machine.
• Use the ODBC Data Source Administrator to create a Data Source Name (DSN) and associate the name with an ODBC driver and your database.
• Create an ODBC Information File that defines a server name and maps it to the DSN name. The information file can also define the default server name.
• Edit the COBOL Environment Variables held in the file COBOL85.CBR to include the "@ODBC_Inf" variable. This variable points to the ODBC Information File.
• Code your program using the server name created in the ODBC Information File to connect to the database, and the table names defined in the database.

Setting up Your Database
When setting up your database consider the following points:

• Do you have an ODBC driver that can access your database? This should be available from your database vendor.
• What passwords are required to access the database? The COBOL85 system stores a password in the ODBC Information File. For systems with both user passwords and database-specific passwords, the ODBC Information File password is the database-specific password. If there is no database-specific password, then the ODBC Information File password needs to be the user password.

Using the ODBC Data Source Administrator
You invoke the ODBC Data Source Administrator from the Windows Control Panel where it has the title "32bit ODBC". You create the Data Source Name (DSN) by using the "Add" function in which you specify the ODBC driver to be used. You map the DSN to a database by using the "Configure" function.

Creating an ODBC Information File
You can create an ODBC Information File with a text editor or by using the ODBC Information File creation utility provided by Fujitsu. If you are setting up a default connection then you need to use the utility as it encrypts the password for you.

The ODBC Information File Creation Utility is the program "SQLODBCS.EXE" found in the PowerCOBOL system directory (\fsc\pcobol32 if you took the installation defaults). Invoke the utility by double-clicking on SQLODBCS.EXE in a Windows Explorer folder list. Alternatively, you can customize the Programming-Staff Tools menu so that the utility is invoked from there.

When you invoke the utility it first asks you for an information file name. To create a new file, enter the new file name in the file name entry field with a ".inf" extension. To load an existing file select it using the Browse function. Click OK to display the utility's main window shown in Figure 2.

Figure 2. ODBC Information File Creation Utility main window

Enter the following information:

• Server Name - the name that your program uses to connect to the database.
• Data Source Name - the DSN that you have set up using the ODBC Data Source Administrator. The utility provides a drop-down list of all the DSNs that are set up.
• Comment - comment describing the server. When creating a new information file the utility requires that you enter a comment.
• Select the Access Mode and Commit Mode.

If you want to setup a database for the default connection enter all of the following items:

• Server Name - the name set for that database
• User ID - ID required to access the database
• Password - password required to access the database. If there is no database password this is the user's password, otherwise it is the database password. A blank password is not supported.

Setting up the "@ODBC_Inf" COBOL Environment Variable
The format for the "@ODBC_Inf" environment variable is:

@ODBC_Inf=<full-pathname-of-odbc-information-file>

For example if the information file is called "myodbc.inf" and is stored in the COBOL system directory "c:\fsc\pcobol32", the environment variable would be set as:

@ODBC_Inf=c:\fsc\pcobol32\myodbc.inf

You can edit the COBOL85.CBR file yourself, or use the Runtime Environment Setup dialog to set the variable and update the COBOL85.CBR file. See the chapter on Executing Programs in the COBOL85 User's Guide for more information on COBOL environment variables.

Connecting to the Database
In your COBOL source code connect to the database by coding either:

EXEC SQL

CONNECT TO

END EXEC

or, if you have set up a default connection:

EXEC SQL

CONNECT TO DEFAULT

END EXEC

Error Messages

1. If an ODBC Information File has not been set up or cannot be found you may receive a message like:
   
   JMP0371I-U ENVIRONMENT INFORMATION FILE ERROR TO PERFORM SQL. '@SQL_USERID'.
   
   or
   
   JMP0371I-U ENVIRONMENT INFORMATION FILE ERROR TO PERFORM SQL. '@SQL_SERVER'.
   
   When you see these messages, first check that you have specified the full path name in the @ODBC_Inf COBOL environment variable and that the ODBC Information File is there.
   
   
2. If you the CONNECT statement fails with a "Not valid password" message, check that you are passing the appropriate password for the database. For example, if the database has a password, the user password will not work.