Application Building Guide

Micro Focus COBOL

This section includes the following topics:

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:

DB2 API and Embedded SQL Applications

The build file, bldapp, in sqllib/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 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.



#! /bin/ksh
# bldapp script file -- AIX                           
# Builds a Micro Focus COBOL application program
# Usage: bldapp <prog_name> [ <db_name> [ <userid> <password> ]] 
                   
# Set DB2PATH to where DB2 will be accessed. 
# The default is the standard instance path.
DB2PATH=$HOME/sqllib
 
# If an embedded SQL program, precompile and bind it.
if [[ -f $1".sqb" ]]
then
  embprep $1 $2 $3 $4
fi
 
# Set COBCPY to include the DB2 COPY files directory.
export COBCPY=$DB2PATH/include/cobol_mf:$COBCPY
 
# Compile the checkerr.cbl error checking utility.
cob -c -x checkerr.cbl
 
# Compile the program.
cob -c -x $1.cbl
 
# Link the program.
cob -x -o $1 $1.o checkerr.o -ldb2 -ldb2gmf -L$DB2PATH/lib


Compile and Link Options for bldmfapi

Compile Options:

cob
The COBOL compiler.

-c
Perform compile only; no link.

-x
Produce an executable program.

Link Options:

cob
Use the compiler as a front end for the linker.

-x
Produce an executable program.

-o $1
Specify the executable program.

$1.o
Specify the program object file.

-ldb2
Link to the DB2 library.

-ldb2gmf
Link to the DB2 exception-handler library for Micro Focus COBOL.

-L$DB2PATH/lib
Specify the location of the DB2 runtime shared libraries. For example: $HOME/sqllib/lib. If you do not specify the -L option, the compiler assumes the following path: /usr/lib:/lib.

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. You can run the executable file against the sample database by entering:

   client

Building and Running Embedded SQL Applications

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

  1. If connecting to the sample database on the same instance, enter:
       bldapp updat
    
  2. If connecting to another database on the same instance, also enter the database name:
       bldapp updat database
    
  3. 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.

There are three ways to run this embedded SQL application:

  1. If accessing the sample database on the same instance, simply enter the executable name:
       updat
    
  2. If accessing another database on the same instance, enter the executable name and the database name:
       updat database
    
  3. 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

Notes:

  1. Before building a stored procedure on AIX 4.3 using the Micro Focus 4.1 compiler, execute the following commands:
       db2stop
       db2set DB2LIBPATH=$LIBPATH
       db2set DB2ENVLIST="COBDIR LIBPATH"
       db2set
       db2start
    
    Ensure that db2stop stops the database and LIBPATH is set properly in your shell environment. The last db2set command is issued to display your settings: make sure DB2LIBPATH and DB2ENVLIST are set correctly.

  2. Some of the more recent versions of the Micro Focus COBOL compiler, used on an AIX Version 4 platform, cannot be used to create a statically-linked stored procedure. As such, the makefile and script file, bldsrv, have been adapted to allow for the creation of a dynamically-linked stored procedure.

    In order for a remote client application to successfully call this dynamically-linked stored procedure, it is necessary for a Micro Focus COBOL routine, cobinit(), to be called on the server where the stored procedure resides just before the stored procedure is executed. A wrapper program which accomplishes this is created during the execution of the makefile, or the script file bldsrv. It is then linked with the stored procedure code to form the stored procedure shared library. Due to the use of this wrapper program, in order for a client application to call a stored procedure named x, it must call x_wrap instead of x.

    The details of the wrapper program are explained later in this section.

The script file bldsrv, in sqllib/samples/cobol_mf, contains the commands to build a stored procedure. The script file compiles the stored procedure into a shared library 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. 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 script file uses the source file name, $1, for the shared library name, and for the entry point to the shared library. If you are building stored procedures where the entry point function name is different from the source file name, you can modify the script file to accept another parameter for the entry point. We recommend renaming the database parameter to $3. Then you can change the entry point link option to -e $2, and specify the additional parameter on the command line when you run the script file.

