Application Building Guide

IBM C

This section explains how to use IBM C with the following kinds of DB2 interfaces:

DB2 CLI
DB2 APIs
Embedded SQL

DB2 CLI Applications

The script file bldcli in sqllib/samples/cli contains the commands to build a DB2 CLI program. The parameter, $1, specifies the name of your source file.

This is the only required parameter, and the only one needed for CLI 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.

If the program contains embedded SQL, indicated by the .sqc extension, then the embprep script is called to precompile the program, producing a program file with a .c extension.

#! /bin/ksh
# bldcli script file -- AIX
# Builds a CLI program with IBM C.
# Usage: bldcli <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".sqc" ]]
then
  embprep $1 $2 $3 $4
fi
 
# To compile 64 bit programs, uncomment the following line.
# BUILD_64BIT=true
 
if [ "$BUILD_64BIT" != "" ]
then
  CFLAGS_64=-q64
else
  CFLAGS_64=
fi
 
# Compile the error-checking utility.
xlc $CFLAGS_64 -I$DB2PATH/include -c utilcli.c
  
# Compile the program.
xlc $CFLAGS_64 -I$DB2PATH/include -c $1.c
 
# Link the program.
xlc $CFLAGS_64 -o $1 $1.o utilcli.o -L$DB2PATH/lib -ldb2

Compile and Link Options for bldcli

Compile Options:

xlc
The IBM C compiler.
$CFLAGS_64
Contains "-q64" value if 'BUILD_64BIT=true' is uncommented; otherwise, it contains no value.
-I$DB2PATH/include
Specify the location of the DB2 include files. For example: $HOME/sqllib/include
-c
Perform compile only; no link. This script has separate compile and link steps.

Link Options:

xlc
Use the compiler as a front end for the linker.
$CFLAGS_64
Contains "-q64" value if 'BUILD_64BIT=true' is uncommented; otherwise, it contains no value.
-o $1
Specify the executable program.
$1.o
Specify the object file.
utilcli.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. If you do not specify the -L option, the compiler assumes the following path: /usr/lib:/lib.
-ldb2
Link with the DB2 library.

Refer to your compiler documentation for additional compiler options.

Compile and Link Options for bldcli
Compile Options: `xlc` The IBM C compiler. `$CFLAGS_64` Contains "-q64" value if 'BUILD_64BIT=true' is uncommented; otherwise, it contains no value. `-I$DB2PATH/include` Specify the location of the DB2 include files. For example: `$HOME/sqllib/include` `-c` Perform compile only; no link. This script has separate compile and link steps.
Link Options: `xlc` Use the compiler as a front end for the linker. `$CFLAGS_64` Contains "-q64" value if 'BUILD_64BIT=true' is uncommented; otherwise, it contains no value. `-o $1` Specify the executable program. `$1.o` Specify the object file. `utilcli.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`. If you do not specify the `-L` option, the compiler assumes the following path: `/usr/lib:/lib`. `-ldb2` Link with the DB2 library. Refer to your compiler documentation for additional compiler options.

To build the sample program tbinfo from the source file tbinfo.c, enter:

 
   bldcli tbinfo

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

   tbinfo

Building and Running Embedded SQL Applications

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

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

The result is an executable file, dbusemx.

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 on more than one database. The descriptions of the CLI sample programs in Table 7 indicates the samples that use DB2 APIs.

The script file bldapi in sqllib/samples/cli contains the commands to build a DB2 CLI program 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 bldcli script. Please see "DB2 CLI Applications" for the compile and link options common to both bldapi and bldcli.

To build the sample program dbmconn from the source file dbmconn.c, enter:

 
   bldapi dbmconn

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

   dbmconn

DB2 CLI Stored Procedures

The script file bldclisp in sqllib/samples/cli contains the commands to build a DB2 CLI stored procedure. The parameter, $1, specifies the name of your source file; $2, specifies the stored procedure function that is the entry point to the shared library.

#! /bin/ksh
# bldclisp script file -- AIX
# Builds a CLI stored procedure in IBM C.
# Usage: bldclisp <prog_name> [ <entry_point> ] 
 
