Application Building Guide

VisualAge C++ Version 4.0

This VisualAge C++ compiler is for AIX, OS/2, and Windows 32-bit operating systems. The information in this section applies to all these platforms.

The VisualAge C++ compiler differs from other compilers documented in this book. To compile a program with VisualAge C++ Version 4.0, you must first make a configuration file. See the documentation that comes with the compiler to learn more about this.

DB2 provides configuration files for the different types of DB2 programs you can build with the VisualAge C++ compiler. To use a DB2 configuration file, you first set an environment variable to the program name you wish to compile. Then you compile the program with a command supplied by VisualAge C++. Here are the configuration files provided by DB2, and the sections describing how they can be used to compile your programs:

cli.icc: DB2 CLI configuration file. For details, see "DB2 CLI Applications".
cliapi.icc: DB2 CLI with DB2 APIs configuration file. For details, see "DB2 CLI Applications with DB2 APIs".
clis.icc: DB2 CLI stored procedure configuration file. For details, see "DB2 CLI Stored Procedures".
api.icc: DB2 API configuration file. For details, see "DB2 API Applications".
emb.icc: Embedded SQL configuration file. For details, see "Embedded SQL Applications".
stp.icc: Embedded SQL stored procedure configuration file. For details, see "Embedded SQL Stored Procedures".
udf.icc: User-defined function configuration file. For details, see "User-Defined Functions (UDFs)".

DB2 CLI Applications

The configuration file, cli.icc, in sqllib/samples/cli on AIX, and in %DB2PATH%\samples\cli on OS/2 and Windows 32-bit operating systems, allows you to build DB2 CLI programs.

// cli.icc configuration file for DB2 CLI applications
// for VisualAge C++ Version 4.0
// To use on AIX, enter: 'export CLI=prog_name'
// To use on OS/2 and Windows, enter: 'set CLI=prog_name'
// Then compile the program by entering: 'vacbld cli.icc'
 
if defined( $CLI )
{
  prog_name = $CLI
}
else
{
  error "Environment Variable CLI is not defined."
}
 
infile   = prog_name".c"
utilcli = "utilcli.c"
 
if defined( $__TOS_AIX__ )
{
  // Set db2path to where DB2 will be accessed. 
  // The default is the standard instance path.
  db2path     = $HOME"/sqllib"
  outfile     = prog_name
  group lib   = "libdb2.a"
  option opts = link( libsearchpath, db2path"/lib" ),
                incl( searchPath, db2path"/include" )
}
else // if defined( $__TOS_OS2__ ) | defined( $__TOS_WIN__ )
{
  db2path     = $DB2PATH
  outfile     = prog_name".exe"
  group lib   = "db2cli.lib"
  option opts = link( libsearchpath, db2path"\\lib" ),
                incl( searchPath, db2path"\\include" )
}
 
option opts
{
  target type(exe) outfile
  {
    source infile
    source utilcli
    source lib
  }
}

VisualAge C++ Version 4.0 defines one of the following environment variables depending on the operating system on which it is installed: __TOS_AIX__, __TOS_OS2__, __TOS_WIN__.

To use the configuration file to build the DB2 CLI sample program tbinfo from the source file tbinfo.c, do the following:

Set the CLI environment variable to the program name by entering:
```
   export CLI=tbinfo
```
If you have a cli.ics file in your working directory, produced by building a different program with the cli.icc file, delete the cli.ics file with this command:
```
   rm cli.ics
```
An existing cli.ics file produced for the same program you are going to build again does not have to be deleted.
Compile the sample program by entering:
```
   vacbld cli.icc
```
Note: The vacbld command is provided by VisualAge C++ Version 4.0.

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

   tbinfo

Building and Running Embedded SQL Applications

You can use the cli.icc configuration file to compile an embedded SQL program after the program is precompiled with the embprep file on AIX, embprep.cmd on OS/2, or embprep.bat on Windows 32-bit operating systems. This file precompiles the source file and binds the program to the database.

There are three ways to precompile the embedded SQL application, dbusemx, from the source file dbusemx.sqc:

If connecting to the sample database on the same instance, enter:
```
   embprep dbusemx
```
If connecting to another database on the same instance, also enter the database name:
```
   embprep dbusemx database
```
If connecting to a database on another instance, also enter the user ID and password of the database instance:
```
   embprep dbusemx database userid password
```

The result is a precompiled C file, dbusemx.c.

After it is precompiled, the C file can be compiled with the cli.icc file, as follows:

