This section explains how to use IBM C with the following kinds of DB2 interfaces:
The script file bldxlcapi in sqllib/samples/c contains the commands to build a DB2 API program. The one parameter it takes, $1, specifies the name of your source file.
#! /bin/ksh # bldxlcapi script file # Build sample programs that do not contain embedded SQL # Usage: blxlcapi <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. xlc -I$DB2PATH/include -c util.c # Compile the program. xlc -I$DB2PATH/include -c $1.c # Link the program. xlc -o $1 $1.o util.o -ldb2 -L$DB2PATH/lib |
| Compile and Link Options for bldxlc |
|---|
|
The script file contains the following compile options:
|
|
The script file contains the following link options:
Refer to your compiler documentation for additional compiler
options.
|
To build the sample program client from the source file client.c , enter:
bldxlcapi client
The result is an executable file client. You can run the executable file against the sample database by entering the executable name:
client
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 -- AIX # Builds a CLI program with IBM 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. xlc -I$DB2PATH/include -c samputil.c # Compile the program. xlc -I$DB2PATH/include -c $1.c # Link the program. xlc -o $1 $1.o samputil.o -L$DB2PATH/lib -ldb2 |
| Compile and Link Options for bldcli |
|---|
|
The script file contains the following compile options:
|
|
The script file contains the following link options:
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
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.
The script file uses the source file name, $1, for the shared library name, and for the entry point to the shared library. If you are building stored procedures that have the entry point function name different from the source file name, you can modify the script file to accept a second parameter for the entry point by changing the link option to -e $2.
#! /bin/ksh # bldclisp script file -- AIX # Builds a CLI stored procedure in IBM 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. xlc -I$DB2PATH/include -c samputil.c # Compile the program. xlc -I$DB2PATH/include -c $1.c # Link the program. xlc -o $1 $1.o samputil.o -L$DB2PATH/lib -ldb2 -lm -H512 -T512 -bE:$1.exp -e $1 # Copy the shared library to the sqllib/function subdirectory of the DB2 instance. # Note: 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:
|
|
The script file contains the following link options:
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
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.
The script file bldxlc, in sqllib/samples/c, contains the commands to build an embedded 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. 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 # bldxlc script file # Builds a sample C program containing embedded SQL # Usage: bldxlc <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. xlc -I$DB2PATH/include -c util.c # Compile the program. xlc -I$DB2PATH/include -c $1.c # Link the program. xlc -o $1 $1.o util.o -ldb2 -L$DB2PATH/lib
| Compile and Link Options for bldxlc |
|---|
|
The script file contains the following compile options:
|
|
The script file contains the following link options:
Refer to your compiler documentation for additional compiler
options.
|
To build the sample program updat from the source file updat.sqc , enter:
bldxlc updat
The result is an executable file updat. You can run the executable file against the sample database by entering the executable name:
updat
The script file bldxlcsrv, 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 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.
The script file uses the source file name, $1, for the shared library name, and for the entry point to the shared library. If you are building stored procedures with the entry point function name different from the source file name, you can modify the script file to accept another parameter for the entry point. We recommend renaming the database parameter to $3, the user ID paramaeter to $4, and the password parameter to $5. Then you can change the entry point link option to -e $2, and specify the additional parameter on the command line when you run the script file.
#! /bin/ksh
# bldxlcsrv script file
# Builds a stored procedure
# Usage: bldxlcsrv <stor_proc_name> [ <db_name> [ <userid> <password> ]]
# Set DB2PATH to where DB2 will be accessed.
# The default is the 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.
xlc -I$DB2PATH/include -c util.c
# Compile the program.
xlc -I$DB2PATH/include -c $1.c
# Link the program using the export file $1.exp,
# creating shared library $1 with entry point $1.
xlc -o $1 $1.o util.o -ldb2 -L$DB2PATH/lib \
-H512 -T512 -bE:$1.exp -e $1
# Copy the shared library to the sqllib/function subdirectory of the DB2 instance.
# Note: this assumes the user has write permission to this directory.
rm -f $DB2PATH/function/$1
cp $1 $DB2PATH/function
| Compile and Link Options for bldxlcsrv |
|---|
|
The script file contains the following compile options:
|
|
The script file contains the following link options:
Refer to your compiler documentation for additional compiler
options.
|
To build the sample program outsrv from the source file outsrv.sqc , enter:
bldxlcsrv outsrv
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 outsrv, you can build the client application outcli that calls the stored procedure. You can build outcli using the script file bldxlc. Refer to "IBM C" for details.
To call the stored procedure, run the sample client application by entering:
outcli remote_database userid password
where
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.
The script file bldxlcudf, 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 never need to connect to a database, precompile, and bind the program.
The first parameter, $1, specifies the name of your source file. The second parameter, $2, specifies the default entry point to the shared library. The script file uses the source file name, $1, for the shared library name.
#! /bin/ksh # bldxlcudf script file # Builds a sample C UDF library. # Usage: bldxlcudf <prog_name> <entry_point> # Set DB2PATH to where DB2 will be accessed. # The default is the standard instance path. DB2PATH=$HOME/sqllib # Compile the program. xlc -I$DB2PATH/include -c $1.c # Link the program. xlc -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 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 bldxlcudf |
|---|
|
The script file contains the following compile options:
|
|
The script file contains the following link options:
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 udf from the source file udf.c , enter:
bldxlcudf udf increase
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 source file calludf.c , in sqllib/samples/cli, using the script file bldcli. Refer to "DB2 CLI Applications" for details.
You can build the embedded SQL calludf program from the source file calludf.sqc , in sqllib/samples/c, using the script file bldxlc. Refer to "IBM C" 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.
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, use the xlc_r7 or xlC_r7 compiler. The _r versions pass -D_REENTRANT to the C preprocessor and -lpthreads to the linker, so it is not necessary to do this explicitly. Please see the /etc/xlC.cfg file for more information.
The script file bldxlcmt, 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.
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 # bldxlcmt script file -- AIX # Builds an embedded SQL multi-threaded program with IBM C. # Usage: bldxlcmt <prog_name> [ <db_name> [ <userid> <password> ]] # Set DB2PATH to where DB2 will be accessed. # The default is the 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. xlc_r -I$DB2PATH/include -c util.c # Compile the program. xlc_r -I$DB2PATH/include -c $1.c # Link the program xlc_r -o $1 $1.o util.o -L$DB2PATH/lib -ldb2
Besides the xlc_r compiler, discussed above, the other compile and link options are the same as those used for the embedded SQL script file, bldxlc. For information on these options, see "Embedded SQL Applications".
To build the multi-threaded sample program, thdsrver, from the source file thdsrver.sqc , enter:
bldxlcmt thdsrver
The result is an executable file, thdsrver. To run the executable file against the sample database, enter the executable name:
thdsrver