Application Building Guide

HP-UX C

This section explains how to use HP-UX C with the following interfaces:

DB2 APIs
DB2 CLI
Embedded SQL

DB2 API Applications

The script file, bldccapi, in sqllib/samples/c, contains the commands to build a sample C program. The parameter, $1, specifies the name of your source file.

#! /bin/ksh # bldccapi script file # Builds a sample C program not containing embedded SQL # Usage: bldccapi <prog_name> # Set DB2PATH to where DB2 will be accessed. # The default is the standard instance path. DB2PATH=$HOME/sqllib # Compile the util.c error-checking utility. cc -Aa +e -I$DB2PATH/include -c util.c # Compile the program. cc -Aa +e -I$DB2PATH/include -c $1.c # Link the program. cc -o $1 $1.o util.o -L$DB2PATH/lib -ldb2

Compile and Link Options for bldccapi

The script file contains the following compile options:

cc
The C compiler.
-Aa
Use ANSI standard mode (for the C compiler only).
+e
Enables HP value-added features while compiling in ANSI C mode.
-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.

The script file contains the following link options:

cc
Use the compiler as a front end for the linker.
-o $1
Specify the executable.
$1.o
Specify the program object file.
util.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, /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 bldccapi
The script file contains the following compile options: `cc` The C compiler. `-Aa` Use ANSI standard mode (for the C compiler only). `+e` Enables HP value-added features while compiling in ANSI C mode. `-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.
The script file contains the following link options: `cc` Use the compiler as a front end for the linker. `-o $1` Specify the executable. `$1.o` Specify the program object file. `util.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, `/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 client from the source file client.c, enter:

   bldccapi client

The result is an executable file client. You can run the executable file against the sample database by entering:

   client

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.

#! /bin/ksh # bldcli script file -- HP-UX # Builds a CLI program with HP-UX C. # Usage: bldcli <prog_name> # Set DB2PATH to where DB2 will be accessed. # The default is the standard instance path. DB2PATH=$HOME/sqllib # Compile the error-checking utility. cc -Aa +e -I$DB2PATH/include -c samputil.c # Compile the program. cc -Aa +e -I$DB2PATH/include -c $1.c # Link the program. cc -o $1 $1.o samputil.o -L$DB2PATH/lib -ldb2

Compile and Link Options for bldcli

The script file contains the following compile options:

cc
Use the C compiler.
-Aa
Use ANSI standard mode.
+e
Enables HP value-added features while compiling in ANSI C mode.
-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.

The script file contains the following link options:

cc
Use the compiler as a front end for the linker.
-o $1
Specify the executable program.
-o $1.o
Specify the object file.
samputil.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 with the database manager library.

Refer to your compiler documentation for additional compiler options.

Compile and Link Options for bldcli
The script file contains the following compile options: `cc` Use the C compiler. `-Aa` Use ANSI standard mode. `+e` Enables HP value-added features while compiling in ANSI C mode. `-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.
The script file contains the following link options: `cc` Use the compiler as a front end for the linker. `-o $1` Specify the executable program. `-o $1.o` Specify the object file. `samputil.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 with the database manager library. Refer to your compiler documentation for additional compiler options.

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

 
   bldcli basiccon

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

   basiccon

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.

#! /bin/ksh # bldclisp script file -- HP-UX # Builds a CLI stored procedure in HP-UX C. # Usage: bldclisp <prog_name> # Set DB2PATH to where DB2 will be accessed. # The default is the standard instance path. DB2PATH=$HOME/sqllib # Compile the error-checking utility. cc +u1 +z -Aa +e -I$DB2PATH/include -c samputil.c # Compile the program. cc +u1 +z -Aa +e -I$DB2PATH/include -c $1.c # Link the program. ld -b -o $1 $1.o -L$DB2PATH/lib -ldb2 # Copy the shared library to the sqllib/function subdirectory of the DB2 instance. # This assumes the user has write permission to this directory. rm -f $DB2PATH/function/$1 cp $1 $DB2PATH/function

Compile and Link Options for bldclisp

The script file contains the following compile options:

cc
The C compiler.
+u1
Allow unaligned data access. Use only if your application uses unaligned data.
+z
Generate position-independent code.
-Aa
Use ANSI standard mode (for the C compiler only).
+e
Enables HP value-added features while compiling in ANSI C mode.
-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.

The script file contains the following link options:

ld
Use the linker to link edit.
-b
Create a shared library rather than a normal executable.
-o $1
Specify the executable.
$1.o
Specify the object file.
-L$DB2PATH/lib
Specify the location of the DB2 runtime shared libraries. For example: -L$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 bldclisp
The script file contains the following compile options: `cc` The C compiler. `+u1` Allow unaligned data access. Use only if your application uses unaligned data. `+z` Generate position-independent code. `-Aa` Use ANSI standard mode (for the C compiler only). `+e` Enables HP value-added features while compiling in ANSI C mode. `-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.
The script file contains the following link options: `ld` Use the linker to link edit. `-b` Create a shared library rather than a normal executable. `-o $1` Specify the executable. `$1.o` Specify the object file. `-L$DB2PATH/lib` Specify the location of the DB2 runtime shared libraries. For example: `-L$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 outsrv2 from source file outsrv2.c, enter:

   bldclisp outsrv2

The script file copies the stored procedure to the server in the path sqllib/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 sqllib/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 script file bldcli. 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 script file, bldcc, in sqllib/samples/c, contains the commands to build an embeddded SQL 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
# bldcc script file
# Builds a sample C program containing embedded SQL
# Usage: bldcc <prog_name> [ <db_name> [ <userid> <password> ]]
 
# Set DB2PATH to where DB2 will be accessed. 
# The default is the standard instance path. 
DB2PATH=$HOME/sqllib
 
# Connect to a database.
if (($# < 2))
then
   db2 connect to sample
elif (($# < 3))
then
   db2 connect to $2
else
   db2 connect to $2 user $3 using $4
fi
 
# Precompile the program.
db2 prep $1.sqc bindfile
 
# Bind the program to the database.
db2 bind $1.bnd
 
# Disconnect from the database.
db2 connect reset
 
# Compile the util.c error-checking utility.
cc -Aa +e -I$DB2PATH/include -c util.c
 
# Compile the program.
cc -Aa +e -I$DB2PATH/include -c $1.c
 
# Link the program.
cc -o $1 $1.o util.o -L$DB2PATH/lib -ldb2

Compile and Link Options for bldcc

The script file contains the following compile options:

cc
The C compiler.
-Aa
Use ANSI standard mode (for the C compiler only).
+e
Enables HP value-added features while compiling in ANSI C mode.
-I$DB2PATH/include
Specify the location of the DB2 include files. For example: -I$DB2PATH/include
-c
Perform compile only; no link. This book assumes that compile and link are separate steps.

The script file contains the following link options:

cc
Use the compiler to link edit.
-o $1
Specify the executable.
$1.o
Specify the program object file.
util.o
Include the utility object file for error checking.
-L$DB2PATH/lib
Specify the location of the DB2 runtime shared libraries. For example: -L$DB2PATH/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 bldcc
The script file contains the following compile options: `cc` The C compiler. `-Aa` Use ANSI standard mode (for the C compiler only). `+e` Enables HP value-added features while compiling in ANSI C mode. `-I$DB2PATH/include` Specify the location of the DB2 include files. For example: `-I$DB2PATH/include` `-c` Perform compile only; no link. This book assumes that compile and link are separate steps.
The script file contains the following link options: `cc` Use the compiler to link edit. `-o $1` Specify the executable. `$1.o` Specify the program object file. `util.o` Include the utility object file for error checking. `-L$DB2PATH/lib` Specify the location of the DB2 runtime shared libraries. For example: `-L$DB2PATH/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 updat from the source file updat.sqc, enter:

   bldcc updat