Set the CLI environment variable to the program name by entering:
```
   export CLI=dbusemx
```
If you have a cli.ics file in your working directory, produced by building a different program with the cli.icc file, delete the cli.ics file with this command:
```
   rm cli.ics
```
An existing cli.ics file produced for the same program you are going to build again does not have to be deleted.
Compile the sample program by entering:
```
   vacbld cli.icc
```
Note: The vacbld command is provided by VisualAge C++ Version 4.0.

There are three ways to run this embedded SQL application:

If accessing the sample database on the same instance, simply enter the executable name:
```
   dbusemx
```
If accessing another database on the same instance, enter the executable name and the database name:
```
   dbusemx database
```
If accessing a database on another instance, enter the executable name, database name, and user ID and password of the database instance:
```
   dbusemx database userid password
```

DB2 CLI Applications with DB2 APIs

DB2 includes CLI sample programs that use DB2 APIs to create and drop a database in order to demonstrate using CLI functions with more than one database. The descriptions of the CLI sample programs in Table 7 indicates the samples that use DB2 APIs. The configuration file, cliapi.icc, in sqllib/samples/cli on AIX, and in %DB2PATH%\samples\cli on OS/2 and Windows 32-bit operating systems, allows you to build DB2 CLI programs with DB2 APIs.

This file compiles and links in the utilapi utility file, which contains the DB2 APIs to create and drop a database. This is the only difference between this file and the cli.icc configuration file.

To build the DB2 CLI sample program, dbmconn, from the source file dbmconn.c, do the following:

Set the CLIAPI environment variable to the program name by entering:
```
   export CLIAPI=dbmconn
```
If you have a cliapi.ics file in your working directory, produced by building a different program with the cliapi.icc file, delete the cliapi.ics file with this command:
```
   rm cliapi.ics
```
An existing cliapi.ics file produced for the same program you are going to build again does not have to be deleted.
Compile the sample program by entering:
```
   vacbld cliapi.icc
```
Note: The vacbld command is provided by VisualAge C++ Version 4.0.

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

   dbmconn

DB2 CLI Stored Procedures

The configuration file, clis.icc, in sqllib/samples/cli on AIX, and in %DB2PATH%\samples\cli on OS/2 and Windows 32-bit operating systems, allows you to build DB2 CLI stored procedures.

// clis.icc configuration file for DB2 CLI stored procedures
// for VisualAge C++ Version 4.0
// To use on AIX, enter: 'export CLIS=prog_name'
// To use on OS/2 and Windows, enter: 'set CLIS=prog_name'
// Then compile the program by entering: 'vacbld clis.icc'
 
if defined( $CLIS )
{
  prog_name = $CLIS
}
else
{
  error "Environment Variable CLIS is not defined."
}
 
infile = prog_name".c"
utilcli = "utilcli.c"
expfile = prog_name".exp"
 
if defined( $__TOS_AIX__ )
{
  // Set db2path to where DB2 will be accessed. 
  // The default is the standard instance path. 
  db2path     = $HOME"/sqllib"
  outfile     = prog_name 
  group lib   = "libdb2.a"
  option opts = link( exportList, expfile ),
                link( libsearchpath, db2path"/lib" ),
                incl( searchPath, db2path"/include" )
  cpcmd       = "cp"
  funcdir     = db2path"/function"
}
else /* if defined( $__TOS_OS2__ ) | defined( $__TOS_WIN__ ) */
{
  db2path     = $DB2PATH
  outfile     = prog_name".dll"
  if defined( $__TOS_WIN__ )
  {
    expfile = prog_name"v4.exp" 
  }
  group lib   = "db2cli.lib"
  option opts = link( exportList, expfile ),
                link( libsearchpath, db2path"\\lib" ),
                incl( searchPath, db2path"\\include" )
  cpcmd       = "copy"
  funcdir     = db2path"\\function"
}
 
option opts
{
  target type(dll) outfile
  {
    source infile
    source utilcli
    source lib
  }
}
 
if defined( $__TOS_AIX__ )
{
  rmcmd       = "rm -f"
  run after rmcmd " " funcdir "/" outfile
}
 
run after cpcmd " " outfile " " funcdir

VisualAge C++ Version 4.0 defines one of the following environment variables depending on the operating system on which it is installed: __TOS_AIX__, __TOS_OS2__, __TOS_WIN__.

To use the configuration file to build the DB2 CLI stored procedure spserver from the source file spserver.c, do the following:

Set the CLIS environment variable to the program name by entering:
```
   export CLIS=spserver
```
If you have a clis.ics file in your working directory, produced by building a different program with the clis.icc file, delete the clis.ics file with this command:
```
   rm clis.ics
```
An existing clis.ics file produced for the same program you are going to build again does not have to be deleted.
Compile the sample program by entering:
```
   vacbld clis.icc
```
Note: The vacbld command is provided by VisualAge C++ Version 4.0.

