Application Building Guide

ptx/C++

This section covers the following topics:

DB2 API and Embedded SQL Applications
Embedded SQL Stored Procedures
User-defined Functions (UDFs)
Multi-threaded Applications

DB2 API and Embedded SQL Applications

The build file, bldapp, in sqllib/samples/cpp, contains the commands to build DB2 API and embedded SQL 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 -- PTX # Builds a C++ application program # Usage: bldapp <prog_name> [ <db_name> [ <userid> <password> ]] # Set DB2PATH to the location 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".sqC" ]] then embprep $1 $2 $3 $4 # Compile the utilemb.C error-checking utility. c++ -I$DB2PATH/include -D_RWSTD_COMPILE_INSTANTIATE=0 -c utilemb.C else # Compile the utilapi.C error-checking utility. c++ -I$DB2PATH/include -D_RWSTD_COMPILE_INSTANTIATE=0 -c utilapi.C fi # Compile the program. c++ -I$DB2PATH/include -D_RWSTD_COMPILE_INSTANTIATE=0 -c $1.C if [[ -f $1".sqC" ]] then # Link the program with utilemb.o c++ -o $1 $1.o utilemb.o -L$DB2PATH/lib -ldb2 -lseq else # Link the program with utilapi.o c++ -o $1 $1.o utilapi.o -L$DB2PATH/lib -ldb2 -lseq fi

Compile and Link Options for bldapp

Compile Options:

c++
The C++ compiler.
-I$DB2PATH/include
Specifies the location of the DB2 include files. For example: $HOME/sqllib/include
-D_RWSTD_COMPILE_INSTANTIATE=0
Do not instantiate the rogue wave classes.
-c
Perform compile only, no link. Compile and link are separate steps.

Link Options:

c++
Use the compiler as a front end for the linker.
-o $1
Specify the executable.
$1.o
Include the program object file.
utilemb.o
If an embedded SQL program, include the embedded SQL utility object file for error checking.
utilapi.o
If a non-embedded SQL program, include the DB2 API utility object file for error checking.
-L$DB2PATH/lib
Specify the location of the DB2 static and shared libraries at link-time. For example: $HOME/sqllib/lib. If you do not specify the -L option, /usr/lib:/lib is assumed.
-ldb2
Link with the DB2 library.
-lseq
Link with the Sequent library.

Refer to your compiler documentation for additional compiler options.

Compile and Link Options for bldapp
Compile Options: `c++` The C++ compiler. `-I$DB2PATH/include` Specifies the location of the DB2 include files. For example: `$HOME/sqllib/include` `-D_RWSTD_COMPILE_INSTANTIATE=0` Do not instantiate the rogue wave classes. `-c` Perform compile only, no link. Compile and link are separate steps.
Link Options: `c++` Use the compiler as a front end for the linker. `-o $1` Specify the executable. `$1.o` Include the program object file. `utilemb.o` If an embedded SQL program, include the embedded SQL utility object file for error checking. `utilapi.o` If a non-embedded SQL program, include the DB2 API utility object file for error checking. `-L$DB2PATH/lib` Specify the location of the DB2 static and shared libraries at link-time. For example: `$HOME/sqllib/lib`. If you do not specify the `-L` option, `/usr/lib:/lib` is assumed. `-ldb2` Link with the DB2 library. `-lseq` Link with the Sequent library. Refer to your compiler documentation for additional compiler options.

To build the DB2 API non-embedded SQL sample program, client, from the source file client.C, enter:

   bldapp client

The result is an executable file, client.

To run the executable file, enter the executable name:

   client

Building and Running Embedded SQL Applications

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

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

Note:

Please see the information for building C++ stored procedures in "C++ Considerations for UDFs and Stored Procedures".

The script file, bldsrv, in sqllib/samples/cpp, contains the commands to build an embedded SQL stored procedure. The script file compiles the stored procedure into a shared library that can be called by a client application.

