Application Building Guide

IBM COBOL Set for AIX

This section includes 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 IBM COBOL Set for AIX compiler, keep the following points in mind:

• When you precompile your application using the command line processor command db2 prep, use the target ibmcob option.

• Do not use tab characters in your source files.

• You can use the PROCESS and CBL keywords in the first line of your source files to set compile options.

• If your application contains only embedded SQL, but no DB2 API calls, you do not need to use the pgmname(mixed) compile option. If you use DB2 API calls, you must use the pgmname(mixed) compile option.

• If you are using the "System/390 host data type support" feature of the IBM COBOL Set for AIX compiler, the DB2 include files for your applications are in the following directory:

  $HOME/sqllib/include/cobol_i
  

  If you are building DB2 sample programs using the script files provided, the include file path specified in the script files must be changed to point to the cobol_i directory and not the cobol_a directory.

  If you are NOT using the "System/390 host data type support" feature of the IBM COBOL Set for AIX compiler, or you are using an earlier version of this compiler, then the DB2 include files for your applications are in the following directory:

  $HOME/sqllib/include/cobol_a
  

  Specify COPY file names to include the .cbl extension as follows:

  COPY "sql.cbl".
  

DB2 API Applications

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

#! /bin/ksh # bldcobapi script file # Builds a COBOL DB2 API program not containing embedded SQL # Usage: bldcobapi <prog_name> # Set DB2PATH to where DB2 will be accessed. # The default is the standard instance path. DB2PATH=$HOME/sqllib # Compile the checkerr.cbl error checking utility. cob2 -qpgmname\(mixed\) -qlib -I$DB2PATH/include/cobol_a \ -c checkerr.cbl # Compile the program. cob2 -qpgmname\(mixed\) -qlib -I$DB2PATH/include/cobol_a \ -c $1.cbl # Link the program. cob2 -o $1 $1.o checkerr.o -ldb2 -L$DB2PATH/lib

Compile and Link Options for bldcobapi
The script file contains the following compile options: cob2 The IBM COBOL Set compiler. -qpgmname\(mixed\) Instructs the compiler to permit CALLs to library entry points with mixed-case names. -qlib Instructs the compiler to process COPY statements. -I$DB2PATH/include/cobol_a Specify the location of the DB2 include files. For example: $HOME/sqllib/include/cobol_a. -c Perform compile only; no link. This book assumes that compile and link are separate steps.
The script file contains the following link options: cob2 Use the compiler as a front end for the linker. -o $1 Specify the executable program. $1.o Specify the program object file. checkerr.o Include the utility object file for error-checking. -ldb2 Link with the database manager library. -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 sample program client from the source file client.cbl , enter:

   bldcobapi client

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

   client

Embedded SQL Applications

The script file bldcob, in sqllib/samples/cobol, 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
# bldcob script file
# Builds a COBOL program containing embedded SQL
# Usage:  bldcob <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 target ibmcob
 
# Bind the program to the database.
db2 bind $1.bnd
 
# Disconnect from the database.
db2 connect reset
 
# Compile the checkerr.cbl error checking utility.
cob2 -qpgmname\(mixed\) -qlib -I$DB2PATH/include/cobol_a \
     -c checkerr.cbl
 
# Compile the program.
cob2 -qpgmname\(mixed\) -qlib -I$DB2PATH/include/cobol_a \
     -c $1.cbl
 
# Link the program.
cob2 -o $1 $1.o checkerr.o -ldb2 -L$DB2PATH/lib

Compile and Link Options for bldcob
The script file contains the following compile options: cob2 The IBM COBOL Set compiler. -qpgmname\(mixed\) Instructs the compiler to permit CALLs to library entry points with mixed-case names. -qlib Instructs the compiler to process COPY statements. -I$DB2PATH/include/cobol_a Specify the location of the DB2 include files. For example: $HOME/sqllib/include/cobol_a. -c Perform compile only; no link. This book assumes that compile and link are separate steps.
The script file contains the following link options: cob2 Use the compiler as a front end for the linker. -o $1 Specify the executable program. $1.o Specify the program object file. checkerr.o Include the utility object file for error-checking. -ldb2 Link with the database manager library. -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 sample program updat from the source file updat.sqb , enter:

   bldcob 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 bldcobsrv, in sqllib/samples/cobol, 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 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, 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
# bldcobsrv script file
# Build a COBOL stored procedure.
# Usage:  bldcobsrv <stor_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 target ibmcob
 
# Bind the program to the database.
db2 bind $1.bnd
 
# Disconnect from the database.
db2 connect reset
 
# Compile the checkerr.cbl error checking utility.
cob2 -qpgmname\(mixed\) -qlib -I$DB2PATH/include/cobol_a \
     -c checkerr.cbl
 
# Compile the program.
cob2 -qpgmname\(mixed\) -qlib -c -I$DB2PATH/include/cobol_a $1.cbl
 
# Link the program using the export file $1.exp
# creating shared library $1 with entry point $1.
cob2 -o $1 $1.o checkerr.o -H512 -T512 -e $1 -bE:$1.exp \
     -L$DB2PATH/lib -ldb2
 
# 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

Compile and Link Options for bldcobsrv
The script file contains the following compile options: cob2 The IBM COBOL Set compiler. -qpgmname\(mixed\) Instructs the compiler to permit CALLs to library entry points with mixed-case names. -qlib Instructs the compiler to process COPY statements. -c Perform compile only; no link. This book assumes that compile and link are separate steps. -I$DB2PATH/include/cobol_a Specify the location of the DB2 include files. For example: $HOME/sqllib/include/cobol_a.
The script file contains the following link options: cob2 Use the compiler to link edit. -o $1 Specify the output as a shared library file. $1.o Specify the stored procedure object file. checkerr.o Include the utility object file for error-checking. -H512 Specify output file alignment. -T512 Specify output file text segment starting address. -e $1 Specify the default entry point to the shared library. -bE:$1.exp Specify an export file. The export file contains a list of the stored procedures. -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. -ldb2 Link with the database manager library. Refer to your compiler documentation for additional compiler options.

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

   bldcobsrv 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 "IBM COBOL Set for AIX" for details.

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

   outcli remote_database userid password

where

remote_database

Is the name of the database to which you want to connect. The name could be sample, or its remote alias, or some other name.

userid

Is a valid user ID.

password

Is a valid password.

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.

[ DB2 List of Books | Search the DB2 Books ]