Application Building Guide

IBM VisualAge COBOL

This section contains 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 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.
If you are using the "System/390 host data type support" feature of the IBM VisualAge COBOL compiler, the DB2 include files for your applications are in the following directory:
```
%DB2PATH%\include\cobol_i
```
If you are building DB2 sample programs using the batch files provided, the include file path specified in the batch 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 VisualAge COBOL compiler, or you are using an earlier version of this compiler, then the DB2 include files for your applications are in the following directory:
```
%DB2PATH%\include\cobol_a
```
Specify COPY file names to include the .cbl extension as follows:
```
COPY "sql.cbl".
```

DB2 API and Embedded SQL Applications

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

@echo off
rem bldapp.bat  -- Windows 32-bit operating systems
rem Builds a VisualAge COBOL application program
rem Usage: bldapp <prog_name> [ <db_name> [ <userid> <password> ]] 
 
rem If an embedded SQL program, precompile and bind it.
if not exist "%1.sqb" goto compile_step
call embprep %1 %2 %3 %4
 
:compile_step
rem Compile the error-checking utility.
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
@echo on

Compile and Link Options for bldapp

Compile and Link Options for bldapp
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.
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.

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.

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 non-embedded SQL sample program client from the source file client.cbl, enter:

   bldapp client

The result is an executable file client.exe. You can run the executable file against the sample database by entering the executable name (without the extension):

   client

Building and Running Embedded SQL Applications

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

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

If accessing the sample database on the same instance, simply enter the executable name:
```
   updat
```
If accessing another database on the same instance, enter the executable name and the database name:
```
   updat database
```
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 batch file bldsrv.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.

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 batch file uses the source file name, %1, for the DLL name.

@echo off
rem bldsrv.bat  -- Windows 32-bit operating systems 
rem Builds a VisualAge COBOL stored procedure
rem Usage: bldsrv <prog_name> [ <db_name> ] 
 
rem Precompile and bind the program.
call embprep %1 %2
 
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.
ilib /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.
copy %1.dll "%DB2PATH%\function"
@echo on

Compile and Link Options for bldsrv

Compile and Link Options for bldsrv
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 batch file has separate compile and link 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"`.
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.

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 batch file has separate compile and link 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".

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 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 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 batch 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 stored procedure library, outsrv, which executes the stored procedure function of the same name on the server database, and then returns the output to the client application.

[ Top of Page | Previous Page | Next Page ]