Application Building Guide

Micro Focus COBOL

This section contains the following topics:

• Using the Compiler

• DB2 API Applications

• 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 COBOL 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).

• In order to use the built-in precompiler front-end, runtime interpreter or Animator debugger, add the DB2 Generic API entry points to the Micro Focus runtime module rts32 by executing the MKRTS command provided by Micro Focus, as follows:

  1. Log in as root.

  2. Execute MKRTS with the arguments supplied in the following directory:

        /opt/IBMdb2/V6.1/lib/db2mkrts.args
     

• You must include the DB2 COBOL COPY file directory in the Micro Focus COBOL environment variable COBCPY. The COBCPY environment variable specifies the location of COPY files. The DB2 COPY files for Micro Focus COBOL reside in sqllib/include/cobol_mf under the database instance directory.

  To include the directory, enter:

     export COBCPY=$COBCPY:/opt/IBMdb2/V6.1/include/cobol_mf
  

  Note:

  You might want to set COBCPY in the .profile file.

DB2 API Applications

The script file bldmfapi, in sqllib/samples/cobol_mf, contains the commands to build a DB2 API program. The parameter, $1, specifies the name of your source file.

#! /bin/ksh # bldmfapi script file # Builds a COBOL program not containing embedded SQL # Usage: bldmfapi <prog_name> # Set DB2PATH to where DB2 will be accessed. # The default is the standard instance path. DB2PATH=$HOME/sqllib # Set COBCPY to include the DB2 COPY files directory. export COBCPY=$COBCPY:$DB2PATH/include/cobol_mf # Compile the checkerr.cbl error checking utility. cob -cx checkerr.cbl # Compile the program. cob -cx $1.cbl # Link the program. cob -x $1.o checkerr.o -L$DB2PATH/lib -ldb2 -ldb2gmf

Compile and Link Options for bldmfapi
The script file contains the following compile options: cob The Micro Focus COBOL compiler. -cx Compile to object module.
The script file contains the following link options: cob Use the compiler to link edit. -x Specify an executable program. $1.o Include the program object file. checkerr.o Include the utility object file for error checking. -L$DB2PATH/lib Specify the location of the DB2 runtime shared libraries. For example: $HOME/sqllib/lib -ldb2 Link to the DB2 library. -ldb2gmf Link to the DB2 exception-handler library for Micro Focus COBOL. Refer to your compiler documentation for additional compiler options.

To build the sample program client from the source file client.cbl , enter:

bldmfapi client

The result is an executable file client. You can run the executable file against the sample database by entering the executable name:

client

Embedded SQL Applications

The script file bldmfcc, in sqllib/samples/cobol_mf, contains the commands to build an embedded SQL program.

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. The third parameter, $3, specifies the user ID for the database, and $4, specifies the password. Only the first parameter, the source file name, is required. Database name, user ID, and password are optional. If no database name is supplied, the program uses the default sample database.

#! /bin/ksh
# bldmfcc script file
# Builds a COBOL program containing embedded SQL
# Usage: bldmfcc <prog_name> [ <db_name> [ <userid> <password> ]]
 
# Set DB2PATH to where DB2 will be accessed. 
# The default is the standard instance path. 
DB2PATH=$HOME/sqllib
 
