Application Building Guide

IBM COBOL Set for AIX

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 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 and Embedded SQL Applications

The build file, bldapp, in sqllib/samples/cobol, 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 an IBM 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
 
# 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 bldapp
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. Compile and link are separate steps.
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 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

The script file bldsrv, in sqllib/samples/cobol, 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 an IBM 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
 
# 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 bldsrv
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.
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 , connecting to the sample database, enter:

   bldsrv outsrv

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

   bldsrv outsrv database

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

If necessary, set the file mode for the stored procedure so the client application can access 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 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 remote alias, or some other 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, and then returns the output to the client application.