The first parameter, $1, specifies the name of your source file. This is the only required parameter. Building embedded SQL programs requires a connection to the database so an additional optional parameter, $2, specifies the name of the database to which you want to connect. If no database name is supplied, the default sample database is used. Since the stored procedure must be built on the same instance where the database resides, no additional parameters for user ID and password are needed. The script file, bldsrv, passes the parameters to the precompile and bind file, embprep.

The source file name, $1, is used for the shared library name.

#! /bin/ksh
# bldsrv script file -- PTX                                
# Builds a C++ 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
 
# Compile the program. First ensure it is coded with extern "C".
c++ -KPIC -I$DB2PATH/include -D_RWSTD_COMPILE_INSTANTIATE=0 -c $1.C
 
# Link the program and create a shared library.          
c++ -G -o $1 $1.o -L$DB2PATH/lib -ldb2
  
# Copy the shared library to the sqllib/function subdirectory. 
# Note: the user must have write permission to this directory.
rm -f $DB2PATH/function/$1
cp $1.so $DB2PATH/function/$1

Compile and Link Options for bldsrv

Compile Options:

c++
The C++ compiler.
-KPIC
Generate position-independent code for shared libraries.
-I$DB2PATH/include
Specify the location of the DB2 include files. For example: -I$DB2PATH/include
-D_RWSTD_COMPILE_INSTANTIATE=0
Do not instantiate the rogue wave classes.
-c
Perform compile only, no link. This book assumes that compile and link are separate steps.

Link Options:

c++
Use the compiler as a front end for the linker.
-G
Generate a shared library.
-o $1
Specify the executable.
$1.o
Include the program object file.
-L$DB2PATH/lib
Specify the location of the DB2 static and shared libraries at link-time. For example: $HOME/sqllib/lib. If you do not specify the -L option, /usr/lib:/lib is assumed.
-ldb2
Link with the DB2 library.

Refer to your compiler documentation for additional compiler options.

Compile and Link Options for bldsrv
Compile Options: `c++` The C++ compiler. `-KPIC` Generate position-independent code for shared libraries. `-I$DB2PATH/include` Specify the location of the DB2 include files. For example: `-I$DB2PATH/include` `-D_RWSTD_COMPILE_INSTANTIATE=0` Do not instantiate the rogue wave classes. `-c` Perform compile only, no link. This book assumes that compile and link are separate steps.
Link Options: `c++` Use the compiler as a front end for the linker. `-G` Generate a shared library. `-o $1` Specify the executable. `$1.o` Include the program object file. `-L$DB2PATH/lib` Specify the location of the DB2 static and shared libraries at link-time. For example: `$HOME/sqllib/lib`. If you do not specify the `-L` option, `/usr/lib:/lib` is assumed. `-ldb2` Link with the DB2 library. Refer to your compiler documentation for additional compiler options.

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

    bldsrv spserver

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

    bldsrv spserver database

The script file copies the shared library to the server in the path sqllib/function.

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 shared libary, spserver, you can build the client application spclient that calls the stored procedures within the shared library.

You can build spclient by using the script file, bldapp. Refer to "DB2 API and Embedded SQL Applications" for details.

To call the stored procedures in the shared library, 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 alias, or another database 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 stored procedures return the output to the client application.

User-Defined Functions (UDFs)

Note:

Please see the information for building C++ UDFs in "C++ Considerations for UDFs and Stored Procedures".

The script file, bldudf, in sqllib/samples/cpp, contains the commands to build a UDF. UDFs do not contain embedded SQL statements. Therefore, to build a UDF program, you do not need to connect to a database or precompile and bind the program.

The parameter, $1, specifies the name of your source file. The script file uses the source file name for the shared library name.

#! /bin/ksh # bldudf script file -- PTX # Builds a C++ user-defined function library # Usage: bldudf <prog_name> # Set DB2PATH to where DB2 will be accessed. # The default is the standard instance path. DB2PATH=$HOME/sqllib # Compile the program. c++ -KPIC -I$DB2PATH/include -D_RWSTD_COMPILE_INSTANTIATE=0 -c $1.c # Link the program and create a shared library. c++ -G -o $1 $1.o -L$DB2PATH/lib -ldb2 -ldb2apie # Copy the shared library to the sqllib/function subdirectory. # Note: the user must have write permission to this directory. rm -f $DB2PATH/function/$1 cp $1.so $DB2PATH/function/$1