The result is an executable file updat. You can run the executable file against the sample database by entering:

   updat

Embedded SQL Stored Procedures

The script file bldccsrv, in sqllib/samples/c, 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. 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.

The script file uses the source file name, $1, for the shared library name.

#! /bin/ksh
# bldccsrv script file
# Build C stored procedure.
# Usage: bldccsrv <prog_name> [ <db_name> [ <userid> <password> ]]
 
# Set DB2PATH to where DB2 will be accessed. 
# The default is the standard instance path. 
DB2PATH=$HOME/sqllib
 
# Connect to a database.
if (($# < 2))
then
   db2 connect to sample
elif (($# < 3))
then
   db2 connect to $2
else
   db2 connect to $2 user $3 using $4
fi
 
# Precompile the program.
db2 prep $1.sqc bindfile
 
# Bind the program to the database.
db2 bind $1.bnd
 
# Disconnect from the database.
db2 connect reset
 
# Compile the program.
cc +u1 +z -Aa +e -I$DB2PATH/include -c $1.c
 
# Link the program to create a shared library
ld -b -o $1 $1.o -L$DB2PATH/lib -ldb2
 
# Copy the shared library to the sqllib/function subdirectory of the DB2
# instance. This assumes the user has write permission to this directory.
rm -f $DB2PATH/function/$1
cp $1 $DB2PATH/function

Compile and Link Options for bldccsrv

The script file contains the following compile options:

cc
The C compiler.
+u1
Allow unaligned data access. Use only if your application uses unaligned data.
-Aa
Use ANSI standard mode (for the C compiler only).
+z
Generate position-independent code.
+e
Enables HP value-added features while compiling in ANSI C mode.
-I$DB2PATH/include
Specify the location of the DB2 include files. For example: -I$DB2PATH/include.
-c
Perform compile only; no link. This book assumes that compile and link are separate steps.

The script file contains the following link options:

ld
Use the linker to link edit.
-b
Create a shared library rather than a normal executable.
-o $1
Specify the output as a shared library file.
$1.o
Specify the program object file.
-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, /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 bldccsrv
The script file contains the following compile options: `cc` The C compiler. `+u1` Allow unaligned data access. Use only if your application uses unaligned data. `-Aa` Use ANSI standard mode (for the C compiler only). `+z` Generate position-independent code. `+e` Enables HP value-added features while compiling in ANSI C mode. `-I$DB2PATH/include` Specify the location of the DB2 include files. For example: `-I$DB2PATH/include`. `-c` Perform compile only; no link. This book assumes that compile and link are separate steps.
The script file contains the following link options: `ld` Use the linker to link edit. `-b` Create a shared library rather than a normal executable. `-o $1` Specify the output as a shared library file. `$1.o` Specify the program object file. `-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, `/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 outsrv from the source file outsrv.sqc, enter:

   bldccsrv outsrv

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 script file bldcc. Refer to "HP-UX C" 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 script file bldccudf, in sqllib/samples/c, contains the commands to build a UDF. UDFs are compiled like stored procedures. They cannot contain embedded SQL statements. This means to build a UDF program, you never need to connect to a database, precompile, and bind the program.

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

#! /bin/ksh # bldccudf script file # Builds sample C UDF library. # Usage: bldccudf <prog_name> # Set DB2PATH to where DB2 will be accessed. # The default is the standard instance path. DB2PATH=$HOME/sqllib # Compile the program. cc +u1 +z -Aa +e -I$DB2PATH/include -c $1.c # Link the program and create a shared library. ld -b -o $1 $1.o -L$DB2PATH/lib -ldb2 -ldb2apie # Copy the shared library to the DB2 instance sqllib/function subdirectory. # This assumes the user has write permission to this directory. rm -f $DB2PATH/function/$1 cp $1 $DB2PATH/function

Compile and Link Options for bldccudf

The script file contains the following compile options:

cc
The C compiler.
+u1
Allow unaligned data access. Use only if your application uses unaligned data.
-Aa
Use ANSI standard mode (for the C compiler only).
+z
Generate position-independent code.
+e
Enables HP value-added features while compiling in ANSI C mode.
-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.

The script file contains the following link options:

ld
Use the linker to link edit.
-b
Create a shared library rather than a normal executable.
-o $1
Specify the output as a shared library file.
$1.o
Specify the program object file.
-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, /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 bldccudf
The script file contains the following compile options: `cc` The C compiler. `+u1` Allow unaligned data access. Use only if your application uses unaligned data. `-Aa` Use ANSI standard mode (for the C compiler only). `+z` Generate position-independent code. `+e` Enables HP value-added features while compiling in ANSI C mode. `-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.
The script file contains the following link options: `ld` Use the linker to link edit. `-b` Create a shared library rather than a normal executable. `-o $1` Specify the output as a shared library file. `$1.o` Specify the program object file. `-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, `/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 udf from the source file udf.c, enter:

   bldccudf udf

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 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 calludf.c source file in sqllib/samples/cli using the DB2 CLI script file bldcli. Refer to "DB2 CLI Applications" for details.

You can build the embedded SQL calludf program from the calludf.sqc source file in sqllib/samples/c using the script file bldcc. Refer to "Embedded SQL Applications" for details.

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

   calludf

The calling application calls functions from the udf library.

Multi-threaded Applications

Note:

Multi-threaded applications are not supported by DB2 on version 10 of the HP-UX operating system. HP-UX version 11 provides a POSIX thread library and a DCE thread library. Multi-threaded applications using the POSIX thread library are supported by DB2 on HP-UX version 11.

Multi-threaded applications on HP-UX version 11 need to have _REENTRANT defined for their compilation. The HP-UX documentation recommends compiling with -D_POSIX_C_SOURCE=199506L. This will also ensure _REENTRANT is defined. Applications also need to be linked with -lpthread.

The script file, bldccmt, in sqllib/samples/c, contains the commands to build an embedded SQL multi-threaded program. If you want to build a DB2 API or DB2 CLI multi-threaded program, comment out the connect, precompile, bind, and disconnect commands. For DB2 CLI, also substitute the samputil.c and samputil.o files for util.c and util.o.

#! /bin/ksh 
# bldccmt script file -- HP-UX                               
# Builds a multi-threaded embedded SQL program with HP-UX C.
# Usage: bldccmt <prog_name> [ <db_name> [ <userid> <password> ]] 
 
# Set DB2PATH to where DB2 will be accessed. 
# The default is the standard instance path.
DB2PATH=$HOME/sqllib
 
# Connect to a database.
if (($# < 2))
then
  db2 connect to sample
elif (($# < 3))
then
   db2 connect to $2
else
   db2 connect to $2 user $3 using $4
fi
 
# Precompile the program.
db2 prep $1.sqc bindfile
# Bind the program to the database.
db2 bind $1.bnd                    
# Disconnect from the database.    
db2 connect reset
 
# Compile the util.c error-checking utility.
cc -Aa +e -I$DB2PATH/include -D_POSIX_C_SOURCE=199506L -c util.c
 
# Compile the program.                                 
cc -Aa +e -I$DB2PATH/include -D_POSIX_C_SOURCE=199506L -c $1.c      
 
# Link the program                                      
cc -o $1 $1.o util.o -L$DB2PATH/lib -ldb2 -lpthread

Besides the -D_POSIX_C_SOURCE=199506L compile option, and the -lpthread link option, discussed above, the other compile and link options are the same as those used for the embedded SQL script file, bldcc. For information on these options, see "Embedded SQL Applications".

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

   bldccmt 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 | Table of Contents | Index ]

[ DB2 List of Books | Search the DB2 Books ]