Application Building Guide

IBM VisualAge COBOL for OS/2

This section contains the following topics:

Using the Compiler
DB2 API and Embedded SQL Applications
Embedded SQL Stored Procedures

Using the Compiler

These points will help you use the IBM VisualAge COBOL compiler with DB2.

Workaround for Creating Bind Files

When creating applications using DB2 for OS/2 and IBM Cobol, the DB2 precompiler will often fail to create bind files. This is due to a file handle limit within OS/2.

The fix makes OS/2 allow more file handles on the machine performing the compiling. The line:

   SET SHELLHANDLESINC=20

should be inserted into the CONFIG.SYS file on the machine where DB2 for OS/2 is installed. Alternately, one can use the NODATA option when compiling (this is an IBM Cobol option).

Embedded SQL and DB2 API Calls

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.
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 command files provided, the include file path specified in the command 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".
```

Embedded SQL Applications

The command file bldapp.cmd, 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 command 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 command file -- OS/2
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 exist "%1.sqb" goto prepbind
goto compile_step
:prepbind
call embprep %1 %2 %3 %4
 
:compile_step
rem Compile the checkerr error checking utility.
cob2 -c -g -qpgmname(mixed) -qlib -I%DB2PATH%\include\cobol_a checkerr.cbl
 
rem Compile the program.
cob2 -c -g -qpgmname(mixed) -qlib -I%DB2PATH%\include\cobol_a %1.cbl
 
rem Link the program.
ilink %1.obj checkerr.obj db2api.lib /ST:64000 /PM:VIO /NOI /DEBUG
@echo on

Compile and Link Options for bldapp

Compile and Link Options for bldapp
Compile Options: `cob2` The IBM VisualAge COBOL compiler. `-c` Perform compile only; no link. This book assumes that compile and link are separate steps. `-g` Include debug information. `-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`path Specify the location of the DB2 include files. For example: `-I%DB2PATH%\include\cobol_a`.
Link Options: `ilink` Use the ilink linker to link edit. `checkerr.obj` Include the error-checking utility object file. `db2api.lib` Link with the DB2 library. `/ST:64000` Specify a stack size of at least 64000. `/PM:VIO` Enable the program to run in an OS/2 window. `/NOI` Do not ignore case when linking. `/DEBUG` Include debugging information. Refer to your compiler documentation for additional compiler options.

Compile Options:

cob2: The IBM VisualAge COBOL compiler.
-c: Perform compile only; no link. This book assumes that compile and link are separate steps.
-g: Include debug information.
-qpgmname(mixed): Instructs the compiler to permit CALLs to library entry points with mixed-case names.
-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 ilink linker to link edit.
checkerr.obj: Include the error-checking utility object file.
db2api.lib: Link with the DB2 library.
/ST:64000: Specify a stack size of at least 64000.
/PM:VIO: Enable the program to run in an OS/2 window.
/NOI: Do not ignore case when linking.
/DEBUG: Include debugging information.

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 file 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.exe.

There are three ways to run this embedded SQL application:

If accessing the sample database on the same instance, simply enter the executable name (without the file extension):
```
   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 command file bldsrv, in %DB2PATH%\samples\cobol, contains the commands to build a stored procedure. The command 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 built 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 command file uses the source file name, %1, for the DLL name.

@echo off
rem bldsrv command file -- OS/2
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 program.
cob2 -c -g -qpgmname(mixed) -qlib -I%DB2PATH%\include\cobol_a %1.cbl
 
rem Link the program.
ilink %1.obj checkerr.obj %1.def db2api.lib /ST:64000 /PM:VIO /NOI /DEBUG
 
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. `-c` Perform compile only; no link. This book assumes that compile and link are separate steps. `-g` Include debug information. `-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`path Specify the location of the DB2 include files. For example: `-I%DB2PATH%\include\cobol_a`.
Link Options: `ilink` Use the ilink linker to link edit. `checkerr.obj` Include the error-checking utility object file. `%1.def` Module definition file. `db2api.lib` Link with the DB2 library. `/ST:64000` Specify a stack size of at least 64000. `/PM:VIO` Enable the program to run in an OS/2 window. `/NOI` Do not ignore case when linking. `/DEBUG` Include debugging information. Refer to your compiler documentation for additional compiler options.

Compile Options:

cob2: The IBM VisualAge COBOL compiler.
-c: Perform compile only; no link. This book assumes that compile and link are separate steps.
-g: Include debug information.
-qpgmname(mixed): Instructs the compiler to permit CALLs to library entry points with mixed-case names.
-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 ilink linker to link edit.
checkerr.obj: Include the error-checking utility object file.
%1.def: Module definition file.
db2api.lib: Link with the DB2 library.
/ST:64000: Specify a stack size of at least 64000.
/PM:VIO: Enable the program to run in an OS/2 window.
/NOI: Do not ignore case when linking.
/DEBUG: Include debugging information.

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 command file uses the module definition file, outsrv.def, contained in the same directory as the sample programs, to build the DLL. The command file copies the stored procedure DLL, outsrv.dll, on the server in the path %DB2PATH%\function.

If necessary, set the file mode for the DLL so the client application can access it.

Once you build the DLL, outsrv, you can build the client application outcli that accesses the DLL. You can build outcli using the command file, bldapp. Refer to "Embedded SQL Applications" for details.

To call the stored procedure, run the 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 DLL, outsrv, and 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 ]