Application Building Guide

IBM VisualAge C++ for OS/2 Version 4.0

The VisualAge C++ compiler differs from other compilers on OS/2. 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:

api.icc: DB2 API configuration file. For details, see "DB2 API Applications".
cli.icc: DB2 CLI configuration file. For details, see "DB2 CLI Applications".
clis.icc: DB2 CLI stored procedure configuration file. For details, see "DB2 CLI Stored Procedures".
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 API Applications

The configuration file, api.icc, in %DB2PATH%\samples\c, allows you to build DB2 API programs in C. There is also a C++ DB2 API configuration file in %DB2PATH%\samples\cpp. These files can be used on AIX, OS/2 and Windows 32-bit operating systems.

// 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   = "util.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:
```
   set 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:
```
   del 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

DB2 CLI Applications

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

// 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"
samputil = "samputil.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 samputil
    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 basiccon from the source file basiccon.c, do the following:

Set the CLI environment variable to the program name by entering:
```
   set CLI=basiccon
```
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:
```
   del 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, basiccon. You can run the program by entering the executable name:

   basiccon

DB2 CLI Stored Procedures

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

// 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"
samputil = "samputil.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 samputil
    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 outsrv2 from the source file outsrv2.c, do the following:

Set the CLIS environment variable to the program name by entering:
```
   set CLIS=outsrv2
```
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:
```
   del 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 %DB2PATH%\function. For DB2DARI parameter style stored procedures where the invoked procedure matches the shared library 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.

If necessary, set the file mode for the stored procedure so the DB2 instance can run it.

Once you build the stored procedure outsrv2, you can build the CLI client application outcli2 that calls the stored procedure. You can build outcli2 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:

outcli2 remote_database userid password

where

remote_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 passes a variable to the server program outsrv2, which gives it a value and then returns the variable to the client application.

Embedded SQL Applications

The configuration file, emb.icc, in %DB2PATH%\samples\c, allows you to build DB2 embedded SQL applications in C. There is also a C++ configuration file for embedded SQL applications, in %DB2PATH%\samples\cpp. These files can be used on AIX, OS/2 and Windows 32-bit operating systems.

// 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   = "util.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 embedded SQL application updat from the source file updat.sqc, do the following:

Set the EMB environment variable to the program name by entering:
```
   set 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:
```
   del 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 %DB2PATH%\samples\c, allows you to build DB2 embedded SQL stored procedures in C. There is also a C++ configuration file for embedded SQL stored procedures in %DB2PATH%\samples\cpp. These files can be used on AIX, OS/2 and Windows 32-bit operating systems.

// 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"
util   = "util.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 util
    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 outsrv from the source file outsrv.sqc, do the following:

Set the STP environment variable to the program name by entering:
```
   set STP=outsrv
```
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:
```
   del 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.

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 configuration file emb.icc. Refer to "Embedded SQL Applications" for details.

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

outcli remote_database userid password

where

remote_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 passes a variable to the server program outsrv, which gives it a value and then returns the variable to the client application.

User-Defined Functions (UDFs)

The configuration file, udf.icc, in %DB2PATH%\samples\c, allows you to build user-defined functions in C. There is also a C++ configuration file for user-defined functions in %DB2PATH%\samples\cpp. These files can be used on AIX, OS/2 and Windows 32-bit operating systems.

// 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 udf from the source file udf.c, do the following:

Set the UDF environment variable to the program name by entering:
```
   set UDF=udf
```
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:
```
   del 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 %DB2PATH%\function.

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

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

You can build the DB2 CLI calludf program from the source file calludf.c, in %DB2PATH%\samples\cli, by using the configuration file cli.icc. Refer to "DB2 CLI Applications" for details.

You can build the embedded SQL calludf.sqc program from the source file calludf.sqc, in %DB2PATH%\samples\c, 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:

   calludf

The calling application calls functions from the udf library.

After you run the calling application, you can also invoke the UDF interactively using the command line processor like this:

   db2 "SELECT name, DOLLAR(salary), SAMP_MUL(DOLLAR(salary), FACTOR(1.2)) FROM staff"

You do not have to type the command line processor keywords in uppercase.

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

[ DB2 List of Books | Search the DB2 Books ]