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 XML Samples
*
* The <install_path>/sqllib/samples/xml directory on UNIX and 
* <install_path>\sqllib\samples\xml directory on Windows contain 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 for UNIX
* and C:\Program Files\IBM for windows. 
*
* The DB2 9.7 sample code for XML is located in the following directory :
* <install_path>/sqllib/samples/xml directory on Unix and
* <install_path>\sqllib\samples\xml directory on Windows.
*
* This README is organized into DIRECTORY ROADMAP, GETTING XML SAMPLES UP 
* AND RUNNING, XML SAMPLES DESIGN OVERVIEW and DETAILS OF SAMPLES sections.
*
*******************************************************************************
*
*                        DIRECTORY ROADMAP
* 
* 1.xml/xquery : This directory contains samples for demonstrating the XQuery
*                features.
*                xquery/c contains C samples for XQuery.
*                xquery/cli contains CLI samples for XQuery.
                 xquery/clp contains command line processor samples for XQuery.
*                xquery/java/jdbc contains JDBC API samples for XQuery.
*                xquery/java/sqlj contains SQLj samples for XQuery.
*
* 2. xml/c   : contains the files for embedded SQL samples.
* 3. xml/cli : contains the files for CLI samples.
* 4. xml/clp : contains the files for CLP samples.
* 5. xml/java: contains the files for JAVA samples.
*              java/jdbc contains the files for JDBC API samples 
*              java/sqlj contains the files for SQLj samples.
* 6. xml/data: directory contains the data required for running these samples.
*              This directory contains the setup and clean up scripts for some of
*              the samples.
*
* For more details on the content of these directories, please refer to the
* the README file in the respective directories. 
* 
********************************************************************************
*
*               GETTING XML SAMPLES UP AND RUNNING
*
* WARNINGS
*  1. These steps gives an overview of building and running the samples. Please
*     read the README in corresponding directory for any specific considerations.
*
* SETUP:
*
*   1) Copy the files from corresponding  directory to a working 
*      directory and ensure that directory has write permission.
*
*   2) On Windows platform, all samples should be run and built in DB2 
*      Command Window. 
*      The DB2 command window is needed to execute the db2 specific commands. 
*      You can follow the step below to open DB2 command window.
*      From the Start Menu click Start --> Programs --> IBM DB2 --> 
*      <DB2  copy name> --> Command Line Tools --> Command Window. 
*
*   3) Start the database manager with the following command:
*      db2start
*
*   4) Create the sample database with the following command:
*      db2sampl -xml
*
*   5) Connect to the sample database with the following command:
*      db2 connect to sample
*
*   6) To build stored procedures and User defined functions, 
*      ensure that you have write permission on the 
*      <install_path>/sqllib/function directory on UNIX and
*      <install_path>\sqlib\function directory on WINDOWS. 
*
*   7) Change directory (CD) to the directory containing the files 
*      copied in step 1.
*
* BUILD AND RUN:
*    1. Some of the samples might need one or more of the data files at runtime.
*       The data files can be found in the xml/data directory. Please copy the
*       data files to your working directory before running the particular sample.
*       For more details on the data files required for a particular sample,
*       please refer the header section of the sample.
*             
*  To compile these samples, build scripts are provided.
*  The README file in each directory containing the actual samples provides the
*  details about how to compile the samples using the build script.
*
*  Here is the brief overview :
*  
*  C and CLI:
*
*  To create the executable for the sample:
* 
*    bldapp <sample name>
*  
*  where <sample name> is the name of the sample without any extension.
*
*  e.g. bldapp xmlschema
*
*  To run the sample:
*
*    xmlschema
*
*  JDBC:
*
*  To create the class file:
*  
*    javac <sample name>.java
*
*  where <sample name> is the name of the sample without any extension.
*
*  To run the sample file:
*
*    java <sample name>.class
*
*  where <sample name> is the name of the sample without any extension.
*
*   SQLj:
*
*  To create the class file:
*
*    bldsqlj <sample name> userid password [server name] [port name]
*
*  where <sample name> is the name of the sample without any extension.
*
*  To run the sample:
*
*    java <sample name>.class
*
*  where <sample name> is the name of the sample without any extension.
*
*
*******************************************************************************
*
*                 XML SAMPLES DESIGN OVERVIEW
*
* The XML samples can be functionally categorized into the following areas:
*
* Administration Samples
*
*   XML Schema Support 
*   Schema registration and validation of XML document as per the schema 
*
*   XML Values Index Support 
*   Indexes on different node types of XML value 
*  
*   Utility Support for XML
*   Import/export/runstats/db2look/db2batch support for XML data type 
*
* Application Development Samples
*
*   XML Insert/Update/Delete 
*   Inserting the new XML value in XML type column, Updating and Deleting the
*   existing values.
*  
*   XML Parse/Validate/Serialize Support 
*   Implicit/explicit parsing of compatible data types.
*
*   Hybrid Use of SQL and XQuery 
*   SQL/XML functions like XMLTable, XMLQuery and XMLExists.
*   
*   XML in Stored Procedures
*   Stored procedure with XML data type parameter 
*   
*   XML Decomposition Support 
*   Decomposition of XML document as per annnotated schema 
*
* XQuery Samples
*
*   Axises, FLWOR expression. SQL/XML with XQuery and nested XQueries
*
********************************************************************************
*
*                        DETAILS OF SAMPLES
*
* In order to help provide valid, usable and comprehensive XML samples, the
* samples are based on specific usage scenarios, or they demonstrate a
* particular feature or API. These samples are derived from a purchase order
* scenario. Besides the purchase order scenario, a bookstore scenario is used
* to demonstrate the decomposition functionality.
*
* A. Usage Scenarios
*    
*    1. Consider a user who needs to insert an XML type value into the table.
*       The user would like to ensure that the XML value conforms to a
*       deterministic XML schema. To do so, the user can register the XML
*       schema to the database and use that to validate the XML document
*       prior to inserting it into the table.
*        
*       Samples: xmlschema.*
*
*    2. Purchase order XML document contains detailed information about all
*       the orders. It will also have the detail of the customer with each
*       order. To avoid infomation, such as address, repeating for each
*       purchase order from the same customer, user can store this data into
*       the relational table having XML column.
*
*       Samples: xmltotable.*
*                
*    3. A bookstore owner has some XML documents which contains descriptive
*       information about a book which he has for sale. The owner needs to
*       store these details in a relational table for easy retrival of
*       information. He/She can easily do it using the Decomposition function. 
*        
*       Samples: xmldecomposition.*
*      
*    4. User's purchase order database uses relational tables to store the
*       orders of different customers. To get all the purchase order data
*       filtered by date or status, a lot of joins on relational tables are
*       required. These joins create a massive amount of redundant data as the 
*       intermediate results. The same data can be returned as an XML object
*       to the application. The XML object can be created using the XML
*       constructor functions on the server side.
*
*       Samples: reltoxmltype.*
*                reltoxmldoc.*
*
* B. Features 
*   
*    1. XML Document Insert/Update/Delete:
*       These samples demonstrate different ways of inserting/updating/deleting
*       an XML document in a table having XML column.
*
*       Samples: xmlinsert.*
*                xmlupdel.*
*                xmlread.*
*
*    2. Stored Procedure parameter of XML type:
*       These samples demonstrate the XML parameter type for stored procedure. 
*
*       Samples: simple_xmlproc.* 
*
*    3. XML Value Index:
*       These samples demonstrate the new index features on XML document,
*       the different kinds of indexes for XML columns, and how to put the
*       constraints on XML document using an index.
*
*       Samples: xmlindex.*
*                xmlconst.*
*
*    4. Import/Export:
*       These samples demonstrate the new import/export command for XML data,
*       and the API changes for import/export commands.
*
*       Samples: impexpxml.*
*                       
*    5. XML Runstats:
*       These samples demonstrate how to perform RUNSTATS on a TABLE containing
*       one or more XML columns. In DB2 Viper, RUNSTATS collects statistics for
*       XML columns and associated XML indexes along with relational columns.
*       Using these statistics the optimizers perform cost estimation for
*       different execution plans. 
*
*       Samples: xmlrunstats.*
*                 
*    6. db2look support for XML:
*       These samples demonstrate how db2look generates the DDL statements for
*       the tables having XML columns.
*
*       Samples: xmldb2look.*
*
*    7. db2batch support for XML:
*        These samples demonstrate the db2batch functionality when the
*        query statements in the batch has XML related queries.
*
*       Samples: xmldb2batch.*
*
*    8. XQuery Support:
*       These sample demonstrate the XQuery support of DB2. For more details,
*       please refer to the README in xquery directory.
*
********************************************************************************