README

******************************************************************************
* (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 Linux 
*
* 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
* 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
*
******************************************************************************
******************************************************************************
* Support for these samples will be provided in the subsequent releases
******************************************************************************
* 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.
******************************************************************************