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, generally, as build files.
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 with the same name is built. This is unlike a makefile. It means a developer can quickly modify an existing program and rerun it without having to delete previous object and executable files.
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 for the embedded SQL samples also contain optional parameters (user ID and password) as they are needed to connect to the database in the building process (precompiling and binding). Making these parameters optional means that if a developer is building a 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 as input parameters to the build file. 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 specified when running the build 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 hardcodes all 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 outsrv2 into a shared library that can be called by the client application, outcli2.
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, outsrv2, and copies it to the function sub-directory:
#outsrv2 is an output Stored procedure, called by outcli2
outsrv2 : outsrv2.o ;
$(CC) -o outsrv2 outsrv2.c $(CFLAGS) -shared $(LIBS) ;
$(ERASE) $(DB2PATH)/function/outsrv2 ;
$(COPY) outsrv2 $(DB2PATH)/function/outsrv2 ;
There is another build file that is called by makefiles that contain embedded SQL programs. It is called embprep (or embprepp for C++), and 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 needs the user ID, password, and database name to connect to the database on the server. The makefile passes these values to embprep, or embprepp, 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 precompile and bind file. The following is an example of the embprep file being called by the Micro Focus makefile on Solaris to build the embedded SQL application, updat:
updat.cbl : updat.sqb;
embprep updat $(DB) $(UID) $(PWD)
updat.o : updat.cbl checkerr.o
$(CC) updat.cbl ;
updat : updat.o checkerr.o;
$(LINK) updat.o $(LINKOBJS)
As is the case with the DB2 CLI stored procedure example above, the makefile variables, contained within the "$(" and ")" characters, are defined at the beginning of the makefile.
DB2 provides a utility file consisting of functions for error-checking and printing out error information. A version of this file is provided for each language in the samples directory. When used with an application program, the utility provides helpful error information, and makes debugging a DB2 program much easier. Most of the error-checking utilities use the DB2 APIs GET SQLSTATE MESSAGE and GETERROR MESSAGE to obtain pertinant SQLSTATE and SQLCA information related to problems encountered in program execution. The DB2 CLI utility, samputil, 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. For Java, an error-checking utility file is not used. It is unnecessary 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 utility. Here are the object files created for the different programming languages:
The following example demonstrates how the error-checking utilities are used in DB2 programs. The util.c source file defines the check_error function. This function checks the SQLCODE flag and prints out any information that is available related to the specific error indicated by this flag. A C program that uses the util program, such as updat in the example below, defines a macro for this function as follows:
#define CHECKERR(CE_STR) if (check_error (CE_STR, &sqlca) != 0) return 1;
and then calls the macro with the appropriate string argument for each database command that is executed:
strcpy (jobUpdate, "Clerk");
EXEC SQL UPDATE staff SET job = :jobUpdate WHERE job = 'Mgr';
CHECKERR ("UPDATE STAFF");
If the statement fails, then the CHECKERR macro ensures an appropriate error message is printed out for the user.
Developers are encouraged to use and build upon these error-checking utilities when creating their own DB2 programs.