******************************************************************************
* (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 SunOS
*
* 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 $HOME.
* This README describes how to build and run cpp 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 sqllib/samples/cpp to your working directory and
* ensure that directory has write permission.
*
* 2) Start the Database Manager with the following command:
* db2start
*
* 3) Create the sample database with the following command:
* db2sampl
*
* 4) Connect to the database with the following command:
* db2 connect to sample
*
* 5) To build Stored Procedures and User Defined Functions, ensure
* that you have write permission on the <install_path>/sqllib/function
* directory.
*
* 6) cd to the directory containing the files copied in Step 1.
*
******************************************************************************
*
* Building DB2 Samples
*
* There are two ways to build DB2 samples: using a make utility or using the
* build files that are included with the DB2 sample programs.
* o To build samples using the make utility see 'BUILDING SAMPLES USING
* make UTILITY'.
* o To build samples using the build files or when you do not have a
* compatible make utility see 'BUILDING SAMPLES USING BUILD FILES'.
*
******************************************************************************
*
* *** BUILDING SAMPLES USING nmake UTILITY ***
*
* If you have a compatible make utility on your system, you can use the
* makefile provided. Such a make utility may be provided by another language
* compiler. Modify the PATH variable to include the directory containing the
* make 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 'make' command in your working directory:
* o make <program name> - builds the sample identified by <program
* name>. Do not include the file extension for
* the program name. E.g. make DbAuth
* For any dependencies refer to the individual
* sample.
* o make srv - builds only samples that can be run on the
* server, including routines (stored procedures
* and User Defined Functions).
* o make rtn - builds only routines.
* o make call_rtn - builds only client programs that call
* routines.
* o make client_run - builds only programs that run completely on
* the client (not ones that call routines).
* o make all_client - builds all client samples (all programs in
* the 'call_rtn' and 'client_run' categories).
* o make all - builds all supplied sample programs
*
* NOTE: Create a database with name SAMPLE2 before running 'make 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 binary 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 binary 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
*
******************************************************************************
*
* Shell Scripts
*
* bldapp - Builds application programs
* bldmc - Builds multi-connection application programs
* bldmt - Builds a multi-threaded program
* bldrtn - Builds routines (stored procedures and UDFs)
* embprep - 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.C - How to get and set client level information.
* clisnap.C - How to get a snapshot at the client level.
* clisnapnew.C - How to get a snapshot at the client level (using API).
*
******************************************************************************
*
* Instance Level (program files that deal with the instance level of DB2)
*
* inattach.C - How to attach to and detach from an instance.
* inauth.sqC - How to display authorities at instance level.
* ininfo.C - How to get and set instance level information.
* insnap.C - How to get a snapshot at instance level.
* insnapnew.C - How to get a snapshot at instance level (using API).
* instart.C - How to stop and start the current local instance.
*
******************************************************************************
*
* Database Level (program files that deal with database objects in DB2)
*
* dbauth.sqC - How to grant/display/revoke authorities at database level.
* dbcfg.sqC - How to configure database and database manager parameters.
* dbconn.sqC - How to connect and disconnect from a database.
* dbcreate.C - How to create and drop databases.
* dbhistfile.sqC - How to read and update a database recovery file entry.
* dbinfo.C - How to get and set information at a database level.
* dbinspec.sqC - How to check architectural integrity with the
* DB2 API db2Inspect
* dblogconn.sqC - How to read database log files asynchronously with a
* database connection for compressed and uncompressed
* tables
* dblognoconn.sqC - How to read database log files asynchronously with no
* database connection
* dbmcon.sqC - How to connect and disconnect from multiple databases.
* dbmcon1.sqC - Functions used in the multiple databases program dbmcon.
* dbmcon1.h - Header file for dbmcon1.sqC.
* dbmcon2.sqC - Functions used in the multiple databases program dbmcon.
* dbmcon2.h - Header file for dbmcon2.sqC.
* dbupgrade.C - How to upgrade a database.
* dbpkg.sqC - How to work with packages.
* dbrestore.sqC - How to restore a database from a backup
* dbrollfwd.sqC - How to perform rollforward after restore of a database
* dbsnap.C - How to get a snapshot at database level.
* dbsnapnew.C - How to get a snapshot at database level (using API).
* dbthrds.sqC - How to use threads.
* dbuse.sqC - How to use database objects.
*
******************************************************************************
*
* Tablespace Level (program files that deal with tablespace objects in DB2)
*
* tscreate.sqC - 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.sqC - How to read and write LOB data.
* dtstruct.sqC - How to create, use, drop a hierarchy of structured types
* and typed tables.
* dtudt.sqC - How to create/use/drop user defined distinct types.
*
******************************************************************************
*
* Function Level (program files that demonstrate SQL functions)
*
* fnuse.sqC - 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 - CLP script that first calls spdrop.db2 and then calls
* spcreate.db2.
* spserver.exp - export file for spserver.
* spclient.sqC - Client application that calls the stored procedures in
* spserver.sqc.
* spserver.sqC - Stored procedure functions built and run on the server.
*
******************************************************************************
*
* UDF Level (program files that demonstrate user defined functions)
*
* udfcli.sqC - Client application which calls the user defined function
* in udfsrv.C
* udfemcli.sqC - Call a variety of types of embedded SQL user-defined
* functions in udfemsrv.sqC
* udfemsrv.sqC - Embedded SQL user-defined functions called by udfemcli.sqC.
* udfemsrv.exp - Export file for udfemsrv
* udfsrv.C - User defined function ScalarUDF called by udfcli.sqC sample
* udfsrv.exp - Export file for udfsrv
*
******************************************************************************
*
* Common Utility Function files
*
* utilapi.C - Error-checking utility file for non-embedded SQL DB2 API
* programs
* utilapi.h - Header file for utilapi.C
* utilemb.sqC - Error-checking utility file for embedded SQL programs.
* utilemb.h - Header file for utilemb.sqC
* utilsnap.C - Utility file for snapshot monitor programs clisnap,
* clisnapnew, dbsnap, dbsnapnew, insnap, insnapnew
*
******************************************************************************
*
* Event Monitor samples
*
* evm.sqC - demonstrates file, pipe, and table event monitors
*
******************************************************************************