****************************************************************************** * (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 HPUX * * 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 * ******************************************************************************