# Set DB2PATH to where DB2 will be accessed. 
# The default is the standard instance path. 
DB2PATH=$HOME/sqllib
 
# To compile 64 bit programs, uncomment the following line.
# BUILD_64BIT=true
 
if [ "$BUILD_64BIT" != "" ]
then
  CFLAGS_64=-q64
else
  CFLAGS_64=
fi
 
# Compile the error-checking utility.
xlc $CFLAGS_64 -I$DB2PATH/include -c utilcli.c
 
# Compile the program.
xlc $CFLAGS_64 -I$DB2PATH/include -c $1.c
 
# Link the program.
xlc $CFLAGS_64 -o $1 $1.o utilcli.o -L$DB2PATH/lib \
  -ldb2 -lm -H512 -T512 -bE:$1.exp -e $2
 
# 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 $DB2PATH/function

Compile and Link Options for bldclisp

Compile Options:

xlc
The IBM C compiler.
$CFLAGS_64
Contains "-q64" value if 'BUILD_64BIT=true' is uncommented; otherwise, it contains no value.
-I$DB2PATH/include
Specify the location of the DB2 include files. For example: $HOME/sqllib/include.
-c
Perform compile only; no link. This book assumes that compile and link are separate steps.

Link Options:

xlc
Use the compiler as a front end for the linker.
$CFLAGS_64
Contains "-q64" value if 'BUILD_64BIT=true' is uncommented; otherwise, it contains no value.
-o $1
Specify the executable program.
$1.o
Specify the object file.
utilcli.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. If you do not specify the -L option, the compiler assumes the following path: /usr/lib:/lib.
-ldb2
Link with the DB2 library.
-lm
Link with the math library.
-H512
Specify output file alignment.
-T512
Specify output file text segment starting address.
-bE:$.exp
Specify an export file. The export file contains a list of the stored procedures.
-e $2
Specify the default entry point to the shared library.

Refer to your compiler documentation for additional compiler options.

Compile and Link Options for bldclisp
Compile Options: `xlc` The IBM C compiler. `$CFLAGS_64` Contains "-q64" value if 'BUILD_64BIT=true' is uncommented; otherwise, it contains no value. `-I$DB2PATH/include` Specify the location of the DB2 include files. For example: `$HOME/sqllib/include`. `-c` Perform compile only; no link. This book assumes that compile and link are separate steps.
Link Options: `xlc` Use the compiler as a front end for the linker. `$CFLAGS_64` Contains "-q64" value if 'BUILD_64BIT=true' is uncommented; otherwise, it contains no value. `-o $1` Specify the executable program. `$1.o` Specify the object file. `utilcli.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`. If you do not specify the `-L` option, the compiler assumes the following path: `/usr/lib:/lib`. `-ldb2` Link with the DB2 library. `-lm` Link with the math library. `-H512` Specify output file alignment. `-T512` Specify output file text segment starting address. `-bE:$.exp` Specify an export file. The export file contains a list of the stored procedures. `-e $2` Specify the default entry point to the shared library. Refer to your compiler documentation for additional compiler options.

To build the sample program spserver from the source file spserver.c, enter the build file name, program name, and the name of the stored procedure function that is the entry point to the shared library:

    bldclisp spserver outlanguage

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

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

You can build spclient by using the script file, bldcli. Refer to "DB2 CLI Applications" for details.

To access 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 output is returned to the client application.

DB2 API and Embedded SQL Applications

The build file, bldapp, in sqllib/samples/c, 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, 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 -- AIX
# Builds a C 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
 
# To compile 64 bit programs, uncomment the following line.
# BUILD_64BIT=true
 
if [ "$BUILD_64BIT" != "" ]
then
  CFLAGS_64=-q64
else 
  CFLAGS_64=
fi
 
# If embedded SQL program, precompile and bind it.
if [[ -f $1".sqc" ]] 
then
  embprep $1 $2 $3 $4
  # Compile the utilemb.c error-checking utility.
  xlc $CFLAGS_64 -I$DB2PATH/include -c utilemb.c
else
  # Compile the utilapi.c error-checking utility.
  xlc $CFLAGS_64 -I$DB2PATH/include -c utilapi.c
