******************************************************************************
* (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/c 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> for SunOS is $HOME.
* 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/c
*
* 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/c 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 make 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 C 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 all files
*
******************************************************************************
*
* Common Utility Function files
*
* utilapi.c - Error-checking utility file for 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: apsnap, dbsnap,
* dbsnapnew, insnap, insnapnew.
*
******************************************************************************
*
* Shell Scripts
*
* bldapp - Builds an application program.
* bldevm - Builds the Event Monitor program.
* bldmc - Builds a multi-connection application program.
* bldmt - Builds a multi-threaded program.
* bldrtn - Builds a routine (stored procedure and UDF) program.
* embprep - Precompiles and binds embedded SQL programs.
*
******************************************************************************
*
* Samples Design
*
* The C sample programs form an object-based design reflecting the
* component nature of DB2. Related samples demonstrate a specific level of
* database programming. Each level is identified by the first two characters
* of the sample name. Here are the levels:
*
* Identifier DB2 Level
*
* cl Client Level.
* in Instance Level.
* db Database Level.
* tb Table Level.
* ts Tablespace 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)
*
* autostore.c - How to use automatic storage capability for a database.
* 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.
* dbinline.sqc - How to use inline SQL Procedure Language
* 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.h - Header file for dbmcon1.sqc
* dbmcon1.sqc - Functions used in the multiple databases program
* dbmcon.
* dbmcon2.h - Header file for dbmcon2.sqc
* dbmcon2.sqc - Functions used in the multiple databases program
* dbmcon.
* dbupgrade.c - How to upgrade a database.
* dbpkg.sqc - How to work with packages.
* dbredirect.sqc - How to perform Redirected Restore of a database.
* dbrestore.sqc - How to restore a database from a backup.
* dbrollfwd.sqc - How to perform rollforward after restore of a
* database.
* dbsample.sqc - How to create a sample database.
* dbsnap.c - How to get a snapshot at database level.
* dbsnapnew.c - How to get a snapshot at database level (using API).
* dbstat.c - Provide database statistics about DB2 performance.
* dbthrds.sqc - How to use threads.
* dbuse.sqc - How to use database objects.
* getlogs.sqc - How to get customer view of diagnostic log file
* entries.
* ssv_backup_db.c - How to take database backup in an MPP environment.
* ssv_backup_tbsp.sqc - How to take tablespace in an MPP environment.
* ssv_db_cfg.c - How to update db cfg parameters in an MPP environment.
*
******************************************************************************
*
* Table Level (program files that deal with table objects in DB2)
*
* getmessage.sqc - How to get error message in the required locale with
* token replacement. The tokens can be programatically
* obtained by invoking Sqlaintp using JNI.
* globvarsupport.sqc - How to use global variables with DB2.
* implicitcasting.sqc- To demonstrate use of implicit casting.
* largerid.sqc - How to enable Large RIDs support on both new tables/
* tablespaces and existing tables/tablespaces.
* setintegrity.sqc - How to perform online SET INTEGRITY on a table.
* 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.
* tbident.sqc - How to use identity columns.
* tbinfo.sqc - How to get and set information at a table level.
* tbintrig.sqc - How to use INSTEAD OF triggers.
* tbload.sqc - How to load into a partitioned database.
* tbloadcursor.sqc - How to load data returned from a SELECT statement into
* a table using CURSOR method or REMOTEFETCH media method.
* 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.sqc - 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.
* tbrowcompress.sqc - How to perform row compression on a table.
* tbrunstats.sqc - 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 materialized query tables
* (summary tables).
* tbunion.sqc - How to insert through a UNION ALL view
*
******************************************************************************
*
* Tablespace Level (program files that deal with tablespace objects in DB2)
*
* tscreate.sqc - How to create/drop bufferpools and tablespaces.
*
******************************************************************************
*
* Data Type Level (programs that deal with data types)
*
* dtformat.sqc - How to load and import data format extensions.
* dtlob.sqc - How to read and write LOB data.
* 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
* spcreate_gv.db2 - CLP script to issue CREATE GLOBAL VARIABLE and
* 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.
* spclient.sqc - Client application that calls the stored procedures in
* spserver.sqc.
* spserver.sqc - Stored procedure functions built and run on the server
* spserver.exp - export file for spserver.
*
******************************************************************************
*
* 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.
* udfsrv.exp - Export file for udfsrv.
*
******************************************************************************
*
* Log Management User Exit samples
*
* db2uext2.cdisk - uses the platform system copy command to archive and
* retrieve database log files.
* db2uext2.ctape - uses system tape commands to archive and retrieve
* database log files.
* db2uext2.ctsm - uses Tivoli Storage Manager (TSM) APIs to archive and
* retrieve database log files.
* db2uext2.cxbsa - uses XBSA APIs to archive and retrieve database log
* files.
*
******************************************************************************
*
* Event Monitor samples
*
* evm.sqc - Demonstrates file, pipe, and table event monitors
*
******************************************************************************
*
* Other
*
* largevol.sqc - Extract large volumes of data from several queries
*
******************************************************************************