#! /bin/ksh 
# bldsrv script file -- AIX
# Builds a Micro Focus COBOL stored procedure 
# Usage: bldsrv <prog_name> [ <db_name> ] 
                           
# Set DB2PATH to where DB2 will be accessed. 
# The default is the standard instance path.
DB2PATH=$HOME/sqllib
 
# Precompile and bind the program.
embprep $1 $2
                           
# Set COBCPY to include the DB2 COPY files directory. 
export COBCPY=$DB2PATH/include/cobol_mf:$COBCPY
 
# Compile the program.                              
cob -c -x $1.cbl
                                    
# Create the wrapper program for the stored procedure.
wrapsrv $1
 
# Link the program using export file ${1}_wrap.exp    
# creating shared library $1 with entry point ${1}_wrap. 
cob -x -o $1 ${1}_wrap.c $1.o -Q -bE:${1}_wrap.exp -Q "-e $1" \
-Q -bI:$DB2PATH/lib/db2g.imp -ldb2gmf -L$DB2PATH/lib
 
# Copy the shared library to the sqllib/function subdirectory. 
# Note: the user must have write permission to this directory.
rm -f $DB2PATH/function/$1
cp $1 $DB2PATH/function


Compile and Link Options for bldsrv

Compile Options:

cob
The COBOL compiler.

-c
Perform compile only; no link. This book assumes that compile and link are separate steps.

-x
Produce an executable program.

Link Options:

cob
Use the compiler to link edit.

-x
Produce an executable program.

-o $1
Specify the executable program.

-o ${1}_wrap.c
Specify the wrapper program.

$1.o
Specify the program object file.

-Q -bE:${1}_wrap.exp
Specify an export file. The export file contains a list of the stored procedure entry points. If a stored procedure is called x, then its entry point will be x_wrap.

-Q "-e $1"
Specify the default entry point to the shared library.

-Q -bI:$DB2PATH/lib/db2g.imp
Provides a list of entry points to the DB2 application library.

-ldb2gmf
Link to the DB2 exception-handler library for Micro Focus COBOL.

-L$DB2PATH/lib
Specify the location of the DB2 runtime shared libraries. For example: $HOME/sqllib/lib. If you do not specify the -L option, the compiler assumes the following path: /usr/lib:/lib.

Refer to your compiler documentation for additional compiler options.

The wrapper program, wrapsrv, causes the Micro Focus COBOL routine, cobinit(), to be called right before the stored procedure is executed. Its contents are shown below.



#! /bin/ksh 
# wrapsrv script file
# Creates the wrapper program for Micro Focus COBOL stored procedures
# Usage: wrapsrv <stored_proc>
 
# Note: The client program calls "<stored_proc>_wrap" not "<stored_proc>"
                           
# Create the wrapper program for the stored procedure.
cat << WRAPPER_CODE > ${1}_wrap.c
#include <stdio.h>
void cobinit(void);
int $1(void *p0, void *p1, void *p2, void *p3);
 
int main(void)
{
  return 0;
}
 
int ${1}_wrap(void *p0, void *p1, void *p2, void *p3)
{
  cobinit();
  return $1(p0, p1, p2, p3);
}
WRAPPER_CODE
# Create the export file for the wrapper program
echo $1_wrap > ${1}_wrap.exp

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 shared library to the server in the path sqllib/function.

If necessary, set the file mode for the shared library so the client application can access it.

Once you build the stored procedure outsrv, you can build the client application outcli that calls it. You can build outcli using the script 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 shared library, outsrv, and executes the stored procedure function of the same name on the server database. The output is then returned to the client application.

Exiting the Stored Procedure

When you develop a stored procedure, exit the 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. This is especially important when the stored procedure is called by a local COBOL client application.


[ Top of Page | Previous Page | Next Page ]