fi
 
# Compile the program.
xlc $CFLAGS_64 -I$DB2PATH/include -c $1.c
 
if [[ -f $1".sqc" ]]
then                     
  # Link the program with utilemb.o
  xlc $CFLAGS_64 -o $1 $1.o utilemb.o -ldb2 -L$DB2PATH/lib
else
  # Link the program with utilapi.o
  xlc $CFLAGS_64 -o $1 $1.o utilapi.o -ldb2 -L$DB2PATH/lib
fi

Compile and Link Options for bldapp

Compile Options:

xlc
The IBM C compiler.
$CFLAGS_64
Contains "-q64" value if 'BUILD_64BIT=true' is uncommented; otherwise, it contains no value.
-I$DB2PATH/include
Specify the location of the DB2 include files. For example: $HOME/sqllib/include.
-c
Perform compile only; no link. Compile and link are separate steps.

Link Options:

xlc
Use the compiler as a front end for the linker.
$CFLAGS_64
Contains "-q64" value if 'BUILD_64BIT=true' is uncommented; otherwise, it contains no value.
-o $
Specify the executable program.
$1.o
Specify the program object file.
utilemb.o
If an embedded SQL program, include the embedded SQL utility object file for error checking.
utilapi.o
If not an embedded SQL program, include the DB2 API utility object file for error checking.
-ldb2
Link to the database manager library.
-L$DB2PATH/lib
Specify the location of the DB2 runtime shared libraries. For example: $HOME/sqllib/lib. If you do not specify the -L option, the compiler assumes the following path: /usr/lib:/lib.

Refer to your compiler documentation for additional compiler options.

Compile and Link Options for bldapp
Compile Options: `xlc` The IBM C compiler. `$CFLAGS_64` Contains "-q64" value if 'BUILD_64BIT=true' is uncommented; otherwise, it contains no value. `-I$DB2PATH/include` Specify the location of the DB2 include files. For example: `$HOME/sqllib/include`. `-c` Perform compile only; no link. Compile and link are separate steps.
Link Options: `xlc` Use the compiler as a front end for the linker. `$CFLAGS_64` Contains "-q64" value if 'BUILD_64BIT=true' is uncommented; otherwise, it contains no value. `-o $` Specify the executable program. `$1.o` Specify the program object file. `utilemb.o` If an embedded SQL program, include the embedded SQL utility object file for error checking. `utilapi.o` If not an embedded SQL program, include the DB2 API utility object file for error checking. `-ldb2` Link to the database manager library. `-L$DB2PATH/lib` Specify the location of the DB2 runtime shared libraries. For example: `$HOME/sqllib/lib`. If you do not specify the `-L` option, the compiler assumes the following path: `/usr/lib:/lib`. 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, 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/c, contains the commands to build a 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. The second parameter, $2, specifies the stored procedure function that is the entry point to the shared library. The third parameter, $3, 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 two parameters, source file name and entry point, are required. Database name is optional. If no database name is supplied, the program uses the default sample database.

#! /bin/ksh
# bldsrv script file -- AIX
# Builds a C stored procedure
# Usage: bldsrv <prog_name> <entry_point> [ <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 $3
 
# To compile 64 bit programs, uncomment the following line.
# BUILD_64BIT=true
 
if [ "$BUILD_64BIT" != "" ]
then
  CFLAGS_64=-q64
else 
  CFLAGS_64=
fi
 
# Compile the program.
xlc $CFLAGS_64 -I$DB2PATH/include -c $1.c
 
# Link the program using the export file $1.exp,
# creating shared library $1 with entry point $2.
xlc $CFLAGS_64 -o $1 $1.o -ldb2 -L$DB2PATH/lib -H512 -T512 -bE:$1.exp -e $2
 
# 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 $DB2PATH/function

Compile and Link Options for bldsrv

Compile Options:

xlc
The IBM C compiler.
$CFLAGS_64
Contains "-q64" value if 'BUILD_64BIT=true' is uncommented; otherwise, it contains no value.
-I$DB2PATH/include
Specify the location of the DB2 include files. For example: $HOME/sqllib/include.
-c
Perform compile only; no link. Compile and link are separate steps.