The stored procedure is copied to the server in the path sqllib/function on AIX, and in the path %DB2PATH%\function on OS/2 and Windows 32-bit operating systems.

Next, catalog the stored procedures by running the spcreate.db2 script on the server. First, connect to the database with the user ID and password of the instance where the database is located:

   db2 connect to sample userid password

If the stored procedures were previously cataloged, you can drop them with this command:

   db2 -td@ -vf spdrop.db2

Then catalog them with this command:

   db2 -td@ -vf spcreate.db2

Then, stop and restart the database to allow the new shared library to be recognized. If necessary, set the file mode for the shared library so the DB2 instance can access it.

Once you build the stored procedure spserver, you can build the CLI client application spclient that calls the stored procedure. You can build spclient by using the configuration file, cli.icc. Refer to "DB2 CLI Applications" for details.

To call the stored procedure, run the sample client application by entering:

spclient 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, spserver, and executes a number of stored procedure functions on the server database. The output is returned to the client application.

DB2 API Applications

The configuration file, api.icc, in sqllib/samples/c and in sqllib/samples/cpp on AIX, and in %DB2PATH%\samples\c and in %DB2PATH%\samples\c on OS/2 and Windows 32-bit operating systems, allows you to build DB2 API programs in C or C++.

// api.icc configuration file for DB2 API programs
// for VisualAge C++ Version 4.0
// To use on AIX, enter: 'export API=prog_name'
// To use on OS/2 and Windows, enter: 'set API=prog_name'
// Then compile the program by entering: 'vacbld api.icc'
 
if defined( $API )
{
  prog_name = $API
}
else
{
  error "Environment Variable API is not defined."
}
 
infile = prog_name".c"
util   = "utilapi.c"
 
if defined( $__TOS_AIX__ )
{
  // Set db2path to where DB2 will be accessed. 
  // The default is the standard instance path.
  db2path     = $HOME"/sqllib"
  outfile     = prog_name
  group lib   = "libdb2.a"
  option opts = link( libsearchpath, db2path"/lib" ),
                incl( searchPath, db2path"/include" )
}
else // if defined( $__TOS_OS2__ ) | defined( $__TOS_WIN__ )
{
  db2path     = $DB2PATH
  outfile     = prog_name".exe"
  group lib   = "db2api.lib"
  option opts = link( libsearchpath, db2path"\\lib" ),
                incl( searchPath, db2path"\\include" )
}
 
option opts
{
  target type(exe) outfile
  {
    source infile
    source util
    source lib
  }
}

VisualAge C++ Version 4.0 defines one of the following environment variables depending on the operating system on which it is installed: __TOS_AIX__, __TOS_OS2__, __TOS_WIN__.

To use the configuration file to build the DB2 API sample program client from the source file client.c, do the following:

Set the API environment variable to the program name by entering:
```
   export API=client
```
If you have an api.ics file in your working directory, produced by building a different program with the api.icc file, delete the api.ics file with this command:
```
   rm api.ics
```
An existing api.ics file produced for the same program you are going to build again does not have to be deleted.
Compile the sample program by entering:
```
   vacbld api.icc
```
Note: The vacbld command is provided by VisualAge C++ Version 4.0.

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

   client

Embedded SQL Applications

The configuration file, emb.icc, in sqllib/samples/c and sqllib/samples/cpp on AIX, and in %DB2PATH%\samples\c and %DB2PATH%\samples\cpp on OS/2 and Windows 32-bit operating systems, allows you to build DB2 embedded SQL applications in C and C++.

// emb.icc configuration file for embedded SQL applications
// for VisualAge C++ Version 4.0
// To use on AIX, enter: 'export EMB=prog_name'
// To use on OS/2 and Windows, enter: 'set EMB=prog_name'
// Then compile the program by entering: 'vacbld emb.icc'
 
if defined( $EMB )
{
  prog_name = $EMB
}
else
{
  error "Environment Variable EMB is not defined."
}
 
// To connect to another database, replace "sample"
// For user ID and password, update 'user' and 'passwd'
// and take out the comment in the line: 'run before "embprep "'
dbname = "sample"
user   = ""
passwd = ""
 
// Precompiling the source program file
run before "embprep " prog_name " " dbname // " " user " " passwd
 
infile = prog_name".c"
util = "utilemb.sqc"
 