Compile and Link Options for bldudf

Compile Options:

c++
The C++ compiler.
-KPIC
Generate position-independent code for shared libraries.
-I$DB2PATH/include
Specify the location of the DB2 include files. For example: $HOME/sqllib/include.
-D_RWSTD_COMPILE_INSTANTIATE=0
Do not instantiate the rogue wave classes.
-c
Perform compile only, no link. This book assumes that compile and link are separate steps.

Link Options:

c++
Use the compiler as a front end for the linker.
-G
Generate a shared library.
-o $1
Specify the executable.
$1.o
Include the program object file.
-L$DB2PATH/lib
Specify the location of the DB2 static and shared libraries at link-time. For example: $HOME/sqllib/lib. If you do not specify the -L option, /usr/lib:/lib is assumed.
-ldb2
Link with the DB2 library.
-ldb2apie
Link with the DB2 API Engine library to allow the use of LOB locators.

Refer to your compiler documentation for additional compiler options.

Compile and Link Options for bldudf
Compile Options: `c++` The C++ compiler. `-KPIC` Generate position-independent code for shared libraries. `-I$DB2PATH/include` Specify the location of the DB2 include files. For example: `$HOME/sqllib/include`. `-D_RWSTD_COMPILE_INSTANTIATE=0` Do not instantiate the rogue wave classes. `-c` Perform compile only, no link. This book assumes that compile and link are separate steps.
Link Options: `c++` Use the compiler as a front end for the linker. `-G` Generate a shared library. `-o $1` Specify the executable. `$1.o` Include the program object file. `-L$DB2PATH/lib` Specify the location of the DB2 static and shared libraries at link-time. For example: `$HOME/sqllib/lib`. If you do not specify the `-L` option, `/usr/lib:/lib` is assumed. `-ldb2` Link with the DB2 library. `-ldb2apie` Link with the DB2 API Engine library to allow the use of LOB locators. Refer to your compiler documentation for additional compiler options.

To build the user-defined function program udfsrv from the source file udfsrv.c, enter:

   bldudf udfsrv

The script file copies the UDF to the server in the path sqllib/function.

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

Once you build udfsrv, you can build the client application, udfcli, that calls it. You can build the udfcli program from the udfcli.sqC source file in sqllib/samples/cpp using the script file bldapp. Refer to "DB2 API and 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 in the udfsrv library.

Multi-threaded Applications

Multi-threaded applications using ptx/C++ need to be compiled and linked in with -Kthread.

The script file, bldmt, in sqllib/samples/cpp, contains the commands to build an embedded SQL multi-threaded program.

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. The third parameter, $3, specifies the user ID for the database, and $4 specifies the password. Only the first parameter, the source file name, is required. Database name, user ID, and password are optional. If no database name is supplied, the program uses the default sample database.

#! /bin/ksh
# bldmt script file -- PTX                                
# Builds a C++ multi-threaded embedded SQL program
# Usage: bldmt <prog_name> [ <db_name> [ <userid> <password> ]] 
  
# Set DB2PATH to the location where DB2 will be accessed. 
# The default is the standard instance path.
DB2PATH=$HOME/sqllib
 
# Precompile and bind the program.
embprep $1 $2 $3 $4
 
# Compile the program.
c++ -Kthread -I$DB2PATH/include -D_RWSTD_COMPILE_INSTANTIATE=0 -c $1.C            
 
# Link the program.
c++ -Kthread -o $1 $1.o -L$DB2PATH/lib -ldb2 -lseq

Besides the -Kthread option, discussed above, and the absence of a utility file linked in, the other compile and link options are the same as those used for the embedded SQL script file, bldapp. For information on these options, see "DB2 API and Embedded SQL Applications".

To build the sample program, thdsrver, from the source file thdsrver.sqC, enter:

   bldmt thdsrver

The result is an executable file, thdsrver. To run the executable file against the sample database, enter:

   thdsrver

[ Top of Page | Previous Page | Next Page ]