Link options:

xlc
Use the compiler as a front end for the linker.
$CFLAGS_64
Contains "-q64" value if 'BUILD_64BIT=true' is uncommented; otherwise, it contains no value.
-o $1
Specify the output as a shared library file.
$1.o
Specify the stored procedure object file.
-ldb2
Link with the DB2 library.
-L$DB2PATH/lib
Specify the location of the DB2 runtime shared libraries. For example: $HOME/sqllib/lib. If you do not specify the -L option, the compiler assumes the following path: /usr/lib:/lib.
-H512
Specify output file alignment.
-T512
Specify output file text segment starting address.
-bE:$1.exp
Specify an export file. The export file contains a list of the stored procedures.
-e $1
Specify the default entry point to the shared library.

Refer to your compiler documentation for additional compiler options.

Compile and Link Options for bldsrv
Compile Options: `xlc` The IBM C compiler. `$CFLAGS_64` Contains "-q64" value if 'BUILD_64BIT=true' is uncommented; otherwise, it contains no value. `-I$DB2PATH/include` Specify the location of the DB2 include files. For example: `$HOME/sqllib/include`. `-c` Perform compile only; no link. Compile and link are separate steps.
Link options: `xlc` Use the compiler as a front end for the linker. `$CFLAGS_64` Contains "-q64" value if 'BUILD_64BIT=true' is uncommented; otherwise, it contains no value. `-o $1` Specify the output as a shared library file. `$1.o` Specify the stored procedure object file. `-ldb2` Link with the DB2 library. `-L$DB2PATH/lib` Specify the location of the DB2 runtime shared libraries. For example: `$HOME/sqllib/lib`. If you do not specify the `-L` option, the compiler assumes the following path: `/usr/lib:/lib`. `-H512` Specify output file alignment. `-T512` Specify output file text segment starting address. `-bE:$1.exp` Specify an export file. The export file contains a list of the stored procedures. `-e $1` Specify the default entry point to the shared library. Refer to your compiler documentation for additional compiler options.

To build the sample program spserver from source file spserver.sqc, if connecting to the sample database, enter the build file name, program name, and the name of the stored procedure function that is the entry point to the shared library:

    bldsrv spserver outlanguage

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

    bldsrv spserver outlanguage database

The script file copies the stored procedure 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 library, spserver, you can build the client application, spclient, that accesses 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 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 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 output is returned to the client application.

User-Defined Functions (UDFs)

The script file bldudf, in sqllib/samples/c, contains the commands to build a UDF. UDFs are compiled like stored procedures. They cannot contain SQL statements. This means to build a UDF program, you do not connect to a database, precompile, and bind the program.

#! /bin/ksh
# bldudf script file -- AIX
# Builds a C UDF library
# Usage: bldudf <prog_name> <entry_point>
 
# Set DB2PATH to where DB2 will be accessed. 
# The default is the standard instance path. 
DB2PATH=$HOME/sqllib
 
# To compile 64 bit programs, uncomment the following line.
# BUILD_64BIT=true
 
if [ "$BUILD_64BIT" != "" ]
then
  CFLAGS_64=-q64
else 
  CFLAGS_64=
fi
 
# Compile the program.
xlc $CFLAGS_64 -I$DB2PATH/include -c $1.c
 
# Link the program.
xlc $CFLAGS_64 -o $1 $1.o -ldb2 -ldb2apie -L$DB2PATH/lib -H512 -T512 -bE:$1.exp -e $2
 
# 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 $DB2PATH/function

Compile and Link Options for bldudf

Compile Options:

xlc
The IBM C compiler.
$CFLAGS_64
Contains "-q64" value if 'BUILD_64BIT=true' is uncommented; otherwise, it contains no value.
-I$DB2PATH/include
Specify the location of the DB2 include files. For example: $HOME/sqllib/include.
-c
Perform compile only; no link. This book assumes that compile and link are separate steps.

Link Options:

xlc
Use the compiler as a front end for the linker.
$CFLAGS_64
Contains "-q64" value if 'BUILD_64BIT=true' is uncommented; otherwise, it contains no value.
-o $1
Specify the output as a shared library file.
$1.o
Specify the shared library object file.
-ldb2
Link with the database manager library.
-ldb2apie
Link with the DB2 API Engine library to allow the use of LOB locators.
-L$DB2PATH/lib
Specify the location of the DB2 runtime shared libraries. For example: $HOME/sqllib/lib. If you do not specify the -L option, the compiler assumes the following path: /usr/lib:/lib.
-H512
Specify output file alignment.
-T512
Specify output file text segment starting address.
-bE:$1.exp
Specify an export file. The export file contains a list of the UDFs.
-e $2
Specify the default entry point to the shared library.

Refer to your compiler documentation for additional compiler options. Refer to "UDFs and the CREATE FUNCTION Statement" for more information on creating UDFs.

Compile and Link Options for bldudf
Compile Options: `xlc` The IBM C compiler. `$CFLAGS_64` Contains "-q64" value if 'BUILD_64BIT=true' is uncommented; otherwise, it contains no value. `-I$DB2PATH/include` Specify the location of the DB2 include files. For example: `$HOME/sqllib/include`. `-c` Perform compile only; no link. This book assumes that compile and link are separate steps.
Link Options: `xlc` Use the compiler as a front end for the linker. `$CFLAGS_64` Contains "-q64" value if 'BUILD_64BIT=true' is uncommented; otherwise, it contains no value. `-o $1` Specify the output as a shared library file. `$1.o` Specify the shared library object file. `-ldb2` Link with the database manager library. `-ldb2apie` Link with the DB2 API Engine library to allow the use of LOB locators. `-L$DB2PATH/lib` Specify the location of the DB2 runtime shared libraries. For example: `$HOME/sqllib/lib`. If you do not specify the `-L` option, the compiler assumes the following path: `/usr/lib:/lib`. `-H512` Specify output file alignment. `-T512` Specify output file text segment starting address. `-bE:$1.exp` Specify an export file. The export file contains a list of the UDFs. `-e $2` Specify the default entry point to the shared library. Refer to your compiler documentation for additional compiler options. Refer to "UDFs and the CREATE FUNCTION Statement" for more information on creating UDFs.

To build the user-defined function program, udfsrv, from the source file udfsrv.c, enter the build file name, program name, and UDF function that is the entry point to the shared library:

   
   bldudf udfsrv ScalarUDF

The script file copies the UDF to the sqllib/function directory.

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. 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, using the script file bldcli. 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, 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 from the udfsrv library.

Multi-threaded Applications

C multi-threaded applications on AIX Version 4 need to be compiled and linked with the xlc_r compiler instead of the xlc compiler or, for C++, with the xlC_r compiler instead of the xlC compiler. If you are using AIX 4.3 or later for 32-bit applications, use the xlc_r7 or xlC_r7 compiler. The _r versions (as well as the other multi-threaded compiler front ends) set the appropriate preprocessor defines for multi-threaded compilation, and supply the appropriate threaded library names to the linker.

Additional information about compiler and link flag settings using the multi-threaded compiler front ends can be obtained from /etc/xlC.cfg when using the 3.1 compiler, or /etc/ibmcxx.cfg when using the 3.6 or newer compilers.

The script file bldmt, in sqllib/samples/c, 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. 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 -- AIX
# Builds a C multi-threaded embedded SQL program.
# Usage: bldmt <prog_name> [ <db_name> [ <userid> <password> ]] 
 
# 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 $3 $4
 
# To compile 64 bit programs, uncomment the following line.
# BUILD_64BIT=true
 
if [ "$BUILD_64BIT" != "" ]
then
  CFLAGS_64=-q64
else 
  CFLAGS_64=
fi
 
# Compile the program.
xlc_r $CFLAGS_64 -I$DB2PATH/include -c $1.c
 
# Link the program.
xlc_r $CFLAGS_64 -o $1 $1.o -L$DB2PATH/lib -ldb2

Besides the xlc_r compiler, discussed above, and the absence of a utility file linked in, the 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 multi-threaded 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 the executable name:

   thdsrver

[ Top of Page | Previous Page | Next Page ]