This section includes the following topics:
| Note: | The Visual C++ compiler is used for both C and C++ sample programs supplied in the %DB2PATH\samples\c and %DB2PATH\samples\cpp directories. The batch files in both these directories contain commands to accept either a C or C++ source file, depending on the file extension. By default, the C++ commands are commented out in the batch files in %DB2PATH\samples\c, and the C commands are commented out in the batch files in %DB2PATH\samples\cpp. Except for the first two topics where batch files are not used, this section demonstrates building programs using the C batch files. |
DB2 ADO programs using Visual C++ can be compiled the same as regular C++ programs, once you make the following change.
To have your C++ source program run as an ADO program, you can put the following import statement at the top of your source program file:
#import "C:\program files\common files\system\ado\msado<VERSION NUMBER>.dll" \ no_namespace \ rename( "EOF", "adoEOF")
where <VERSION NUMBER> is the version number of the ADO library.
When the program is compiled, the user will need to verify that the msado<VERSION NUMBER>.dll is in the path specified. An alternative is to add C:\program files\common files\system\ado to the environment variable LIBPATH, and then use this shorter import statement in your source file:
#import <msado<VERSION NUMBER>.dll> \ no_namespace \ rename( "EOF", "adoEOF")
This is the method used in the DB2 sample program, BLOBAccess.dsp.
With this IMPORT statement, your DB2 program will have access to the ADO library. You can now compile your Visual C++ program as you would any other program. If you are also using another programming interface, such as DB2 APIs, or DB2 CLI, refer to the appropriate section in this chapter for additional information on building your program.
DB2 provides Visual C++ ADO sample programs in the %DB2PATH%\samples\ADO\VC directory.
This section describes Object Linking and Embedding (OLE) automation UDFs in Microsoft Visual C++, as well as a sample OLE automation controller for stored procedures.
You can implement OLE automation UDFs and stored procedures in any language, as OLE is language independent, by exposing methods of OLE automation servers, and registering the methods as UDFs with DB2. Application development environments which support the development of OLE automation servers include certain versions of the following: Microsoft Visual Basic, Microsoft Visual C++, Microsoft Visual J++, Microsoft FoxPro, Borland Delphi, Powersoft PowerBuilder, and Micro Focus COBOL. Also, Java beans objects that are wrapped properly for OLE, for example with Microsoft Visual J++, can be accessed via OLE automation.
You need to refer to the documentation of the appropriate application development environment for further information on developing OLE automation servers. For more detailed information on DB2 programming using OLE automation, refer to the Application Development Guide.
Microsoft Visual C++ supports the creation of OLE automation servers. Servers can be implemented using Microsoft Foundation Classes and the Microsoft Foundation Class application wizard, or as Win32 applications. Servers can be DLLs or EXEs. Refer to the Microsoft Visual C++ documentation and to the OLE samples provided by Microsoft Visual C++ for further information. For information on building Visual C++ UDFs for DB2, see "User-Defined Functions (UDFs)".
DB2 provides self-containing samples of OLE automation UDFs in Microsoft Visual C++, located in the directory %DB2PATH%\samples\ole\msvc. For information on building and running the OLE automation UDF samples, please see the readme.txt file in %DB2PATH%\samples\ole.
Directory %DB2PATH%\samples\ole\stpcntr contains a sample OLE automation controller implemented in Microsoft Visual C++ as a stored procedure. The automation controller can be used to invoke stored procedures through OLE automation. The first SQLVAR in the SQLDA provides the OLE programmable identifier, progID, and the name of the method which should be invoked. OLE automation stored procedures must be implemented as in-process OLE automation servers.
The directory %DB2PATH%\samples\ole\msvb contains a Visual Basic project, salarysvr, with a "median" stored procedure which calculates the median salary in the STAFF table of the DB2 samples database. The stored procedure is implemented in Microsoft Visual Basic and DB2 CLI. The directory %DB2PATH%\samples\ole\msvc contains a DB2 client program, salaryclt, implemented in Microsoft Visual C++, which invokes the "median" stored procedure.
For information on setting up and running the automation controller and the projects using it, please see the readme.txt file in %DB2PATH%\samples\ole.
The batch file bldmsapi.bat, in %DB2PATH%\samples\c, and %DB2PATH%\samples\cpp, contains the commands to build a DB2 API program.
The parameter, %1, specifies the name of your source file.
@echo off rem bldmsapi.bat file rem Builds a DB2 API program in C or C++ rem using the Microsoft Visual C++ compiler. rem Usage: bldmsapi prog_name if "%1" == "" goto error rem Compile the C program. cl -Z7 -Od -c -W2 -D_X86_=1 -DWIN32 %1.c util.c rem For C++, comment out the above line, and uncomment the following: rem cl -Z7 -Od -c -W2 -D_X86_=1 -DWIN32 %1.cxx util.cxx rem Link the program. link -debug:full -debugtype:cv -out:%1.exe %1.obj util.obj db2api.lib goto exit :error echo Usage: bldmsapi prog_name :exit @echo on
| Compile and Link Options for bldmsapi |
|---|
|
The batch file contains the following compile options:
|
|
The batch file contains the following link options:
Refer to your compiler documentation for additional compiler
options.
|
To build the sample program, client, from either the source file client.c , in %DB2PATH%\samples\c, or from the source file client.cxx , in %DB2PATH%\samples\cpp, enter:
bldmsapi client
The result is an executable file, client.exe. You can run the executable file by entering the executable name (without the extension) on the command line:
client
The batch file bldmcli.bat, in %DB2PATH%\samples\cli, contains the commands to build a DB2 CLI program.
The parameter, %1, specifies the name of your source file.
@echo off rem bldmcli batch file - Windows 32-bit Operating Systems rem Builds a CLI program with Microsoft Visual C++. rem Usage: bldmcli prog_name if "%1" == "" goto error rem Compile the error-checking utility. cl -Z7 -Od -c -W1 -D_X86=1 -DWIN32 samputil.c rem Compile the program. cl -Z7 -Od -c -W1 -D_X86=1 -DWIN32 %1.c rem Link the program. link -debug:full -debugtype:cv -OUT:%1.exe %1.obj samputil.obj db2cli.lib goto exit :error echo Usage: bldmcli prog_name :exit @echo on
| Compile and Link Options for bldmcli |
|---|
|
The batch file contains the following compile options:
|
|
The batch 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:
bldmcli basiccon
The result is an executable file, basiccon.exe. You can run the executable file against the SAMPLE database by entering the executable name (without the extension):
basiccon
The batch file bldmclis.bat, in %DB2PATH%\samples\cli, contains the commands to build a CLI stored procedure. The batch file builds the stored procedure into a DLL on the server.
The parameter, %1, specifies the name of your source file. The batch file uses the source file name, %1, for the DLL name.
@echo off rem bldmclis.bat file - Windows 32-bit Operating Systems rem Builds a CLI stored procedure using the Microsoft Visual C++ compiler. rem Usage: bldmclis prog_name if "%1" == "" goto error rem Compile the program. cl -Z7 -Od -c -W2 -D_X86_=1 -DWIN32 %1.c samputil.c rem Link the program. link -debug:full -debugtype:cv -out:%1.dll %1.obj samputil.obj db2cli.lib -def:%1.def rem Copy the stored procedure DLL to the 'function' directory copy %1.dll %DB2PATH%\function goto exit :error echo Usage: bldmclis prog_name :exit @echo on
| Compile and Link Options for bldmclis |
|---|
|
The batch file contains the following compile options:
|
|
The batch file contains the following link options:
Refer to your compiler documentation for additional compiler
options.
|
To build the outsrv2 stored procedure from the source file outsrv2.c , enter:
bldmclis outsrv2
The batch file uses the module definition file outsrv2.def, contained in the same directory as the CLI sample programs, to build the stored procedure. The batch file copies the stored procedure DLL, outsrv2.dll, to the server in the path %DB2PATH%\function. For DB2DARI parameter style stored procedures where the invoked procedure matches the stored procedure DLL 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 %DB2PATH%\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. |
Once you build the stored procedure, outsrv2, you can build the client application that calls the stored procedure. You can build outcli2 using the batch file bldmcli. See "DB2 CLI Applications" for details.
To run the stored procedure, enter:
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 batch file bldmsemb.bat, in %DB2PATH%\samples\c, and in %DB2PATH%\samples\cpp, 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. 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.
@echo off rem bldmsemb.bat file rem Builds a C or C++ program containing embedded SQL rem using the Microsoft Visual C++ compiler. rem Usage: bldmsemb prog_name [ db_name [ userid password ]] rem Connect to a database. if "%1" == "" goto error if "%2" == "" goto case1 if "%3" == "" goto case2 if "%4" == "" goto error goto case3 :case1 db2 connect to sample goto continue :case2 db2 connect to %2 goto continue :case3 db2 connect to %2 user %3 using %4 goto continue :continue rem Precompile the program. db2 prep %1.sqc bindfile rem For C++, comment out the above line and uncomment the following: rem db2 prep %1.sqx bindfile rem Bind the program to the database. db2 bind %1.bnd rem Disconnect from the database. db2 connect reset rem Compile the program. cl -Z7 -Od -c -W2 -D_X86_=1 -DWIN32 %1.c util.c rem For C++, comment out the above line and uncomment the following: rem cl -Z7 -Od -c -W2 -D_X86_=1 -DWIN32 %1.cxx util.cxx rem Link the program. link -debug:full -debugtype:cv -out:%1.exe %1.obj util.obj db2api.lib goto exit :error echo Usage: bldmsemb prog_name [ db_name [ userid password ]] :exit @echo on
| Compile and Link Options for bldmsemb |
|---|
|
The batch file contains the following compile options:
|
|
The batch file contains the following link options:
Refer to your compiler documentation for additional compiler
options.
|
To build the sample program updat, from the C source file updat.sqc in %DB2PATH%\samples\c, or from the C++ source file updat.sqx in %DB2PATH%\samples\cpp, enter:
bldmsemb updat
The result is an executable file updat.exe. You can run the executable file against the SAMPLE database by entering the executable name (without the extension):
updat
The batch file bldmsstp.bat, in %DB2PATH%\samples\c, and in %DB2PATH%\samples\cpp, contains the commands to build an embedded SQL stored procedure. The batch file builds the stored procedure into a DLL on the server.
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 batch file uses the source file name, %1, for the DLL name.
@echo off rem bldmsstp.bat file rem Builds a C or C++ stored procedure using the Microsoft Visual C++ compiler. rem Usage: bldmsstp <prog_name> [ <db_name> [ < userid> <password> ]] rem Connect to a database. if "%1" == "" goto error if "%2" == "" goto case1 if "%3" == "" goto case2 if "%4" == "" goto error goto case3 :case1 db2 connect to sample goto continue :case2 db2 connect to %2 goto continue :case3 db2 connect to %2 user %3 using %4 goto continue :continue rem Precompile the program. db2 prep %1.sqc bindfile rem For C++, comment out the above line and uncomment the following: rem db2 prep %1.sqx bindfile rem Bind the program to the database. db2 bind %1.bnd rem Disconnect from the database. db2 connect reset rem Compile the program. cl -Z7 -Od -c -W2 -D_X86_=1 -DWIN32 %1.c rem For C++, comment out the above line and uncomment the following: rem cl -Z7 -Od -c -W2 -D_X86_=1 -DWIN32 %1.cxx rem Link the program. link -debug:full -debugtype:cv -out:%1.dll %1.obj db2api.lib -def:%1.def rem Copy the stored procedure DLL to the 'function' directory copy %1.dll %DB2PATH%\function goto exit :error echo Usage: bldmsstp <prog_name> [ <db_name> [ < userid> <password> ]] :exit @echo on
| Compile and Link Options for bldmsstp |
|---|
|
The batch file contains the following compile options:
|
|
The batch file contains the following link options:
Refer to your compiler documentation for additional compiler
options.
|
To build the outsrv stored procedure from either the C source file, outsrv.sqc , or the C++ source file, outsrv.sqx , enter:
bldmsstp outsrv
The batch file uses the module definition file outsrv.def, contained in the same directory as the sample programs, to build the stored procedure. The batch file copies the stored procedure DLL, outsrv.dll, to the server in the path %DB2PATH%\function. For DB2DARI parameter style stored procedures where the invoked procedure matches the stored procedure DLL 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 %DB2PATH%\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. |
Once you build the stored procedure, outsrv, you can build the client application that calls the stored procedure. You can build outcli using the bldmsemb file. See "Embedded SQL Applications" for details.
To run the stored procedure, enter:
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 batch file bldmsudf, in %DB2PATH%\samples\c, and in %DB2PATH%\samples\cpp, contains the commands to build a UDF.
UDFs cannot contain embedded SQL statements. Therefore, to build a UDF program, you do not need to connect to a database to precompile and bind the program.
The batch file takes one parameter, %1, which specifies the name of your source file. It uses the source file name, %1, for the DLL name.
@echo off rem bldmsudf.bat file rem Builds a C or C++ user-defined function (UDF). rem Usage: bldmsudf udf_prog_name if "%1" == "" goto error rem Compile the program. cl -Z7 -Od -c -W2 -D_X86_=1 -DWIN32 %1.c rem For C++, comment out the above line and uncomment the following: rem cl -Z7 -Od -c -W2 -D_X86_=1 -DWIN32 %1.cxx rem Link the program. link -debug:full -debugtype:cv -dll -out:%1.dll %1.obj db2api.lib db2apie.lib -def:%1.def rem Copy the UDF DLL to the 'function' directory copy %1.dll %DB2PATH%\function @echo on
| Compile and Link Options for bldmsudf |
|---|
|
The batch file bldmsudf contains the following compile options:
|
|
The batch file contains the following link options:
Refer to your compiler documentation for additional compiler
options.
|
To build the user-defined function udf, from the source file udf.c , enter:
bldmsudf udf
The batch file uses the module definition file udf.def, contained in the same directory as the sample programs, to build the user-defined function. The batch file copies the user-defined function DLL, udf.dll, to the server in the path %DB2PATH%\function.
Once you build udf, you can build the client application, calludf, that calls it. DB2 CLI, as well as embedded SQL C and C++ versions of this program are provided.
You can build the DB2 CLI calludf program from the calludf.c source file in %DB2PATH%\samples\cli using the batch file bldmscli. Refer to "DB2 CLI Applications" for details.
You can build the embedded SQL C calludf program from the calludf.sqc source file in %DB2PATH%\samples\c using the batch file bldmsemb. Refer to "Embedded SQL Applications" for details.
You can build the embedded SQL C++ calludf program from the calludf.sqx source file in %DB2PATH%\samples\cpp using the batch file bldmsemb. Refer to "Embedded SQL Applications" for details.
To run the UDF, enter:
calludf
The 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. Connect to the database, then enter:
SELECT name, DOLLAR(salary), SAMP_MUL(DOLLAR(salary), FACTOR(1.2)) FROM staff
You do not have to type the command line processor commands in uppercase.