Application Building Guide

Micro Focus 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 Micro Focus COBOL compiler, keep the following points in mind:

When you precompile your application using the command line processor command db2 prep, use the target mfcob option (the default).
In order to use the built-in precompiler front-end, runtime interpreter or Animator debugger, you have to add the DB2 Generic API entry points to the Micro Focus runtime module rts32 by executing the mkrts command provided by Micro Focus. You also need to run mkcheck to update the check file. If this is not run, you will receive a 173 error in SQLGSTRT.
Before running mkrts and mkcheck, COBOPT must be set in the following steps:
1. Log in as root.
2. From the directory $COBDIR/src/rts enter:
```
   COBOPT=/opt/IBMdb2/V7.1/lib/db2mkrts.args; export COBOPT
   ksh mkrts
   mv $COBDIR/rts32 $COBDIR/rts32.orig
   cp rts32 $COBDIR/rts32
```
3. You must also rebuild the check executable which Hewlett-Packard ships with the product. If you do not rebuild the check executable located in your $COBDIR directory, attempts to compile using cob -C SQL will fail with a run-time system 173 error because the DB2 pre-processor calls the DB2 library. To rebuild check, you should change to the src/sql directory under your $COBDIR directory as root and run the mkcheck script. Once the script completes, you need to move the resulting check executable to your $COBDIR directory. From the directory $COBDIR/src/sql, enter:
```
   COBOPT=/opt/IBMdb2/V7.1/lib/db2mkrts.args; export COBOPT
   ksh mkcheck
   mv $COBDIR/check $COBDIR/check.orig
   cp check $COBDIR/check
```
Now you can execute mkrts with the arguments supplied in the following directory:
```
   /opt/IBMdb2/V7.1/lib/db2mkrts.args
```
You must include the DB2 COBOL COPY file directory in the Micro Focus COBOL environment variable COBCPY. The COBCPY environment variable specifies the location of COPY files. The DB2 COPY files for Micro Focus COBOL reside in sqllib/include/cobol_mf under the database instance directory.
To include the directory, enter:
```
   export COBCPY=$COBCPY:/opt/IBMdb2/V7.1/include/cobol_mf
```
Note: You might want to set COBCPY in the .profile file.

DB2 API and Embedded SQL Applications

The script file bldapp, in sqllib/samples/cobol_mf, contains the commands to build DB2 API and embedded SQL application programs.

The first parameter, $1, specifies the name of your source file. This is the only required parameter, and the only one needed for DB2 API 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 -- HP-UX                           
# Builds a Micro Focus 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
 
# Set COBCPY to include the DB2 COPY files directory.
export COBCPY=$COBCPY:$DB2PATH/include/cobol_mf
 
# Compile the checkerr.cbl error checking utility.
cob +DAportable -cx checkerr.cbl
 
# Compile the program.
cob +DAportable -cx $1.cbl
 
# Link the program.
cob +DAportable -x $1.o checkerr.o -L$DB2PATH/lib -ldb2 -ldb2gmf

Compile and Link Options for bldapp

Compile Options:

cob
The Micro Focus COBOL compiler.
+DAportable
Generates code compatible across PA_RISC 1.x and 2.0 workstations.
-cx
Compile to object module.

Link options:

cob
Use the compiler as a front end for the linker.
+DAportable
Use code compatible across PA_RISC 1.x and 2.0 workstations.
-x
Specify an executable program.
$1.o
Include the program object file.
checkerr.o
Include the utility object file for error checking.
-L$DB2PATH/lib
Specify the location of the DB2 runtime shared libraries. For example: $HOME/sqllib/lib.
-ldb2
Link to the DB2 library.
-ldb2gmf
Link to the DB2 exception-handler library for Micro Focus COBOL.

Refer to your compiler documentation for additional compiler options.

Compile and Link Options for bldapp
Compile Options: `cob` The Micro Focus COBOL compiler. `+DAportable` Generates code compatible across PA_RISC 1.x and 2.0 workstations. `-cx` Compile to object module.
Link options: `cob` Use the compiler as a front end for the linker. `+DAportable` Use code compatible across PA_RISC 1.x and 2.0 workstations. `-x` Specify an executable program. `$1.o` Include the program object file. `checkerr.o` Include the utility object file for error checking. `-L$DB2PATH/lib` Specify the location of the DB2 runtime shared libraries. For example: `$HOME/sqllib/lib`. `-ldb2` Link to the DB2 library. `-ldb2gmf` Link to the DB2 exception-handler library for Micro Focus COBOL. 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:

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 script file bldsrv, in sqllib/samples/cobol_mf, contains the commands to build an embedded SQL 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. 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.

#! /bin/ksh
# bldsrv script file -- HP-UX                           
# Builds a Micro Focus 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
 
# Set COBCPY to include the DB2 COPY files directory.
export COBCPY=$COBCPY:$DB2PATH/include/cobol_mf
 
# Compile the program.
cob +DAportable +z -cx $1.cbl
 
# Link the program.
ld -b -o $1 $1.o -L$DB2PATH/lib -ldb2 -ldb2gmf \
   -L$COBDIR/coblib -lcobol -lcrtn
 
# Copy the shared library to the sqllib/function subdirectory.
# The user must have write permission to this directory.
rm -f $DB2PATH/function/$1
cp $1 $DB2PATH/function

Compile and Link Options for bldsrv

Compile and Link Options for bldsrv
Compile Options: `cob` The COBOL compiler. `+DAportable` Generates code compatible across PA_RISC 1.x and 2.0 workstations. `+z` Generate position-independent code. `-cx` Compile to object module.
Link Options: `ld` Use the linker to link edit. `-b` Create a shared library rather than a normal executable file. `-o $1` Specify the executable. `$1.o` Include the program object file. `-L$DB2PATH/lib` Specify the location of the DB2 runtime shared libraries. For example: `$HOME/sqllib/lib` `-ldb2` Link to the DB2 shared library. `-ldb2gmf` Link to the DB2 exception-handler library for Micro Focus COBOL. `-L$COBDIR/coblib` Specify the location of the COBOL runtime libraries. `-lcobol` Link to the COBOL library. `-lcrtn` Link to the crtn library. Refer to your compiler documentation for additional compiler options.

Compile Options:

cob: The COBOL compiler.
+DAportable: Generates code compatible across PA_RISC 1.x and 2.0 workstations.
+z: Generate position-independent code.
-cx: Compile to object module.

Link Options:

ld: Use the linker to link edit.
-b: Create a shared library rather than a normal executable file.
-o $1: Specify the executable.
$1.o: Include the program object file.
-L$DB2PATH/lib: Specify the location of the DB2 runtime shared libraries. For example: $HOME/sqllib/lib
-ldb2: Link to the DB2 shared library.
-ldb2gmf: Link to the DB2 exception-handler library for Micro Focus COBOL.
-L$COBDIR/coblib: Specify the location of the COBOL runtime libraries.
-lcobol: Link to the COBOL library.
-lcrtn: Link to the crtn library.

Refer to your compiler documentation for additional compiler options.

To build the sample program outsrv from the source file outsrv.sqb, if connecting to the sample database, enter:

   bldsrv outsrv

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

   bldsrv outsrv database

The script file copies the stored procedure to the sqllib/function directory.

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 alias, or another 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.

Exiting the Stored Procedure

When you develop your stored procedures, exit your stored procedure using the following statement:

move SQLZ-HOLD-PROC to return-code.

With this statement, the stored procedure returns correctly to the client application.

[ Top of Page | Previous Page | Next Page ]