******************************************************************************
* (c) Copyright IBM Corp. 2007 All rights reserved.
*
* The following sample of source code ("Sample") is owned by International
* Business Machines Corporation or one of its subsidiaries ("IBM") and is
* copyrighted and licensed, not sold. You may use, copy, modify, and
* distribute the Sample in any form without payment to IBM, for the purpose of
* assisting you in the development of your applications.
*
* The Sample code is provided to you on an "AS IS" basis, without warranty of
* any kind. IBM HEREBY EXPRESSLY DISCLAIMS ALL WARRANTIES, EITHER EXPRESS OR
* IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. Some jurisdictions do
* not allow for the exclusion or limitation of implied warranties, so the above
* limitations or exclusions may not apply to you. IBM shall not be liable for
* any damages you suffer as a result of using, copying, modifying or
* distributing the Sample, even if IBM has been advised of the possibility of
* such damages.
*
******************************************************************************
*
* README for C++ Samples on WINDOWS
*
* The <install_path>\sqllib\samples\cpp directory contains this README file
* where <install_path> is the location of DB2 9.7 on your hard drive.
* The default location for <install_path> is C:\Program Files\IBM.
* This README describes how to build and run C++ sample code for DB2 9.7.
*
* The DB2 9.7 sample code for C++ is located in the following directory:
* <install_path>\sqllib\samples\cpp
*
* It is recommended that you copy the files from this directory to your
* working directory prior to building the sample programs. The sample
* programs directory is typically read-only on most platforms and some
* samples generate temporary files.
*
* WARNING: Some of these samples may change your database or database manager
* configuration. Execute the samples against a 'test' database only,
* such as the DB2 SAMPLE database.
*
* NOTE: These samples are tested on sample database created using db2sampl.
*
******************************************************************************
*
* Prepare your DB2 sample development environment
*
* 1) Copy the files from <install_path>\sqllib\samples\cpp to your working
* directory and ensure that directory has write permission.
*
* 2) All samples should be run and built in a DB2 Command Window.
* The DB2 Command Window is needed to execute db2 specific commands.
* You can follow the step below to open DB2 Command window.
* From the Start Menu click Start --> Programs --> IBM DB2 -->
* <DB2 copy name> --> Command Line Tools --> Command Window.
*
* 3) Start the Database Manager with the following command:
* db2start
*
* 4) Create the sample database with the following command:
* db2sampl
*
* 5) Connect to the database with the following command:
* db2 connect to sample
*
* 6) To build Stored Procedures and User Defined Functions, ensure
* that you have write permission on the <install_path>\sqllib\function
* directory.
*
* 7) cd to the directory containing the files copied in Step 1.
*
******************************************************************************
*
* Building DB2 Samples
*
* There are two ways to build DB2 samples: using a nmake utility or using the
* build files that are included with the DB2 sample programs.
* o To build samples using the nmake utility see 'BUILDING SAMPLES USING
* nmake UTILITY'.
* o To build samples using the build files or when you do not have a
* compatible nmake utility see 'BUILDING SAMPLES USING BUILD FILES'.
*
******************************************************************************
*
* *** BUILDING SAMPLES USING nmake UTILITY ***
*
* If you have a compatible nmake utility on your system, you can use the
* makefile provided. Such a nmake utility may be provided by another language
* compiler. Modify the PATH variable to include the directory containing the
* nmake utility.
*
* Depending on your environment, the makefile might have to be modified.
* For more details refer to the 'VARIABLES' section in the makefile.
*
* Execute the appropriate 'nmake' command in your working directory:
* o nmake <program name> - builds the sample identified by <program
* name>. Do not include the file extension for
* the program name. E.g. nmake DbAuth
* For any dependencies refer to the individual
* sample.
* o nmake srv - builds only samples that can be run on
* the server, including routines (stored
* procedures and User Defined Functions).
* o nmake rtn - builds only routines.
* o nmake call_rtn - builds only client programs that call
* routines.
* o nmake client_run - builds only programs that run completely
* on the client (not ones that call routines).
* o nmake all_client - builds all client samples (all programs
* in the 'call_rtn' and 'client_run'
* categories).
* o nmake all - builds all supplied sample programs
*
* NOTE: Create a database with name SAMPLE2 before running 'nmake all' as
* some of the samples require two databases. Create second database
* with the following commands:
* db2 connect reset -- To disconnect from sample database.
* db2 create database sample2 -- Create second database.
* db2 connect to sample -- Reconnect to sample database.
*
******************************************************************************
*
* *** BUILDING SAMPLES USING BUILD FILES ***
*
* As an alternative to the makefile, the build files included with the DB2
* samples can be used to build the CPP sample programs.
*
* Building Standalone Samples:
* o bldapp <prog_name>
* <prog_name> - the name of the sample program without
* any extension.
* For any additional dependencies refer to the individual sample.
*
* Building and Executing Stored Procedures:
* o Build stored procedure server and copy the resulting object file
* to the sqllib/function directory with the following command:
* bldrtn <prog_name>
* <prog_name> - Name of the sample program without any
* extension.
* o Catalog stored procedures with the following command:
* spcat
* o Build stored procedure client with the following command:
* bldapp <prog_name>
* <prog_name> - Name of the sample program without any
* extension.
*
* Building and Executing User Defined Functions:
* o Build UDF server and copy the resulting object file to the
* sqllib/function directory with the following command:
* bldrtn <prog_name>
* <prog_name> - Name of the sample program without any
* extension.
* o Catalog User Defined Functions with the following command:
* udfcat
* o Build UDF client with the following command:
* bldapp <prog_name>
* <prog_name> - Name of the sample program without any
* extension.
*
******************************************************************************
*
* Common file Descriptions
*
* The following are the common files for C++ samples. For more
* information on these files, refer to the program source files.
*
******************************************************************************
*
* Common files
*
* README - this file!
* makefile - Makefile for most sample files
*
******************************************************************************
*
* Batch files
*
* bldapp.bat - Builds application programs
* bldmc.bat - Builds multi-connection application programs
* bldmt.bat - Builds multi-threaded application programs
* bldrtn.bat - Builds routines (stored procedures and UDFs)
* embprep.bat - Precompiles and binds embedded SQL programs
*
******************************************************************************
*
* Samples Design
*
* Most of the C++ sample programs are organized to reflect an object-based
* design of the distinct levels of DB2. A sample's level is indicated by a
* two character identifier at the beginning of the sample name. These levels
* show a hierarchical structure: an application can access different
* instances, an instance can have different databases, etc. Here are the DB2
* levels demonstated by the C++ samples:
*
* Identifier DB2 Level
*
* cl Client Level.
* in Instance Level.
* db Database Level.
* ts Tablespace Level.
* tb Table Level.
* dt Data Type Level.
*
******************************************************************************
*
* Other Samples
*
* Besides the samples organized in the DB2 Level design, other samples show
* specific kinds of application methods:
*
* Identifier Application Method
*
* fn SQL functions.
* sp Stored Procedures.
* ud User Defined Functions.
*
******************************************************************************
*
* C++ Sample Descriptions
*
* The following are the C++ sample files included with DB2. For more
* information on the sample programs, refer to the program source
* files.
*
******************************************************************************
*
* Client Level (program files that deal with the client level of DB2)
*
* cli_info.cxx - How to get and set client level information.
* clisnap.cxx - How to get a snapshot at the client level.
* clisnapnew.cxx - How to get a snapshot at the client level (using API).
*
******************************************************************************
*
* Instance Level (program files that deal with the instance level of DB2)
*
* inattach.cxx - How to attach to and detach from an instance.
* inauth.sqx - How to display authorities at instance level.
* ininfo.cxx - How to get and set instance level information.
* insnap.cxx - How to get a snapshot at instance level.
* insnapnew.cxx - How to get a snapshot at instance level (using API).
* instart.cxx - How to stop and start the current local instance.
*
******************************************************************************
*
* Database Level (program files that deal with database objects in DB2)
*
* dbauth.sqx - How to grant/display/revoke authorities at database level.
* dbcfg.sqx - How to configure database and database manager parameters.
* dbconn.sqx - How to connect and disconnect from a database.
* dbcreate.cxx - How to create and drop databases.
* dbhistfile.sqx - How to read and update a database recovery file entry.
* dbinfo.cxx - How to get and set information at a database level.
* dbinspec.sqx - How to check architectural integrity with the
* DB2 API db2Inspect
* dblogconn.sqx - How to read database log files asynchronously with a
* database connection for compressed and uncompressed
* tables
* dblognoconn.sqx - How to read database log files asynchronously with no
* database connection
* dbmcon.sqx - How to connect and disconnect from multiple databases.
* dbmcon1.sqx - Functions used in the multiple databases program dbmcon.
* dbmcon1.h - Header file for dbmcon1.sqx.
* dbmcon2.sqx - Functions used in the multiple databases program dbmcon.
* dbmcon2.h - Header file for dbmcon2.sqx.
* dbupgrade.cxx - How to upgrade database.
* dbpkg.sqx - How to work with packages.
* dbrestore.sqx - How to restore a database from a backup
* dbrollfwd.sqx - How to perform rollforward after restore of a database
* dbsnap.cxx - How to get a snapshot at database level.
* dbsnapnew.cxx - How to get a snapshot at database level (using API).
* dbthrds.sqx - How to use threads.
* dbuse.sqx - How to use database objects.
*
******************************************************************************
*
* Tablespace Level (program files that deal with tablespace objects in DB2)
*
* tscreate.sqx - How to create/drop bufferpools and tablespaces.
*
******************************************************************************
*
* Table Level (program files that deal with table objects in DB2)
*
* tbast.sqC - How to use staging table for updating deferred AST
* tbcompress.sqC - How to create tables with null and default value
* compression option
* tbconstr.sqC - How to work with table constraints.
* tbselcreate.db2 - CLP script to create tables
* tbseldrop.db2 - CLP script to drop tables
* tbselinit - Script that first calls tbseldrop.db2 and then calls
* tbselcreate.db2.
* tbcreate.sqC - How to create, alter, and drop tables.
* tbinfo.sqC - How to get and set information at a table level.
* tbintrig.sqC - How to use INSTEAD OF triggers.
* tbmerge.sqC - How to use the MERGE statement.
* tbmod.sqC - How to modify information in a table.
* tbmove.sqC - How to move a table.
* tbonlineinx - How to create and reorg indexes on a table
* tbpriv.sqC - How to grant/display/revoke privileges at a table level.
* tbread.sqC - How to read information in a table.
* tbreorg.sqC - How to reorganize a table.
* tbrunstats - How to perform runstats on a table
* tbsavept.sqC - How to use external savepoints
* tbsel.sqC - How to select from each of: insert, update, delete.
* tbtemp.sqC - How to use a declared temporary table
* tbtrig.sqC - How to use a trigger on a table.
* tbumqt.sqC - How to use user materialzed query tables (summary tables)
* tbloadcursor.sqC - How to load data into a table using either the CURSOR
* or REMOTEFETCH media types.
*
******************************************************************************
*
* Data Type Level (programs that deal with data types)
*
* dtlob.sqx - How to read and write LOB data.
* dtstruct.sqx - How to create, use, drop a hierarchy of structured types
* and typed tables
* dtudt.sqx - How to create/use/drop user defined distinct types.
*
******************************************************************************
*
* Function Level (program files that demonstrate SQL functions)
*
* fnuse.sqx - How to use SQL functions.
*
******************************************************************************
*
* Stored Procedure Level (program files that demonstrate stored procedures)
*
* spcreate.db2 - CLP script to issue CREATE PROCEDURE statements
* spdrop.db2 - CLP script to drop stored procedures from the catalog
* spcat.bat - Batch file that first calls spdrop.db2 and then calls
* spcreate.db2.
* spserver.def - Definition file for spserver
* spclient.sqx - Client application that calls the stored procedures in
* spserver.sqc.
* spserver.sqx - Stored procedure functions built and run on the server.
*
******************************************************************************
*
* UDF Level (program files that demonstrate user defined functions)
*
* udfcli.sqx - Client application which calls the user defined function
* in udfsrv.cxx
* udfemcli.sqx - Call a variety of types of embedded SQL user-defined
* functions in udfemsrv.sqx
* udfemsrv.sqx - Embedded SQL user-defined functions called by udfemcli.sqx.
* udfsrv.cxx - User defined function ScalarUDF called by udfcli.sqx sample
* udfemsrv.def - Definition file for udfemsrv
* udfsrv.def - Definition file for udfsrv
*
******************************************************************************
*
* Common Utility Function files
*
* utilapi.cxx - Error-checking utility file for non-embedded SQL DB2 API
* programs
* utilapi.h - Header file for utilapi.cxx
* utilemb.sqx - Error-checking utility file for embedded SQL programs.
* utilemb.h - Header file for utilemb.sqx
* utilsnap.cxx - Utility file for snapshot monitor programs clisnap,
* clisnapnew, dbsnap, dbsnapnew, insnap, insnapnew
*
******************************************************************************
*
* Event Monitor samples
*
* evm.sqC - demonstrates file, pipe, and table event monitors
*
******************************************************************************