Application Building Guide

IBM VisualAge 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 IBM VisualAge COBOL 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, the default.
Do not use tab characters in your source files.
You can use the PROCESS and CBL keywords in your source files to set compile options. Place the keywords in columns 8 to 72 only.
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.
The DB2 COPY files for IBM VisualAge COBOL reside in %DB2PATH%\include\cobol_a under the database instance directory. Specify COPY file names to include the .cbl extension as follows:
```
COPY "sql.cbl".
```

DB2 API Applications

The batch file bldvcapi.bat, in %DB2PATH%\samples\cobol, contains the commands to build a DB2 API program. The parameter, %1, specifies the name of your source file.

@echo off
rem bldvcapi.bat file
rem Build a DB2 API program using the IBM VisualAge COBOL compiler.
rem Usage: bldvcapi <prog_name>
 
rem Compile the error checking facility.
cob2 -qpgmname(mixed) -c -qlib -I%DB2PATH%\include\cobol_a checkerr.cbl
 
rem Compile the program.
cob2 -qpgmname(mixed) -c -qlib -I%DB2PATH%\include\cobol_a %1.cbl
 
rem Link the program.
cob2 %1.obj checkerr.obj db2api.lib
 
goto exit
 
:error
echo Usage: bldvcapi <prog_name>
 
:exit
@echo on

Compile and Link Options for bldvcapi

Compile and Link Options for bldvcapi
The batch file contains the following compile options: `cob2` The IBM VisualAge COBOL compiler. `-qpgmname(mixed)` Instructs the compiler to permit CALLs to library entry points with mixed-case names. `-c` Perform compile only; no link. This book assumes that compile and link are separate steps. `-qlib` Instructs the compiler to process COPY statements. `-I`path Specify the location of the DB2 include files. For example: `-I%DB2PATH%\include\cobol_a`. `checkerr.cbl` Compile the error-checking utility.
The batch file contains the following link options: `cob2` Use the compiler to link edit. `checkerr.obj` Include the error-checking utility object file. `db2api.lib` Link with the DB2 library. Refer to your compiler documentation for additional compiler options.

The batch file contains the following compile options:

cob2: The IBM VisualAge COBOL compiler.
-qpgmname(mixed): Instructs the compiler to permit CALLs to library entry points with mixed-case names.
-c: Perform compile only; no link. This book assumes that compile and link are separate steps.
-qlib: Instructs the compiler to process COPY statements.
-Ipath: Specify the location of the DB2 include files. For example: -I%DB2PATH%\include\cobol_a.
checkerr.cbl: Compile the error-checking utility.

The batch file contains the following link options:

cob2: Use the compiler to link edit.
checkerr.obj: Include the error-checking utility object file.
db2api.lib: Link with the DB2 library.

Refer to your compiler documentation for additional compiler options.

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

 
   bldvcapi client

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

   client

Embedded SQL Applications

The batch file bldvacob.bat, in %DB2PATH%\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.

@echo off
rem bldvacob.bat file
rem Build sample Cobol program using the IBM VisualAge COBOL compiler.
rem Usage: bldvacob <prog_name> [ <db_name> [ < userid> <password> ]]
 
rem Connect to a database.
if "%1" == "" goto error
if "%2" == "" goto case1
if "%3" == "" goto case2
if "%4" == "" goto error
goto case3
:case1
   db2 connect to sample
   goto continue
:case2
   db2 connect to %2
   goto continue
:case3
   db2 connect to %2 user %3 using %4
   goto continue
:continue
 
rem Precompile the program.
db2 prep %1.sqb bindfile target ibmcob
 
rem Bind the program to the database.
db2 bind %1.bnd
 
rem Disconnect from the database.
db2 connect reset
 
rem Compile the error checking facility.
cob2 -qpgmname(mixed) -c -qlib -I%DB2PATH%\include\cobol_a checkerr.cbl
 
rem Compile the program.
cob2 -qpgmname(mixed) -c -qlib -I%DB2PATH%\include\cobol_a %1.cbl
 
rem Link the program.
cob2 %1.obj checkerr.obj db2api.lib
 
goto exit
 
:error
echo Usage: bldvacob <prog_name> [ <db_name> [ < userid> <password> ]]
 
:exit
@echo on

Compile and Link Options for bldvacob

Compile and Link Options for bldvacob
The batch file contains the following compile options: `cob2` The IBM VisualAge COBOL compiler. `-qpgmname(mixed)` Instructs the compiler to permit CALLs to library entry points with mixed-case names. `-c` Perform compile only; no link. This book assumes that compile and link are separate steps. `-qlib` Instructs the compiler to process COPY statements. `-I`path Specify the location of the DB2 include files. For example: `-I%DB2PATH%\include\cobol_a`. `checkerr.cbl` Compile the error-checking utility.
The batch file contains the following link options: `cob2` Use the compiler to link edit. `checkerr.obj` Include the error-checking utility object file. `db2api.lib` Link with the DB2 library. Refer to your compiler documentation for additional compiler options.