if defined( $__TOS_AIX__ )
{
  // Set db2path to where DB2 will be accessed. 
  // The default is the standard instance path.
  db2path     = $HOME"/sqllib"
  outfile     = prog_name
  group lib   = "libdb2.a"
  option opts = link( libsearchpath, db2path"/lib" ),
                incl( searchPath, db2path"/include" )
}
else // if defined( $__TOS_OS2__ ) | defined( $__TOS_WIN__ )
{
  db2path     = $DB2PATH
  outfile     = prog_name".exe"
  group lib   = "db2api.lib"
  option opts = link( libsearchpath, db2path"\\lib" ),
                incl( searchPath, db2path"\\include" )
}
 
option opts
{
  target type(exe) outfile
  {
    source infile
    source util
    source lib
  }
}

VisualAge C++ Version 4.0 defines one of the following environment variables depending on the operating system on which it is installed: __TOS_AIX__, __TOS_OS2__, __TOS_WIN__.

To use the configuration file to build the embedded SQL application updat from the source file updat.sqc, do the following:

Set the EMB environment variable to the program name by entering:
```
   export EMB=updat
```
If you have an emb.ics file in your working directory, produced by building a different program with the emb.icc file, delete the emb.ics file with this command:
```
   rm emb.ics
```
An existing emb.ics file produced for the same program you are going to build again does not have to be deleted.
Compile the sample program by entering:
```
   vacbld emb.icc
```
Note: The vacbld command is provided by VisualAge C++ Version 4.0.

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

   updat

Embedded SQL Stored Procedures

The configuration file, stp.icc, in sqllib/samples/c and sqllib/samples/cpp on AIX, and in %DB2PATH%\samples\c and %DB2PATH%\samples\cpp on OS/2 and Windows 32-bit operating systems, allows you to build DB2 embedded SQL stored procedures in C and C++.

// stp.icc configuration file for embedded SQL stored procedures
// for VisualAge C++ Version 4.0
// To use on AIX, enter: 'export STP=prog_name'
// To use on OS/2 and Windows, enter: 'set STP=prog_name'
// Then compile the program by entering: 'vacbld emb.icc'
 
if defined( $STP )
{
  prog_name = $STP
}
else
{
  error "Environment Variable STP is not defined."
}
 
// To connect to another database, replace "sample"
// For user ID and password, update 'user' and 'passwd'
// and take out the comment in the line: 'run before "embprep "'
dbname = "sample"
user   = ""
passwd = ""
 
// Precompiling the source program file
run before "embprep " prog_name " " dbname // " " user " " passwd
 
infile = prog_name".c"
expfile = prog_name".exp"
 
if defined( $__TOS_AIX__ )
{
  // Set db2path to where DB2 will be accessed. 
  // The default is the standard instance path. 
  db2path     = $HOME"/sqllib"
  outfile     = prog_name 
  group lib   = "libdb2.a"
  option opts = link( exportList, expfile ),
                link( libsearchpath, db2path"/lib" ),
                incl( searchPath, db2path"/include" )
  cpcmd       = "cp"
  funcdir     = db2path"/function"
}
else // if defined( $__TOS_OS2__ ) | defined( $__TOS_WIN__ ) 
{
  db2path     = $DB2PATH
  outfile     = prog_name".dll"
  if defined( $__TOS_WIN__ )
  {
    expfile = prog_name"v4.exp" 
  }
  group lib   = "db2api.lib"
  option opts = link( exportList, expfile ),
                link( libsearchpath, db2path"\\lib" ),
                incl( searchPath, db2path"\\include" )
  cpcmd       = "copy"
  funcdir     = db2path"\\function"
}
 
option opts
{
  target type(dll) outfile
  { 
    source infile
    source lib
  }
}
 
if defined( $__TOS_AIX__ )
{
  rmcmd       = "rm -f"
  run after rmcmd " " funcdir "/" outfile
}
 
run after cpcmd " " outfile " " funcdir

VisualAge C++ Version 4.0 defines one of the following environment variables depending on the operating system on which it is installed: __TOS_AIX__, __TOS_OS2__, __TOS_WIN__.

To use the configuration file to build the embedded SQL stored procedure spserver from the source file spserver.sqc, do the following:

Set the STP environment variable to the program name by entering:
```
   export STP=spserver
```
If you have an stp.ics file in your working directory, produced by building a different program with the stp.icc file, delete the stp.ics file with this command:
```
   rm stp.ics
```
An existing stp.ics file produced for the same program you are going to build again does not have to be deleted.
Compile the sample program by entering:
```
   vacbld stp.icc
```
Note: The vacbld command is provided by VisualAge C++ Version 4.0.

The stored procedure is copied to the server in the path sqllib/function on AIX, and in the path %DB2PATH%\function on OS/2 and Windows 32-bit operating systems.

