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