The batch file contains the following compile options:

cob2: The IBM VisualAge COBOL compiler.
-qpgmname(mixed): Instructs the compiler to permit CALLs to library entry points with mixed-case names.
-c: Perform compile only; no link. This book assumes that compile and link are separate steps.
-qlib: Instructs the compiler to process COPY statements.
-Ipath: Specify the location of the DB2 include files. For example: -I%DB2PATH%\include\cobol_a.
checkerr.cbl: Compile the error-checking utility.

The batch file contains the following link options:

cob2: Use the compiler to link edit.
checkerr.obj: Include the error-checking utility object file.
db2api.lib: Link with the DB2 library.

Refer to your compiler documentation for additional compiler options.

To build the sample program updat.sqb, enter:

 
   bldvacob updat

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

   updat

Embedded SQL Stored Procedures

The batch file bldvacbs.bat, in %DB2PATH%\samples\cobol, contains the commands to build an embedded SQL stored procedure. The batch file compiles the stored procedure into a DLL on the server.

@echo off
rem bldvacbs.bat file
rem Builds a COBOL stored procedure using the IBM VisualAge COBOL compiler.
rem Usage: bldvacbs <prog_name> [ <db_name> [ < userid> <password> ]]
 
rem Connect to a database.
if "%1" == "" goto error
if "%2" == "" goto case1
if "%3" == "" goto case2
if "%4" == "" goto error
goto case3
:case1
   db2 connect to sample
   goto continue
:case2
   db2 connect to %2
   goto continue
:case3
   db2 connect to %2 user %3 using %4
   goto continue
:continue
 
rem Precompile the program.
db2 prep %1.sqb bindfile target ibmcob
 
rem Bind the program to the database.
db2 bind %1.bnd
 
rem Disconnect from the database.
db2 connect reset
 
rem  Compile the stored procedure.
cob2 -qpgmname(mixed) -c -qlib -I%DB2PATH%\include\cobol_a %1.cbl
 
rem  Link the stored procedure and create a shared library.
lib /nol /gi:%1 %1.obj
ilink /free /nol /dll db2api.lib %1.exp %1.obj iwzrwin3.obj
 
rem Copy stored procedure to the %DB2PATH%\function directory.
rem Substitute the path where DB2 is installed for %DB2PATH%.
copy %1.dll %DB2PATH%\function
 
goto exit
 
:error
echo Usage: bldvacbs <prog_name> [ <db_name> [ < userid> <password> ]]
 
:exit
@echo on

Compile and Link Options for bldvacbs

Compile and Link Options for bldvacbs
The batch file contains the following compile options: `cob2` The IBM VisualAge COBOL compiler. `-qpgmname(mixed)` Instructs the compiler to permit CALLs to library entry points with mixed-case names. `-c` Perform compile only; no link. This book assumes that compile and link are separate steps. `-qlib` Instructs the compiler to process COPY statements. `-I`path Specify the location of the DB2 include files. For example: `-I%DB2PATH%\include\cobol_a`.
The batch file contains the following link options: `ilink` Use the IBM VisualAge COBOL linker. `/free` Free format. `/nol` No logo. `/dll` Create the DLL with the source program name. `db2api.lib` Link with the DB2 library. `%1.exp` Include the export file. `%1.obj` Include the program object file. `iwzrwin3.obj` Include the object file provided by IBM VisualAge COBOL. Refer to your compiler documentation for additional compiler options.

The batch file contains the following compile options:

cob2: The IBM VisualAge COBOL compiler.
-qpgmname(mixed): Instructs the compiler to permit CALLs to library entry points with mixed-case names.
-c: Perform compile only; no link. This book assumes that compile and link are separate steps.
-qlib: Instructs the compiler to process COPY statements.
-Ipath: Specify the location of the DB2 include files. For example: -I%DB2PATH%\include\cobol_a.

The batch file contains the following link options:

ilink: Use the IBM VisualAge COBOL linker.
/free: Free format.
/nol: No logo.
/dll: Create the DLL with the source program name.
db2api.lib: Link with the DB2 library.
%1.exp: Include the export file.
%1.obj: Include the program object file.
iwzrwin3.obj: Include the object file provided by IBM VisualAge COBOL.

Refer to your compiler documentation for additional compiler options.

To build the outsrv stored procedure from the outsrv.sqb source file, enter:

   bldvacbs outsrv

The batch file copies the stored procedure DLL, outsrv.dll, to the server in the path %DB2PATH%\function. For DB2DARI parameter style stored procedures where the invoked procedure matches the stored procedure DLL 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 %DB2PATH%\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.

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 batch file bldvacob. See "Embedded SQL Applications" for details.

To run the stored procedure, enter:

   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.

[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]

[ DB2 List of Books | Search the DB2 Books ]