Application Building Guide

Micro Focus COBOL

This section includes the following topics:

Using the Compiler
DB2 API and Embedded SQL Applications
Embedded SQL Stored Procedures

Using the Compiler

If you develop applications that contain embedded SQL and DB2 API calls, and you are using the Micro Focus compiler, keep the following points in mind:

When you precompile your application using the command line processor command db2 prep, use the target mfcob option, the default.
Ensure the LIB environment variable points to %DB2PATH%\lib like this:
```
set LIB="%DB2PATH%\lib;%LIB%"
```
The DB2 COPY files for Micro Focus COBOL reside in %DB2PATH%\include\cobol_mf. Set the COBCPY environment variable to include the directory like this:
```
set COBCPY="%DB2PATH%\include\cobol_mf;%COBCPY%"
```

Calls to all DB2 application programming interfaces must be made using calling convention 74. The DB2 COBOL precompiler automatically inserts a CALL-CONVENTION clause in a SPECIAL-NAMES paragraph. If the SPECIAL-NAMES paragraph does not exist, the DB2 COBOL precompiler creates it, as follows:

Identification Division
Program-ID. "static".
special-names.
    call-convention 74 is DB2API.

Also, the precompiler automatically places the symbol DB2API, which is used to identify the calling convention, after the "call" keyword whenever a DB2 API is called. This occurs, for instance, whenever the precompiler generates a DB2 API run-time call from an embedded SQL statement.

If calls to DB2 APIs are made in an application which is not precompiled, you should manually create a SPECIAL-NAMES paragraph in the application, similar to that given above. If you are calling a DB2 API directly, then you will need to manually add the DB2API symbol after the "call" keyword.

DB2 API and Embedded SQL Applications

The batch file bldapp, in %DB2PATH%\samples\cobol_mf, contains the commands to build a DB2 application program.

The first parameter, %1, specifies the name of your source file. This is the only required parameter for programs that do not contain embedded SQL. Building embedded SQL programs requires a connection to the database so three optional parameters are also provided: the second parameter, %2, specifies the name of the database to which you want to connect; the third parameter, %3, specifies the user ID for the database, and %4 specifies the password.

For an embedded SQL program, bldapp passes the parameters to the precompile and bind batch file, embprep. If no database name is supplied, the default sample database is used. The user ID and password parameters are only needed if the instance where the program is built is different from the instance where the database is located.

@echo off
rem bldapp.bat  -- Windows 32-bit operating systems
rem Builds a Micro Focus Cobol application program
rem Usage: bldapp <prog_name> [ <db_name> [ <userid> <password> ]] 
 
rem If an embedded SQL program, precompile and bind it.
if not exist "%1.sqb" goto compile_step
call embprep %1 %2 %3 %4
 
:compile_step
rem Compile the error-checking utility.
cobol checkerr.cbl;
 
rem  Compile the program.
cobol %1.cbl;
 
rem  Link the program.
cbllink -l %1.obj checkerr.obj db2api.lib
@echo on

Compile and Link Options for bldapp

Compile and Link Options for bldapp
Compile Option: `cobol` The Micro Focus COBOL compiler.
Link Options: `cbllink` Use the linker to link edit. `-l` Link with the lcobol library. `checkerr.obj` Link with the error-checking utility object file. `db2api.lib` Link with the DB2 API library. Refer to your compiler documentation for additional compiler options.

Compile Option:

cobol: The Micro Focus COBOL compiler.

Link Options:

cbllink: Use the linker to link edit.
-l: Link with the lcobol library.
checkerr.obj: Link with the error-checking utility object file.
db2api.lib: Link with the DB2 API library.

Refer to your compiler documentation for additional compiler options.

To build the non-embedded SQL sample program, client, from the source file client.cbl, enter:

   bldapp client

The result is an executable file client.exe. You can run the executable file against the sample database by entering the executable name (without the extension):

   client

Building and Running Embedded SQL Applications

There are three ways to build the embedded SQL application, updat, from the source file updat.sqb:

If connecting to the sample database on the same instance, enter:
```
   bldapp updat
```
If connecting to another database on the same instance, also enter the database name:
```
   bldapp updat database
```
If connecting to a database on another instance, also enter the user ID and password of the database instance:
```
   bldapp updat database userid password
```

The result is an executable file, updat.exe.

There are three ways to run this embedded SQL application:

If accessing the sample database on the same instance, simply enter the executable name (without the extension):
```
   updat
```
If accessing another database on the same instance, enter the executable name and the database name:
```
   updat database
```
If accessing a database on another instance, enter the executable name, database name, and user ID and password of the database instance:
```
   updat database userid password
```

Embedded SQL Stored Procedures

The batch file bldsrv, in %DB2PATH%\samples\cobol_mf, contains the commands to build an embedded SQL stored procedure. The batch file compiles the stored procedure into a DLL on the server.

The first parameter, %1, specifies the name of your source file. The second parameter, %2, specifies the name of the database to which you want to connect. Since the stored procedure must be build on the same instance where the database resides, there are no parameters for user ID and password.

Only the first parameter, source file name, is required. Database name is optional. If no database name is supplied, the program uses the default sample database.

The batch file uses the source file name, %1, for the DLL name.

@echo off
rem bldsrv.bat  -- Windows 32-bit operating systems
rem Builds a Micro Focus Cobol stored procedure
rem Usage: bldsrv <prog_name> [ <db_name> ] 
 
rem Precompile and bind the program.
call embprep %1 %2
 
rem  Compile the stored procedure.
cobol %1.cbl /case;
 
rem  Link the stored procedure and create a shared library.
cbllink /d %1.obj db2api.lib
 
rem Copy the stored procedure to the %DB2PATH%\function directory.
copy %1.dll "%DB2PATH%\function"
@echo on

Compile and Link Options for bldsrv

Compile Options:

cobol
The Micro Focus COBOL compiler.
/case
Prevent external symbols being converted to upper case.

Link Options:

cbllink
Use the Micro Focus COBOL linker to link edit.
/d
Create a .dll file.
db2api.lib
Link with the DB2 API library.

Refer to your compiler documentation for additional compiler options.

Compile and Link Options for bldsrv
Compile Options: `cobol` The Micro Focus COBOL compiler. `/case` Prevent external symbols being converted to upper case.
Link Options: `cbllink` Use the Micro Focus COBOL linker to link edit. `/d` Create a .dll file. `db2api.lib` Link with the DB2 API library. Refer to your compiler documentation for additional compiler options.

To build the sample program outsrv from the source file outsrv.sqb, if connecting to the sample database, enter:

   bldsrv outsrv

If connecting to another database, also enter the database name:

   bldsrv outsrv database

The script file copies the DLL to the server in the path sqllib/function.

If necessary, set the file mode for the DLL so the client program can access it.

Once you build the DLL outsrv, you can build the client application outcli that calls it. You can build outcli using the batch file, bldapp. Refer to "DB2 API and Embedded SQL Applications" for details.

To call the stored procedure, run the sample client application by entering:

   outcli database userid password

where

database: Is the name of the database to which you want to connect. The name could be sample, or its alias, or another name.
userid: Is a valid user ID.
password: Is a valid password.

The client application accesses the DLL, outsrv, and executes the stored procedure function of the same name on the server database. The output is then returned to the client application.

[ Top of Page | Previous Page | Next Page ]