****************************************************************************** * Licensed Materials * Property of IBM * * Governed under the terms of the International * License Agreement for Non-Warranted Sample Code. * * � COPYRIGHT International Business Machines Corp. 2007 * All Rights Reserved. * * US Government Users Restricted Rights - Use, duplication or * disclosure restricted by GSA ADP Schedule Contract with IBM Corp. * ****************************************************************************** * * README for PHP Samples * * This README file describes the PHP sample files. It is recommended that * you copy the files into a working directory prior to running the * sample scripts. * * DB2 specific samples are writen for and tested on a DB2 v9+. * * There are samples with in this set which have been designed, written for * and tested with both DB2 v9+ and Informix 10+. These generic samples are * denoted by "_generic" tagged on the end of the file name before the file * type denotation. * * 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. * ****************************************************************************** * * Setup * * 1) Copy the files into your working directory. * These samples can be run from: * - A command line on a computer that has PHP cli installed * - Called as a webpage from a HTTP/web server capable of interpreting * PHP server-side scripts * * The latest version of PHP can be downloaded from here: * http://www.php.net/downloads.php * Most any commonly used HTTP/web server can be configured to use PHP * server-side scripts. See the PHP installation instruction under you * operating system for instructions on how to do this on more common * HTTP/web server: * http://www.php.net/manual/install.php * * 2) Ensure you have the appropriate database driver for the samples you wish * to run. Database driver are available to be installed with the DB2 Data * Server Client if PHP is installed before the instillation of the DB2 * Data Server Client also you can download the drivers directly. * * - "*_DB2.php" samples require the IBM_DB2 driver to be installed * The latest version of the driver is available here: * http://pecl.php.net/package/ibm_db2 * The latest compiled version for windows is available here: * http://pecl4win.php.net/ext.php/php_pdo_ibm.dll * * - "*_PDO.php" samples require the PDO and PDO_IBM drivers to be * installed * The latest version of the driver is available here: * ::PDO * http://pecl.php.net/package/PDO * ::PDO_IBM * http://pecl.php.net/package/PDO_IBM * The latest compiled version for windows is available here: * ::PDO * http://pecl4win.php.net/ext.php/php_pdo.dll * ::PDO_IBM * http://pecl4win.php.net/ext.php/php_pdo_ibm.dll * * For PHP install and setup information see: * http://www.php.net/manual/ * * To build PHP and extension from scratch on Windows see: * http://www.php.net/manual/install.windows.building.php * * 3) Create a working database * - For Xml DB2 samples you need to use the Xml sample * database which can be created using the following * command: * * db2sampl -xml * * WARNINGS * 1. These steps gives an overview of building and running the * samples. Please read the README in corresponding directory * for any specific considerations. * * On a Windows system this command needs to be run from a * db2 command window: * - From the Start Menu click Start --> Programs --> * IBM DB2 --> <DB2 copy name> --> Command Line Tools * --> Command Window. * * - Other non-Xml samples just require a database to run against this * could be created using ether of the following command: * * db2sampl * * or * * db2 create database <Database Name> * Where <Database Name> is the name of the database. * These samples use the database of the name "SAMPLE" * by default if you chose another name it is recommended * that you update the "PHPSampleConfig.cfg" file. * * On a Windows system this command needs to be run from a * db2 command window: * - From the Start Menu click Start --> Programs --> * IBM DB2 --> <DB2 copy name> --> Command Line Tools * --> Command Window. * * (Optional) * 3) Configure the file "PHPSampleConfig.cfg" * By configuring this file ahead of time each individual sample will * have the general information it needs to run. These setting can be * overridden at any time while running any sample. * * Options * db="<Database Connection String>" * u="<User Name>" * p="<User Password>" * Schema="<The Schema to run under>" * ****************************************************************************** * * For information on developing PHP applications, see the Application * Development Guide. * * For information on using SQL statements, see the SQL Reference. * * For information on obtaining the latest version of PHP, visit: * http://www.php.net * ****************************************************************************** * * Code Notes * -- Thing you might want to know -- * * UtilIOHelper.php * - This File and the IO_Helper class parses any Input * that the sample is feed in and sanitises any output * that need to be sent to the screen. Below are the most * common element of the IO_Helper that you will see outside * of the class. Please see the �UtilIOHelper_Def� * for a complete class definition. * * '{$this->schema}' * - This is how you will most often see this * variable embedded with in an SQL statement. * It will contain a Schema Name followed by a * period or It will contain nothing. The * Schema Name is parsed from the values of * the schema option flag that can be passed * in through the command line, web * browsers GET, POST or the PHPSampleConfig * file. * * display_Xml_Parsed_Struct * - This will take a string containing an * unformatted XML document and format it * in to a XML based tree which is returned * as a string. This function also has the * ability to add a Start of line character * to the beginning of each line. * * format_Output * - This function is used to output any * information to the screen. If the program * is running in a console the output is * passed directly to the screen otherwise * the output is sanitized for display with * in a web browser. * * UtilConnection_DB2.php * UtilConnection_PDO.php * - These files and the DB2_Connection and PDO_Connection * classes will be extended by most Samples and use some of * the basic functionality inside. These classes take care * of basic operation such as forming connections and commit * and rollback of transactions. * Please see: * 'UtilConnection_DB2_Def' * or * 'UtilConnection_PDO_Def' * for a complete classes definition. * * ****************************************************************************** * * Common file Descriptions * * The following are the common files for PHP samples. For more * information on these files, refer to the program source files. * ****************************************************************************** * * Common files * * README - this file * * UtilConnection_DB2_Def - A class definition for UtilConnection_DB2.php * * UtilConnection_PDO_Def - A class definition for UtilConnection_PDO.php * * UtilIOHelper_Def - A class definition for UtilIOHelper.php * * PHPSampleConfig.cfg - A configuration file that lets you set * commonly used connection parameters that * will be parsed by the IO_Helper class in * util_IO_Helper.php for use in the samples. * All information in here can be overridden * when running the samples. * ****************************************************************************** * * Data files * * photo.gif * resume.txt * ****************************************************************************** * Samples Files * * The PHP sample programs form an object-based design reflecting the * component nature of DB2. Related samples demonstrate a specific level of * database programming. * * PHP Sample File Naming Schema * .-'_generic'-. * >>--| Identifier || Short Sample Name |+----------++------------+.php * +--'_DB2'--+ * '--'_PDO'--' * * Identifier - denotes the group that this sample or file is * classified under * * Posible * Identifiers Definition * * Db A Database Level sample * Tbl A Table Level sample * Dt Data Types Level sample * Xml XML samples * Util A Utility file used by the PHP samples * * Short Sample Name - A short descriptive name to identify the sample * * Database Driver - This denotes what driver if any the sample is using. * - The IBM_DB2 driver is identified by '_DB2' * - The PDO_IBM driver is identified by '_PDO' * * Generic Sample - This specifies a sample which is generic and can be * run on both DB2 databases and Informix Databases. * ****************************************************************************** * * Utility files * * * UtilConnection_DB2.php - Handles General IBM_DB2 Connection * for IBM_DB2 driver samples * - See UtilConnection_DB2_Def * for Class definition details * and overview. * * UtilConnection_PDO.php - Handles General PDO Connection * for PDO driver samples * - See UtilConnection_PDO_Def * for Class definition details * and overview. * * UtilIOHelper.php - Handles General IO * - See UtilIOHelper_Def * for Class definition details * and overview. * * *** Sample Level Table Setup *** * * These utility files are used by some sample to create table and * populate them with information used when running the sample and * then to remove those table when complete. * * - See README_UtilTableSetup_deff for Class definition details and * overview. * * * UtilTableSetup_Xml.php - Sets up tables used in XML Samples * * UtilTableSetup_XmlDecomposition.php * - Sets up tables used in the * XML_Decomposition sample * * UtilTableSetup_LOB.php * * UtilTableSetup_Staff.php * ****************************************************************************** * * Database Level. * * DbAuthorities_DB2.php * DbAuthorities_PDO.php - How to grant/display/revoke authorities * at the database level * ****************************************************************************** * * Data Type Level. * * DtInfo_DB2.php * DtInfo_PDO.php - How to get information about data types. * * DtLOB_DB2.php * DtLOB_PDO_generic.php - How to read and write LOB data * * DtUDT_DB2.php * DtUDT_PDO.php - How to create, use, and drop user-defined * distinct types. * ****************************************************************************** * * Table Level. * * TblIdentity_Columns_DB2.php * TblIdentity_Columns_PDO.php - How to use identity columns * * TblSelect_DB2.php * TblSelect_PDO.php - How to select from each of: insert, * update, delete. * * TblConstraints_DB2.php * TblConstraints_PDO.php - How to work with table constraints * * TblTrigger_DB2.php. * TblTrigger_PDO.php - How to use a trigger on a table * * TblUnion_DB2.php * TblUnion_PDO.php - How to insert through a UNION ALL view. * ****************************************************************************** * * XML samples * * * **************************************************************************** * * * * * PDO and XQuery * * * * * * PDO v1.0.3 and earlier contain a documented parsing bug which interferes * * * with XQuery statement. This is in relation to how PDO uses ':<name>' in * * * SQL statement to act as a binding point, which is equivalent to '?' * * * character also used in PDO and most other database drivers. If you * * * require or wish to use XQuery statements it is recommended that you use * * * the IBM_DB2 PHP Driver or upgrade your version of PDO. * * * * * **************************************************************************** * * XmlDecomposition_DB2.php - Decompose data stored in an XML file and * insert the data into tables * PREREQUISITE:This sample require bookdetail.xml, * bookdetail.xsd files at run time. Copy these files * to your working directory before running the sample. * These file can be found in * <install_path>\sqllib/samples/xml/data directory. * * XmlFlwor_DB2.php - Use the XQuery FLWOR expression * * XmlIndex_DB2.php - Create an index and use it in an XQuery * * XmlInsert_DB2.php - Insert an XML document into a column of * XML data type * PREREQUISITE: copy the files cust1023.xml to working * directory before running the sample. This file can be * found in xml/data directory. * * XmlRead_DB2.php - Read XML data stored in tables * * XmlRelToXmlDOC_DB2.php - Create and XML document directly from data * stored in relational tables using SQL/XML * publishing sunctions * * XmlRelToXmlType_DB2.php - Create an XML document from relational and * XML data using SQL/XML publishing functions * * XmlRunstats.php - How to perform RUNSTATS on a table * containing XML type columns. * * XmlSchemas_DB2.php - Register the XML schema to the database * and use the registered schema to validate * and insert and XML document * PREREQUISITE: copy product.xsd, order.xsd, * customer.xsd, header.xsd Schema files, order.xml XML * document from <install_path>\sqllib/samples/xml/data * directory to working directory. * * XmlSQLXQuery_DB2.php - Use SQL/XML queries * * XmlUniqueIndexes_DB2.php - Create and index with UNIQUE and VARCHAR * length constraints * * XmlUpAndDel_DB2.php - Update and delete XML documents in the * tables * PREREQUISITE: copy the files cust1021.xml, cust1022.xml and * cust1023.xml to working directory before running the * sample. These files can be found in * <install_path>\sqllib/samples/xml/data directory. * * XmltoTable_DB2.php - Insert the data from an XML document into * relational tables using SQL/XML * PREREQUISITE: copy purchaseorder.xml XML document * from <install_path>\sqllib/samples/xml/data * directory to the working directory. * * XmlXPath_DB2.php - Run simple XPath queries * * XmlXQuery_DB2.php - Executing nested XQuery FLWOR expression * ******************************************************************************