This section includes the following topics:
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:
/usr/lpp/db2_06_01/lib/db2mkrts.args
To include the directory, enter:
export COBCPY=$COBCPY:$HOME/sqllib/include/cobol_mf
| Note: | You might want to set COBCPY in the .profile file. |
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 DB2 API 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=$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 |
|---|
|
The script file contains the following compile options:
|
|
The script file contains the following link options:
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:
client
The script file bldmfcob, 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. 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 # bldmfcob script file # Builds a COBOL program containing embedded SQL # Usage: bldmfcob <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=$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 bldmfcob |
|---|
|
The script file contains the following compile options:
|
|
The script file contains the following link options:
Refer to your compiler documentation for additional compiler
options.
|
To build the sample program updat from the source file updat.sqb , enter:
bldmfcob updat
The result is an executable file updat. You can run the executable file against the sample database by entering:
updat
| Note: | 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, bldmfcobs,
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 bldmfcobs. 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, bldmfcobs, in sqllib/samples/cobol_mf, contains the commands to build a 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. Parameter $3 specifies the user ID for the database, and $4 specifies the password. Only the first two parameters, the source file name and the entry point, are 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, 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, the user ID parameter to $4, and the password parameter to $5. 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
# bldmfcobs script file
# Build sample COBOL stored procedure
# Usage: bldmfcobs <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=$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
# Create the wrapper program for the stored procedure.
wrpmfcobs $1
# Link the program using the export file ${1}_wrap.exp,
# creating a shared library called $1 with the main
# 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 DB2 instance sqllib/function subdirectory.
# This assumes the user has write permission to this directory.
rm -f $DB2PATH/function/$1
cp $1 $DB2PATH/function
| Compile and Link Options for bldmfcobs |
|---|
|
The script file contains the following compile options:
|
|
The script file contains the following link options:
Refer to your compiler documentation for additional compiler
options.
|
The wrapper program, wrpmfcobs, causes the Micro Focus COBOL routine, cobinit(), to be called right before the stored procedure is executed. Its contents are shown below.
#! /bin/ksh
# wrpmfcobs script file
# Create the wrapper program for sample COBOL stored procedure
# Usage: wrpmfcobs <stored_proc_name>
# Note: With the wrapper program, the client application must call x_wrap
# instead of x, where x is the original name of the stored procedure.
# 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 , enter:
bldmfcobs 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 bldcob. Refer to "Micro Focus COBOL" for details.
To call the stored procedure, run the sample client application by entering:
outcli remote_database userid password
where
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.
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.