Next, catalog the stored procedures by running the spcreate.db2 script on the server. First, connect to the database:

   db2 connect to sample

If the stored procedures were previously cataloged, you can drop them with this command:

   db2 -td@ -vf spdrop.db2

Then catalog them with this command:

   db2 -td@ -vf spcreate.db2

Then, stop and restart the database to allow the new shared library to be recognized. If necessary, set the file mode for the shared library so the DB2 instance can access it.

Once you build the stored procedure, spserver, you can build the client application, spclient, that calls the stored procedure. You can build spclient using the configuration file, emb.icc. Refer to "Embedded SQL Applications" for details.

To call the stored procedure, run the sample client application by entering:

spclient 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, spserver, and executes a number of stored procedure functions on the server database. The output is returned to the client application.

User-Defined Functions (UDFs)

The configuration file, udf.icc, in sqllib/samples/c and sqllib/samples/cpp on AIX, and in %DB2PATH%\samples\c and %DB2PATH%\samples\cpp on OS/2 and Windows 32-bit operating systems, allows you to build user-defined functions in C and C++.

// udf.icc configuration file for user-defined functions
// for VisualAge C++ Version 4.0
// To use on AIX, enter: 'export UDF=prog_name'
// To use on OS/2 and Windows, enter: 'set UDF=prog_name'
// Then compile the program by entering: 'vacbld udf.icc'
 
if defined( $UDF )
{
  prog_name = $UDF
}
else
{
  error "Environment Variable UDF is not defined."
}
 
infile = prog_name".c"
expfile = prog_name".exp"
 
if defined( $__TOS_AIX__ )
{
  // Set db2path to where DB2 will be accessed. 
  // The default is the standard instance path.
  db2path     = $HOME"/sqllib"
  outfile     = prog_name
  group lib   = "libdb2.a", "libdb2apie.a"
  option opts = link( exportList, expfile ),
                link( libsearchpath, db2path"/lib" ),
                incl( searchPath, db2path"/include" )
  cpcmd       = "cp"
  funcdir     = db2path"/function"
}
else // if defined( $__TOS_OS2__ ) | defined( $__TOS_WIN__ ) 
{
  db2path     = $DB2PATH
  outfile     = prog_name".dll"
  if defined( $__TOS_WIN__ )
  {
    expfile = prog_name"v4.exp"
  }
  group lib   = "db2api.lib", "db2apie.lib"
  option opts = link( exportList, expfile ),
                link( libsearchpath, db2path"\\lib" ),
                incl( searchPath, db2path"\\include" )
  cpcmd       = "copy"
  funcdir     = db2path"\\function"
}
 
option opts
{
  target type(dll) outfile
  {
    source infile
    source lib
  }
}
if defined( $__TOS_AIX__ )
{
  rmcmd       = "rm -f"
  run after rmcmd " " funcdir "/" outfile
}
 
run after cpcmd " " outfile " " funcdir

VisualAge C++ Version 4.0 defines one of the following environment variables depending on the operating system on which it is installed: __TOS_AIX__, __TOS_OS2__, __TOS_WIN__.

To use the configuration file to build the user-defined function program udfsrv from the source file udf.c, do the following:

Set the UDF environment variable to the program name by entering:
```
   export UDF=udfsrv
```
If you have a udf.ics file in your working directory, produced by building a different program with the udf.icc file, delete the udf.ics file with this command:
```
   rm udf.ics
```
An existing udf.ics file produced for the same program you are going to build again does not have to be deleted.
Compile the sample program by entering:
```
   vacbld udf.icc
```
Note: The vacbld command is provided by VisualAge C++ Version 4.0.

The UDF library is copied to the server in the path sqllib/function.

If necessary, set the file mode for the user-defined function so the DB2 instance can run it.

Once you build udfsrv, you can build the client application, udfcli, that calls it. DB2 CLI and embedded SQL versions of this program are provided.

You can build the DB2 CLI udfcli program from the source file udfcli.c, in sqllib/samples/cli on AIX, and in %DB2PATH%\samples\cli on OS/2 and Windows 32-bit operating systems, by using the configuration file cli.icc. Refer to "DB2 CLI Applications" for details.

You can build the embedded SQL udfcli program from the source file udfcli.sqc, in sqllib/samples/c on AIX, and in %DB2PATH%\samples\cli on OS/2 and Windows 32-bit operating systems, by using the configuration file emb.icc. Refer to "Embedded SQL Applications" for details.

To call the UDF, run the sample calling application by entering the executable name:

   udfcli

The calling application calls the ScalarUDF function from the udfsrv library.

[ Top of Page | Previous Page | Next Page ]