****************************************************************************** * (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/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 Linux 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 * ******************************************************************************