# Connect to a database.
if (($# < 2))
then
   db2 connect to sample
elif (($# < 3))
then
   db2 connect to $2
else
   db2 connect to $2 user $3 using $4
fi
 
# Precompile the program.
db2 prep $1.sqb bindfile
 
# Bind the program to the database.
db2 bind $1.bnd
 
# Disconnect from the database.
db2 connect reset
 
# Set COBCPY to include the DB2 COPY files directory.
export COBCPY=$COBCPY:$DB2PATH/include/cobol_mf
 
# Compile the checkerr.cbl error checking utility.
cob -cx checkerr.cbl
 
# Compile the program.
cob -cx $1.cbl
 
# Link the program.
cob -x $1.o checkerr.o -L$DB2PATH/lib -ldb2 -ldb2gmf

Compile and Link Options for bldmfcc
The script file contains the following compile options: cob The Micro Focus COBOL compiler. -cx Compile to object module.
The script file contains the following link options: cob Use the compiler as a front end for the linker. -x Specify an executable program. $1.o Include the program object file. checkerr.o Include the utility object file for error checking. -L$DB2PATH/lib Specify the location of the DB2 runtime shared libraries. For example: $HOME/sqllib/lib. -ldb2 Link to the DB2 library. -ldb2gmf Link to the DB2 exception-handler library for Micro Focus COBOL. Refer to your compiler documentation for additional compiler options.

To build the sample program updat from the source file updat.sqb , enter:

bldmfcc updat

The result is an executable file updat. You can run the executable file against the sample database by entering:

updat

Embedded SQL Stored Procedures

The script file bldmfsp, in sqllib/samples/cobol_mf, contains the commands to build an embedded SQL stored procedure. The script file compiles the stored procedure into a shared library on the server that can be called by a client application.

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. The third parameter, $3, specifies the user ID for the database, and $4 specifies the password. Only the first parameter, the source file name, is required. Database name, user ID, and password are optional. If no database name is supplied, the program uses the default sample database.

The script file uses the source file name, $1, for the shared library name.

#! /bin/ksh
# bldmfsp script file
# Builds a COBOL stored procedure.
# Usage: bldmfsp <stored_proc_name> [ <db_name> [ <userid> <password> ]]
 
# Set DB2PATH to where DB2 will be accessed. 
# The default is the standard instance path. 
DB2PATH=$HOME/sqllib
 
# Connect to a database.
if (($# < 2))
then
   db2 connect to sample
elif (($# < 3))
then
   db2 connect to $2
else
   db2 connect to $2 user $3 using $4
fi
 
# Precompile the program.
db2 prep $1.sqb bindfile
 
# Bind the program to the database.
db2 bind $1.bnd
 
# Disconnect from the database.
db2 connect reset
 
# Set COBCPY to include the DB2 COPY files directory.
export COBCPY=$COBCPY:$DB2PATH/include/cobol_mf
 
# Compile the checkerr.cbl error checking utility.
cob +z -cx checkerr.cbl
 
# Compile the program.
cob +z -cx $1.cbl
 
# Link the program.
ld -b -o $1 $1.o -L$DB2PATH/lib -ldb2 -ldb2gmf \
   -L$COBDIR/coblib -lcobol -lcrtn
 
# Copy the shared library to the sqllib/function subdirectory of the DB2 instance.
# This assumes the user has write permission to this directory.
rm -f $DB2PATH/function/$1
cp $1 $DB2PATH/function

To build the sample program outsrv from the source file outsrv.sqb , enter:

   bldmfsp outsrv

The script file copies the stored procedure to the server in the path sqllib/function. For DB2DARI parameter style stored procedures where the invoked procedure matches the shared library name, this location indicates that the stored procedure is fenced. If you want this type of stored procedure to be unfenced, you must move it to the sqllib/function/unfenced directory. For all other types of DB2 stored procedures, you indicate whether it is fenced or not fenced with the CREATE FUNCTION statement in the calling program. For a full discussion on creating and using the different types of DB2 stored procedures, please see the "Stored Procedures" chapter in the Application Development Guide.

Note:

An unfenced stored procedure runs in the same address space as the database manager and results in increased performance when compared to a fenced stored procedure, which runs in an address space isolated from the database manager. With unfenced stored procedures there is a danger that user code could accidentally or maliciously damage the database control structures. Therefore, you should only run unfenced stored procedures when you need to maximize the performance benefits. Ensure these programs are thoroughly tested before running them as unfenced. Refer to the Application Development Guide for more information.

If necessary, set the file mode for the stored procedure so the DB2 instance can run it.

Once you build the stored procedure outsrv, you can build the client application outcli that calls the stored procedure. You can build outcli using the script file bldmfcc. Refer to "Embedded SQL Applications" for details.

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

   outcli

The client application passes a variable to the server program outsrv, which gives it a value and then returns the variable to the client application.

Exiting the Stored Procedure

When you develop your stored procedures, exit your stored procedure using the following statement:

move SQLZ-HOLD-PROC to return-code.

With this statement, the stored procedure returns correctly to the client application.

[ DB2 List of Books | Search the DB2 Books ]