DB2 provides an array of building tools for your program development needs. These tools make it easy to build the supplied sample programs, which demonstrate the broad range of DB2 functionality. The tools also allow you to build your own database programs. For each supported compiler, DB2 provides build files, makefiles, and error-checking utilities, which are made available in the samples directory along with the sample programs. This section explains how these tools can be used.
Each of the following chapters uses files that contain compile and link commands for building programs with the supported platform compilers. These files are known as command files on OS/2, script files on UNIX, and batch files on Windows 32-bit operating systems. We refer to them, generically, as build files.
Build files are provided by DB2 for each language on supported platforms where the types of programs they build are available, in the same directory as the sample programs for each language. Table 16 lists the build files for all languages on all supported platforms except for C++ on Windows 32-bit operating systems. The filename extensions have been left off. For OS/2, the extension is .cmd; for Windows 32-bit operating systems, the extension is .bat. There is no extension for UNIX platforms.
For Windows 32-bit operating systems, there are two supported C++
compilers: Microsoft Visual C++ and IBM VisualAge C++. For these
compilers, respectively, an "m" or a "v" has been inserted after the "bld" for
each build file name, except for bldclisp, which becomes either
bldmclis or bldvclis. These build files are
listed in Table 17. The .bat extension has been left
off.
| Build File | Types of Programs Built |
|---|---|
| bldsqlj | Java Embedded SQLJ applications. |
| bldsqljs | Java Embedded SQLJ stored procedures. |
| bldcli | DB2 CLI applications, with or without embedded SQL. |
| bldapi | DB2 CLI applications, with or without embedded SQL, that require linking in the utilapi utility file that contains DB2 APIs for creating and dropping a database. |
| bldclisp | DB2 CLI stored procedures (non-embedded SQL). |
| bldapp | Application programs with or without embedded SQL. |
| bldsrv | Embedded SQL stored procedures. |
| bldudf | User-defined functions (UDFs). |
| bldmt | Multi-threaded embedded SQL applications (only available for C/C++ on supported UNIX platforms). |
| bldevm | The event monitor sample program, evm (only available on AIX and OS/2). |
Table 17. C/C++ Build Files for Windows 32-bit operating systems
| Build File | Types of Programs Built |
|---|---|
| bldmcli | Microsoft Visual C++ DB2 CLI applications, with or without embedded SQL. |
| bldvcli | VisualAge C++ DB2 CLI applications, with or without embedded SQL. |
| bldmapi | Microsoft Visual C++ DB2 CLI applications, with or without embedded SQL, that require linking in the utilapi utility file that contains DB2 APIs for creating and dropping a database. |
| bldvapi | VisualAge C++ DB2 CLI applications, with or without embedded SQL, that require linking in the utilapi utility file that contains DB2 APIs for creating and dropping a database. |
| bldmclis | Microsoft Visual C++ DB2 CLI stored procedures (non-embedded SQL). |
| bldvclis | VisualAge C++ DB2 CLI stored procedures (non-embedded SQL). |
| bldmapp | Microsoft Visual C++ application programs with or without embedded SQL. |
| bldvapp | VisualAge C++ application programs with or without embedded SQL. |
| bldmsrv | Microsoft Visual C++ Embedded SQL stored procedures. |
| bldvsrv | VisualAge C++ Embedded SQL stored procedures. |
| bldmudf | Microsoft Visual C++ User-defined functions (UDFs). |
| bldvudf | VisualAge C++ User-defined functions (UDFs). |
The build files are documented in this book because they demonstrate very clearly the compile and link options that DB2 recommends for building various kinds of programs with the supported compilers. There are generally many other compile and link options available, and users are free to experiment with them. See your compiler documentation for all the compile and link options provided. Besides building the sample programs, developers can also build their own programs with the build files. The sample programs can be used as templates that can be modified by users to assist their programming development.
Conveniently, the build files are designed to build a source file with any file name allowed by the compiler. This is unlike the makefiles, where the program names are hardcoded into the file. The build files use the $1 variable on UNIX, or the %1 variable on OS/2 and Windows 32-bit operating systems, to substitute internally for the program name. Other similarly named variables substitute for other arguments that may be required. The build files allow for quick and easy experimentation, as each one is suited to a specific kind of program-building, such as DB2 APIs, DB2 CLI, embedded SQL, stored procedures, or user-defined functions. Each type of build file is provided wherever the specific kind of program it is designed for is supported by the compiler.
The object and executable files produced by a build file are automatically over-written each time a program is built, even if the source file is not modified. This is unlike a makefile. It means a developer can rebuild an existing program without having to delete previous object and executable files, or modifying the source.
The build files contain a default setting for the sample database. If the user is accessing another database, he or she can simply supply another parameter to over-write the default. If they are using the other database consistently, they may wish to hardcode this database name, replacing sample, within the build file itself.
The build files used for embedded SQL programs call another file, embprep, that contains the precompile and bind steps for embedded SQL programs. These steps may require the optional parameters user ID and password, depending on where the embedded SQL program is being built.
If a developer is building the program on a server instance where the database is located, then the user ID and password will be common to both, and therefore need not be provided. On the other hand, if a developer is in a different instance, such as on a client machine accessing a server database remotely, then these parameters would have to be provided. The embprep file is also used by the makefile. See Makefiles, below, for more on this file.
Finally, the build files can be modified by the developer for his or her convenience. Besides changing the database name in the build file (explained above) the developer can easily hardcode other parameters within the file, change compile and link options, or change the default DB2 instance path. The simple, straightforward, and specific nature of the build files makes tailoring them to your needs an easy task.
Each samples directory for a supported compiler includes a makefile for building the supplied sample programs. The makefile builds most of the DB2 sample programs shipped for the compiler. It uses variables for many of the common elements used for each sample program compilation. The syntax for the makefiles and the output from their commands differ in some important respects from that of the build files supplied. The make commands are simple and powerful to use:
Unlike the build files, the makefiles will not over-write existing intermediate and executable files for programs listed within it. This makes it faster, using the make all command, to create executables for some of the files if other files already have executables, as make all will just ignore these files. But it also assumes the need for the make clean and make cleanall commands, to get rid of existing object and executable files when they are not needed.
The makefiles can be used for program development. They are less convenient to use then the build files, but if you want the power and convenience of the make commands, this is a route to consider. To include a new program in an existing makefile, code in the syntax for the program entry, using as a template a similar kind of existing sample program. Note that the syntax differs for DB2 API, DB2 CLI, and embedded SQL programs, as well as for stored procedures and UDFs.
Here is an example of how you can use the supplied makefiles. This makefile, from the samples/cli directory on AIX, builds all the supplied DB2 CLI samples on AIX with the IBM C compiler. This example demonstrates how to build the stored procedure program, spserver, into a shared library that can be called by the client application, spclient.
Before using the makefile, you may need to edit the following variables contained in the file:
On AIX, the DB2 CLI makefile defines the variables DB2PATH, CC, COPY, ERASE, CFLAGS, and LIBS as follows:
# Set DB2PATH to where DB2 will be accessed. # The default is the instance path. DB2PATH=$(HOME)/sqllib CC = cc COPY = cp ERASE = rm -f # The required compiler flags CFLAGS= -I$(DB2PATH)/include # The required libraries LIBS= -L$(DB2PATH)/lib -Wl,-rpath,$(DB2PATH)/lib -ldb2
The makefile uses these variables when it compiles the stored procedure, spserver, and copies the shared library to the function subdirectory:
spserver : utilcli.o
$(CC) -o spserver spserver.c utilcli.o $(CFLAGS) $(LIBS) \
-H512 -T512 -bE:spserver.exp -e outlanguage
$(ERASE) $(DB2PATH)/function/spserver
$(COPY) spserver $(DB2PATH)/function/spserver
For embedded SQL programs, the makefile calls the embprep file, which contains the precompile and bind steps for these embedded SQL programs. Making this a separate file, which is called for each embedded SQL program, saves repeating these steps within the body of the makefile itself. This file uses the parameters for user ID, password, and database name to connect to the database on the server. The makefile passes these values to embprep when it calls it.
The database variable, DB, is hardcoded by default to the sample database, and can be changed by the user if another database is used. The user ID and password variables, UID and PWD, are not set to any value by default. These optional parameters do not need to be used if the user is already working in the same instance as the server database. However, if this is not the case, for example, if the user is remotely connecting to the server from a client machine, then he or she can modify the makefile by giving the appropriate values to the UID and PWD variables, and they will be automatically passed to the embprep precompile and bind file. The following is an example of the embprep file being called by the Micro Focus COBOL makefile on Windows NT to build the embedded SQL application, updat:
updat.cbl : updat.sqb
embprep updat $(DB) $(UID) $(PWD)
updat.obj : updat.cbl
$(CC) updat.cbl;
updat : updat.obj checkerr.obj
$(LINK) updat.obj checkerr.obj $(LIBS)
The DB2 AD Client provides several utility files. These files have functions for error-checking and printing out error information. The exception to this is the CLI utility file, utilapi.c, which calls the DB2 APIs to create and drop a database. Utility files are provided for each language in the samples directory. When used with an application program, the error-checking utility files provide helpful error information, and make debugging a DB2 program much easier. Most of the error-checking utilities use the DB2 APIs GET SQLSTATE MESSAGE and GETERROR MESSAGE to obtain pertinent SQLSTATE and SQLCA information related to problems encountered in program execution. The DB2 CLI utility file, utilcli.c, does not use these DB2 APIs; instead it uses equivalent DB2 CLI statements. With all the error-checking utilities, descriptive error messages are printed out to allow the developer to quickly understand the problem.
Some DB2 programs, such as stored procedures and user-defined functions, do not need to use the utilities. They are also not necessary for Java because the SQLException object will be thrown if an exception occurs.
Here are the error-checking utility files used by DB2-supported compilers for the different programming languages:
In order to use the utility functions, the utility file must first be compiled, and then its object file linked in during the creation of the target program's executable. Both the makefile and build files in the samples directories do this for the programs that require the error-checking utilities.
The following example demonstrates how the error-checking utilities are used in DB2 programs. The utilemb.h header file defines the EMB_SQL_CHECK macro which is substituted for the functions SqlInfoPrint() and TransRollback():
#define EMB_SQL_CHECK( MSG_STR ) \ if( SqlInfoPrint( MSG_STR, &sqlca, __LINE__, __FILE__) != 0 ) TransRollback( );
SqlInfoPrint() checks the SQLCODE flag. It prints out any available information related to the specific error indicated by this flag. It also points to where the error occurred in the source code. TransRollback() allows the utility file to safely rollback a transaction where an error has occurred. It requires embedded SQL statements to connect to the database and execute a rollback. The following is an example of how the C++ program cursor calls the utility functions by using the macro, supplying the value "DECLARE CURSOR" for the MSG_STR parameter of the SqlInfoPrint() function:
Cursor::Fetch () {
EXEC SQL DECLARE c1 CURSOR FOR
SELECT name, dept FROM staff WHERE job='Mgr'
FOR UPDATE OF job;
EMB_SQL_CHECK("DECLARE CURSOR") ;
The EMB_SQL_CHECK macro ensures that if the DECLARE statement fails, the transaction will be safely rolled back, and an appropriate error message printed out.
Developers are encouraged to use and build upon these error-checking utilities when creating their own DB2 programs.