# XML Extender administration wizard help

# Contents

Connecting to a database

- Fields and controls
- Tasks
- Connecting to the database
- Switching to another database

  Using the XML Extender Administration LaunchPad

- Fields and controls
- Tasks

  Enabling or disabling a database

- Task: Enabling a database
- Task: Disabling a database

  Importing DTDs

- Fields and controls
- Task: Importing a DTD

  Working with DAD files

- Fields and controls
- Specify a DAD - first step for all types
- Select validation - step 2 for all types
- Side tables- step 3 for XML column type
- Specify text- step 3 for SQL mapping or RDB node mapping type
- Specify SQL statement- step 4 for SQL mapping type
- Map SQL- step 5 for SQL mapping type
- Map RDB nodes- step 4 for RDB node mapping type
- Save a DAD- last step for all types
- Tasks
- Creating or editing a DAD for XML columns
- Creating or editing a DAD for XML collections

  Working with XML columns

- Fields and controls
- Select a task (for columns)
- Add an XML column
- Enable an XML column
- Disable an XML column
- Tasks
- Adding an XML column
- Enabling an XML column
- Disabling an XML column

  Working with XML collections

- Fields and controls
- Select a task (for collections)
- Enable an XML collection
- Disable an XML collection
- Tasks
- Enabling an XML collection
- Disabling an XML collection

  # Connecting to a database

  From this wizard, you can connect to the database that contains or will contain XML data.

  ## Fields and controls

  Address
    Type the name of the JDBC database you want to connect to or select an address from the list. The wizard performs real-time tasks in that database. If you select from the list, the user ID and JDBC driver last associated with this address are displayed in the following fields. This field is mandatory. The address has the following syntax:

    |For stand-alone configurations (recommended):

        jdbc:db2:database_name

    Where:

    database_name
      The database to which you are connecting and storing XML documents.

    Example:

        jdbc:db2:sales_db

    For network configurations:

        jdbc:db2://|host:port_number/database_name

    Where:

    |host
      |Is the name of the server where the XML Extender is located.

    port_number
      The port number used to connect to the server. To determine the port number, enter the following command from the DB2 command line at the server machine:

          db2jstrt port#

    database_name
      The database to which you are connecting and storing XML documents.

    Example:

        jdbc:db2://host1.ibm.com/sales_db

  User ID
    Type or verify the user ID you use to access the database. This field is mandatory.

  Password
    Type the password you use to access the database. This field is mandatory.

  JDBC Driver
    Type or verify the location of the driver for the database. This field is mandatory. The driver should have one of the following values:

    |For stand-alone configurations (default):

        COM.ibm.db2.jdbc.app.DB2Driver

    For network configurations:

        COM.ibm.db2.jdbc.net.DB2Driver

  Finish
    Completes the process of logging on to a database and opens the LaunchPad.

  Cancel
    Cancels the wizard.

  ## Tasks

  ### Connecting to the database

  When you start the XML Extender Administration Wizard, the Logon window opens and you connect to a database.

  1. In the Address field, enter the fully-qualified JDBC address to the IBM DB2 UDB data source to which you are connecting.
  2. In the User ID and Password fields, type or verify the DB2 user ID and password for the database to which you are connecting.
  3. In the JDBC Driver field, type or verify the JDBC driver name for the specified address.
  4. Click Finish to connect to the database and advance to the LaunchPad.

  ### Switching to another database

  1. From the LaunchPad, click Switch Database.
  2. In the Address field, enter the fully-qualified JDBC address to the IBM DB2 UDB data source to which you are connecting.
  3. In the User ID and Password fields, enter or verify the DB2 user ID and password for the database to which you are connecting.
  4. In the JDBC Driver field, type or verify the JDBC driver name for the specified address.
  5. Click Finish to connect to the new database and return to the LaunchPad. XML Extender disconnects you from the original database and connects you to the new database.

  # Using the XML Extender Administration LaunchPad

  The XML Extender Administration Wizard LaunchPad (the LaunchPad), provides access to wizards that help you complete administration tasks, such as enabling a database, editing a data access definition (DAD) file, and enabling XML columns or collections. Select a task name to launch the wizard for that task.

  ## Fields and controls

  Switch Database
    Opens a window for logging on to a specific database. To store or access XML documents, you have to be connected to a database. After you log on to a database, you can switch to another database from the LaunchPad.

  Enable Database/Disable Database
    Enables or disables a database for XML Extender. This button is a toggle and changes depending on whether the database is enabled. To enable the database, XML Extender creates XML Extender UDTs, UDFs, a DTD reference table for storing DTDs and information about each DTD, and a usage table for storing common information for each enabled column. To disable a database, XML Extender drops UDTs, UDFs, the DTD reference table, and the XML usage table. You must disable all XML columns and collections before you attempt to disable a database.

  Import a DTD
    Opens the Import a DTD window for importing an existing Document Type Definition (DTD) file into the DTD repository of the current database. The DTD allows you to validate XML data in an XML column or in an XML collection. It is optional for XML column data but required for XML collection data. |

  |Edit DAD
    |Opens the Specify a DAD window for editing an existing Document Access |Definition (DAD) file or creating a new DAD. The DAD defines how XML |data is collected and stored in DB2; it allows you to define the |attributes and key elements of your data so that it can be searched. |The XML column DAD maps the XML column to side tables for indexing. The |XML collection DAD maps DB2 data to the XML document structure.

  Work with XML Columns
    |Opens a window for adding an XML column, enabling an XML column, or |disabling an XML column in a table. You store and access XML data by |enabling a DB2 column for XML data types.

  Work with XML Collections
    Opens a window for enabling or disabling an XML collection in a database. In a collection, you store and access XML data by using a set of relational tables.

  ## Tasks

  From the LaunchPad, you can complete the following XML Extender tasks:

  - Log on to a database or switch to a different database
  - Enable or disable database
  - Import a DTD
  - |Edit DAD
  - Work with XML columns
  - Work with XML collections

  # Enabling or disabling a database

  From this wizard, you can enable or disable a database. Enabling a database creates the UDTs, UDFs, stored procedures, and administration support tables required when using XML Extender. You must enable the database to store, compose, or decompose XML documents in the database. Disabling the database drops the UDTs, UDFs, stored procedures, and administration support tables.

  ## Task: Enabling a database

  Click Enable Database from the LaunchPad to enable the current database. If a database is already enabled, Disable Database is available.

  When the database is enabled, you are returned to the LaunchPad.

  ## Task: Disabling a database

  Click Disable Database from the LaunchPad to disable the current database. If a database is not currently enabled, Enable Database is available.

  When the database is disabled, you are returned to the LaunchPad.

  # Importing DTDs

  From this wizard, you can import a DTD to validate an XML document that is stored in an XML column, or that is being composed from DB2 data in an XML collection.

  ## Fields and controls

  DTD file name
    Type the DTD file name or click ... to browse a list of available DTDs. This field is mandatory.

  DTD ID
    Type the name of the DTD ID. The ID associates the DTD with the XML document DAD and specifies its location. The DTD ID is an identifier for the DTD and can be the path specifying the location of the DTD on the local system. The DTD ID must match the value that is specified in the DAD file for the <DTDID> element. This field is mandatory.

  Author
    Type the name of the DTD author. The name is automatically displayed if it is specified in the DTD repository. This field is optional.

  Finish
    Inserts the DTD into the DTD repository and returns you to the LaunchPad.

  Cancel
    Cancels the wizard and returns you to the LaunchPad.

  ## Task: Importing a DTD

  1. Click Import a DTD from the LaunchPad to import an existing DTD file into the DTD repository of the current database. The Import a DTD wizard is displayed.
  2. Type the DTD file name in the DTD file name field or click ... to browse for an existing DTD file.
  3. Type the DTD ID in the DTD ID field.
  4. Optionally, type the name of the author of the DTD in the Author field.

     The XML Extender automatically displays the author's name if it is specified in the DTD.

  5. Click Finish to insert the DTD into the DTD repository table, DB2XML.DTD_REF, and return to the LaunchPad.

  # Working with DAD files

  From this wizard, you can create or edit DAD files to define how XML documents are used with DB2. DAD files are used to:

  - Store XML documents in columns and define side tables that are indexed for fast structural search.
  - Compose XML documents from one or more DB2 tables that are defined in an XML collection.
  - Decompose XML documents into one or more DB2 tables that are defined in an XML collection.

  Refer to DB2 XML Extender Administration and Programming to learn more about these techniques.

  ## Fields and controls

  ### Specify a DAD - first step for all types

  File name
    Type an existing DAD file name or click ... to browse for an existing DAD file name. If you are creating a new DAD, leave the field blank. If the DAD file exists, the type of DAD file is displayed in Type and Next is selectable.

  Type
    If you are creating a new DAD, select one of the following types of DAD files:
    - XML column to specify how documents stored in a column are to be indexed
    - XML collection SQL mapping to provide mapping between relational data and XML documents through a single SQL statement
    - XML collection RDB_node mapping to provide node definitions for tables, columns, and conditions for defining how the XML data is stored

  Next
    Goes to the next step: Select validation.

  Finish
    Enabled when you finish creating or modifying a DAD file. Completes the process and returns you to the LaunchPad.

  Cancel
    Cancels the wizard and returns you to the LaunchPad.

  ### Select validation - step 2 for all types

  Validate XML documents with the DTD
    Select to validate the XML documents. With valid documents, you can perform structured searches on your data. Your documents are validated against the DTD specified in the DAD file. You should validate XML data before inserting data into DB2 because you cannot validate data already inserted into DB2.

  DTD ID
    Type the name of the DTD or select the name from the list of existing DTDs. If you have not imported any DTDs into the DTD repository for your database, you cannot validate your XML documents.

  |Do NOT validate
    Select to continue without validating your XML documents.

  Back
    Goes to the previous step: Specify a DAD window.

  Next
    Goes to the next step. Opens the Manage side tables window if you are working with XML columns, the Specify SQL statement widow if you are working with XML collection SQL mapping, or the Specify text window if you are working with XML collection RDB_node mapping.

  Finish
    Enabled when you finish creating or modifying a DAD file. Completes the process and returns you to the LaunchPad.

  Cancel
    Cancels the wizard and returns you to the LaunchPad.

  ### Side tables- step 3 for XML column type

  |List of existing tables and columns
    |This table contains a list of side tables that are to be created when an |XML column using this DAD file is created.. You can select the |name of an existing table and column that you want to change or remove, or |enter a new name in the fields below.

  Table name
    Type the name for a new side table containing the column. If you selected a column from the list, the name of its table appears for you to modify. This field is mandatory. Example:

        ORDER_SIDE_TAB

  Column name
    Type the name of the column. If you selected a name from the list of columns, the column name appears for you to modify. This field is mandatory. Example:

        CUSTOMER_NAME

  Type
    Select or change the type of column, such as DATE, CHAR, INTEGER, or VARCHAR. This field is mandatory.

  Length
    If you selected VARCHAR, type or change the maximum number of characters for the length of the column. This field is only enabled if the type is VARCHAR. Example:

        30

  Path
    Type or change the location path of an element or attribute. This field is mandatory. Example:

        /ORDER/CUSTOMER/NAME

  Multiple occur
    Select this check box to indicate whether the element or the column attribute can be used more than once or only once in a document. Select the box for multiple occurrence; leave the box unselected to indicate no multiple occurrence.

  Add
    Saves the table or column with the details you specified and allows you to continue to add, modify, or delete a table or column.

  Change
    Saves changes that you make to the Table name, Column name, Type, Length, Path, or Multiple occur fields. When you change the name of a table or column, the old object is dropped from the list and the new one added.

  Remove
    Removes the currently highlighted item from the list.

  Back
    Goes to the previous step: Select Validation.

  Next
    Goes to the next step: Save a DAD.

  Finish
    Enabled when you finish creating or modifying a DAD file. Completes the process and returns you to the LaunchPad.

  Cancel
    Cancels the wizard and returns you to the LaunchPad.

  ### Specify text- step 3 for SQL mapping or RDB node mapping type

  Prolog
    Type a prolog name. If you are editing an existing DAD, the name is displayed. The name should be in the format

        <?xml version="1.0" ?>

    This field is mandatory.

  Doctype
    Type the type of XML document. If you are editing an existing DAD, the document type is displayed. This field is mandatory. Example:

        <!DOCTYPE Order SYSTEM "C:\dxx\samples\dtd\getstart.dtd">

  Back
    Goes to the previous step: Select Validation.

  Next
    Goes to the next step: Map RDB nodes, if the type is RDB node mapping, or Specify SQL statement if the type is SQL mapping

  Finish
    Enabled when you finish creating or modifying a DAD file. Completes the process and returns you to the LaunchPad.

  Cancel
    Cancels the wizard and returns you to the LaunchPad.

  ### Specify SQL statement- step 4 for SQL mapping type

  SQL statement
    Type a SQL SELECT statement. If you are editing an existing DAD file, the SQL statement is displayed. The statement maps the columns of the SELECT clause to XML elements or attributes in the XML document. The FROM clause defines the tables containing the data. The WHERE clause indicates the join and search conditions. All the tables in the collection have to be able to be joined by one SELECT statement. This field is mandatory. Example:

        SELECT o.order_key, customer_name, customer_email, p.part_key, color, quantity,
        price, tax, ship_id, date, mode from order_tab o, part_tab p,
        table (select substr(char(timestamp(generate_unique())),16)
          as ship_id, date, mode, part_key from ship_tab) s
              WHERE o.order_key = 1 and
                    p.price > 20000 and
                    p.order_key = o.order_key and
                    s.part_key = p.part_key
              ORDER BY order_key, part_key, ship_id

    The SQL statement uses the following guidelines:

    - Columns are specified in top-down order, by the hierarchy of the XML document structure.
    - The columns for an entity are grouped together, and each group has an object ID column.
    - The object ID column is the first column in each group.
    - For tables that do not use a single key conditional column, use the generate_unique DB2 built-in function to generate the column.
    - The object ID columns are then listed in top-down order in an ORDER BY statements. The columns in ORDER BY should not be qualified by any schema and table name and should match the column names in the SELECT clause.

  Test SQL
    Tests the validity of the SQL statement. If the statement is valid, sample results are shown in the Sample results field. If the statement is not valid, an error message asks you to correct the statement and try again.

  Sample results
    Shows the sample results of testing your SQL statement if the statement is valid. This field is read only.

  Back
    Goes to the previous step: Select validation.

  Next
    Goes to the next step: Map SQL.

  Finish
    Enabled when you finish creating or modifying a DAD file. Completes the process and returns you to the LaunchPad.

  Cancel
    Cancels the wizard and returns you to the LaunchPad.

  ### Map SQL- step 5 for SQL mapping type

  DAD map
    Select a node from the displayed DAD map to map from. You can map the elements and attributes in the XML document to element and attribute nodes that correspond to DB2 data. The nodes provide the path from the XML data to the DB2 data. Select a node to enable New Element. Selecting a node causes the appropriate fields to appear in the Details group box.

  Node type
    Select a node type from the list of types that are valid at this point in the map. Depending on the type of node you select, different fields are displayed in the Details group box. This field is mandatory.

    Element
      Represents an XML element defined in the DTD associated with the XML document and used to associate the XML element with a column in a DB2 table. An element node can have attribute nodes, child element nodes, or text nodes. A bottom-level node has a text node and column name associated with it in the tree view.

    Attribute
      Represents an XML attribute defined in the DTD associated with the XML document and used to associate the XML attribute with a column in a DB2 table. An attribute node can have a text node and has a column name associated with it in the tree view.

    Text
      Specifies text content for an element node. A text node has a column name associated with it in the tree view.

  Node name
    Type the node name. This field is mandatory. Example:

        Order

  Column
    If you selected Attribute, Element, or Text as the node type, select a column name. This field is mandatory. If you specify Column as the node type, you can only select a column that already exists in your DB2 database. Example:

        Customer_Name

  Add
    Adds the appropriate label to the empty element currently being added in the tree structure.

  Change
    Makes the changes to the highlighted node. You can select the node again or another node and make further modifications.

  Remove
    Removes the currently highlighted element or attribute.

  New Element
    Creates a new node by clearing the fields in the Details group box, appends an empty element below the currently highlighted one in the tree structure, and highlights the new empty element.

  Back
    Goes the previous step: Specify SQL statement.

  Next
    Goes to the next step: Save a DAD.

  Finish
    Enabled when you finish creating or modifying a DAD file. Completes the process and returns you to the LaunchPad.

  Cancel
    Cancels the wizard and returns you to the LaunchPad.

  ### Map RDB nodes- step 4 for RDB node mapping type

  DAD map
    Select a node from the displayed DAD map to map from. You map the elements and attributes in the XML document to element and attribute nodes that correspond to DB2 data. The nodes provide the path from the XML data to the DB2 data. They indicate which table and which column has the data and under which condition you can get the data. Select a node to enable New Element. Selecting a node causes the appropriate fields to appear in the Details group box.

  Node type
    Select a node type from the list of types that are valid at this point in the map. Depending on the type of node you select, different fields are displayed in the Details group box. The fields could be for Element, Attribute, Text, Table, Column, or Condition, depending on what you selected in the DAD map. This field is mandatory.

    Element
      Represents an XML element defined in the DTD associated with the XML document and used to associate the XML element with a column in a DB2 table. An element node can have attribute nodes, child element nodes, text nodes, table nodes, or condition nodes. A root element has table nodes to specify all tables that are used to generate XML documents and a condition node that is used to connect the tables. This field is mandatory. Example:

          element_node name="Order"

    Attribute
      Represents an XML attribute node defined in the DTD associated with the XML document and used to associate the XML attribute with a column in a DB2 table. An attribute node can have a text node and has a column name associated with it in the DAD map. Data resides in the attribute node and text node of each element. This field is mandatory. Example:

          attribute_node name="key"

      |

    |Table
      |Represents the table that is associated with the text node or attribute |node content. It specifies the name of a DB2 table in which the content |of the text node or attribute node will be either stored in or retrieved |from. Example:

          |table_node name=order_tab

      |

    |Column
      |Represents the column that contains the content of the text node or |attribute node. It specifies the name of a DB2 table column in which |the content of the text node or attribute node will be either stored in or |retrieved from. Example:

          |column name="order_key"

  Node name
    Type the name of an element or attribute. This field is mandatory. Example:

        element_node name="Price"

  Text
    Indicates the text content of an element and the column data in a relational table for bottom-level element nodes. Contains a table element, column element, and for the root node, a condition element.

  Table name
    The name of the table containing the column. Example:

        table name="order_tab"
        table name="part_tab"
        table name="ship_tab"

  Table key
    The primary key for a table, consisting of a single column or multiple columns (composite key). The key is used to tie tables together in a collection. Example of composite key:

        table name="part_tab" key="part_key, price"

  Column
    Name of the column that contains the data for the element text and to which the element and attribute are mapped. Example:

        column name="order_key" type="integer"

  Condition
    In root elements, indicates the way to join XML collection tables. In lower-level elements, indicates the criteria for selecting XML data with values of "=", "<", ">", or "LIKE". Example of condition for rootl element:

        order_tab.order_key = part_tab.order_key AND
        part_tabe.part_key = ship_tab.part._key

    Example for criteria for selecting XML data:

        price > 2500.00

  Add
    Adds the appropriate label to the empty element currently being added in the tree structure.

  Change
    Makes changes to the highlighted node. You can select the node again or another node and make further modifications.

  Remove
    Removes the currently highlighted element.

  New Element
    Creates a new node by clearing the fields in the Details group box, appends an empty element below the currently highlighted one in the tree structure, and highlights the new empty element.

  Back
    Goes the previous step: Specify text.

  Next
    Goes the next window: Save a DAD.

  Finish
    Enabled when you finish creating or modifying a DAD file. Completes the process and returns you to the LaunchPad.

  Cancel
    Cancels the wizard and returns you to the LaunchPad.

  ### Save a DAD- last step for all types

  File name
    Type the file name for the modified or new DAD you want to save or click ... to open the local file browser window for you to select the saving location for the DAD. This field is mandatory.

  Back
    Goes to the previous step.

  Finish
    Saves the DAD file and returns you to the LaunchPad.

  Cancel
    Cancels the wizard and returns you to the LaunchPad.

  ## Tasks

  ### Creating or editing a DAD for XML columns

  When you create a DAD for an XML column, you specify the data type of the XML document and define side tables used for indexing.

  1. |Click Edit DAD from the LaunchPad to edit or create an |XML DAD file. The Work with DAD files wizard opens and displays the |Specify a DAD window.
  2. Choose whether to edit an existing DAD file or to create a new DAD file.
     - To edit an existing DAD:
       1. Click ... to browse for an existing DAD file in the list, or type the DAD file name into the File name field.
       2. Verify that the wizard recognizes the specified DAD file.
          - If the wizard recognizes the specified DAD file, Next is selectable, and XML column is displayed in the Type field.
          - If the wizard does not recognize the specified DAD file, Next is not selectable. Either retype the DAD file name into the File name field, or click ... to browse again for an existing DAD file. Continue until Next is selectable.
       3. Click Next.
     - To create a new DAD:
       1. Leave the File name field blank.
       2. From the Type list, click XML column.
       3. Click Next.
  3. Choose whether to validate your XML documents with a DTD from the Select Validation window.
     - To validate:
       1. Click Validate XML documents with the DTD.
       2. Select the DTD to be used for validation from the DTD ID list.

       If you have not imported any DTDs into the DTD repository for your database, you cannot validate your XML documents.

     - Click |Do NOT validate to continue without validating your XML documents.
  4. Click Next.
  5. Choose whether to add a new side table, edit an existing side table, or remove an existing side table from the Side tables window.
     - To add a new side table or side table column:

       To add a new side table, you define the columns in the table. Complete the following steps for each column in a side table.

       1. Complete the fields of the Details box of the Side tables window.
          1. Table name: Type the name of the table containing the column.
          2. Column name: Type the name of the column.
          3. Type: Select the type of the column from the list.
          4. Length (VARCHAR type only): Type the maximum number of VARCHAR characters.
          5. Path: Type the location of the element or attribute.
          6. Multi occur: Select No or Yes from the list.

             Indicates whether this element or attribute can be used more than once in a document. Important If you specify multiple occurrence for a column, you can specify only one column in the side table that contains the column.

       2. Click Add to add a column.
       3. Continue adding, editing, or removing columns for the side table, or click Next.
     - To edit an existing side table column:

       You can update a side table by changing the definitions of the existing columns.

       1. Click on the side table and column name you want to edit.
       2. Edit the fields of the Details box.
       3. Click Change to save changes.
       4. Continue adding, editing, or removing columns for each side table, or click Next.
     - To remove an existing side table column:
       1. Click on the side table and column you want to remove.
       2. Click Remove.
       3. Continue adding, editing, or removing side table columns, or click Next.
     - To remove an existing side table:

       Delete each column in the side table to remove the table.

       1. Click on each side table column for the table you want to remove.
       2. Click Remove.
       3. Continue adding, editing, or removing side tables columns, or click Next.
  6. Type an output file name for the modified DAD file in the File name field of the Specify a DAD window.
  7. Click Finish to save the DAD file and to return to the LaunchPad.

  ### Creating or editing a DAD for XML collections

  When you create the DAD for the XML collection, you map the XML document to the DB2 data source, using one of the following techniques:

  - Compose an XML file, using SQL mapping
  - Compose an XML file, using RDB node mapping
  - Decompose an XML file, using RDB node mapping

  #### Composition with SQL mapping

  1. Click |Edit DAD from the LaunchPad. The Specify a DAD window is displayed.
  2. Choose whether to edit an existing DAD file or to create a new DAD file.

     To create a new DAD file:

     1. Leave the File name field blank.
     2. From the Type list, select XML collection SQL mapping.
     3. Click Next to open the Select Validation window.

     To edit an existing DAD file:

     1. Type the DAD file name into the File name field, or click ... to browse for an existing DAD file.
     2. Verify that the wizard recognizes the specified DAD file.
        - If the wizard recognizes the specified DAD file, Next is selectable and XML collection SQL mapping is displayed in the Type field.
        - If the wizard does not recognize the specified DAD file, Next is not selectable. Either retype the DAD file name, or click ... to browse again for an existing DAD file. Repeat the preceding steps until Next is selectable.
     3. Click Next to open the Select Validation window.
  3. In the Select Validation window, choose whether to validate your XML documents with a DTD.
     - To validate:
       1. Click Validate XML documents with the DTD.
       2. Select the DTD to be used for validation from the DTD ID list.

       If you have not imported any DTDs into the DTD repository for your database, you cannot validate your XML documents.

     - Click |Do NOT validate to continue without validating your XML documents.
  4. Click Next to open the Specify Text window.
  5. Type the prolog in the Prolog field, to specify the prolog of the XML document to be composed.

         <?xml version="1.0"?>

     If you are editing an existing DAD, the prolog is automatically displayed in the Prolog field.

  6. Type the document type of the XML document in the Doctype field of the Specify Text window, pointing to the DTD for the XML document. Example:

         |<!DOCTYPE Order SYSTEM "C:\dxx\samples\dtd\getstart.dtd">

     If you are editing an existing DAD, the document type is automatically displayed in the Doctype field.

  7. Click Next to open the Specify SQL Statement window.
  8. Type a valid SQL SELECT statement in the SQL statement field.

     If you are editing an existing DAD, the SQL statement is automatically displayed in the SQL statement field.

  9. Click Test SQL to test the validity of the SQL statement.
     - If your SQL statement is valid, sample results are displayed in the Sample results field.
     - If your SQL statement is not valid, an error message is displayed in the Sample results field. The error message instructs you to correct your SQL SELECT statement and to try again.
  10. |Click Next to open the Map SQL window.
  11. Select an element or attribute node to map from by clicking on it in the field on the left of the |Map SQL window.

      Map the elements and attributes in the XML document to element and attribute nodes that correspond to DB2 data. These nodes provide a path from the XML data to the DB2 data.

      - To add the root node:
        1. Select the Root icon.
        2. Click New Element to define a new node.
        3. In the Details box, specify Node type as Element.
        4. Enter the name of the root node in the Node name field.
        5. Click Add to create the new node.

           You have created the root node or element, which is the parent to all the other element and attribute nodes in the map. You can now add child elements and attributes to this node.

      - To add a child element or an attribute node:
        1. Click on a parent node in the field on the left to add a child element or attribute.

           If you have not selected a parent node, New Element is not selectable.

        2. Click New Element.
        3. Select the node type from the Node type list in the Details box.

           The Node type list displays only the node types that are valid at that point in the map.

        4. Type the node name in the Node name field in the Details box.
        5. If you specified Attribute, Element or Text for a bottom-level element as the Node type, select a column from the Column field in the Details box.

           Restriction: New columns cannot be created using the administration wizard. If you specify Column as the node type, you can only select a column that already exists in your DB2 database.

        6. Click Add to add the new node.

           You can modify a node later by clicking on it in the field on the left and making any needed modifications to it in the Details box. Click Change to update the element.

           You can also add child elements or attributes to the node by highlighting the node repeating the add process.

        7. Continue editing the SQL map, or click Next to open the Specify a DAD window.
      - To remove a node:
        1. Click on a node in the field on the left.
        2. Click Remove.
        3. Continue editing the SQL map, or click Next to open the Specify a DAD window.

        Note that if you remove a bottom-level node, another element will become a bottom-level node and might need a column name defined for it.

  12. Type the name of an output file for the modified DAD file in the File name field of the Specify a DAD window.
  13. Click Finish to return to the LaunchPad.

  #### Composition with RDB_node mapping

  1. Click |Edit DAD from the LaunchPad. The Specify a DAD window is displayed.
  2. Choose whether to edit an existing DAD file or to create a new DAD.

     To edit an existing DAD:

     1. Type the DAD file name into the File name field or click ... to browse for an existing DAD.
     2. Verify that the wizard recognizes the specified DAD file.
        - If the wizard recognizes the specified DAD file, Next is selectable, and XML collection RDB_node mapping is displayed in the Type field.
        - If the wizard does not recognize the specified DAD file, Next is not selectable. Either retype the DAD file name into the File name field or click ... to browse again for an existing DAD file. Continue these steps until Next is selectable.
     3. Click Next to open the Select Validation window.

     To create a new DAD:

     1. Leave the File name field blank.
     2. Select XML collection RDB node mapping from the Type list.
     3. Click Next to open the Select Validation window.
  3. In the Select Validation window, choose whether to validate your XML documents with a DTD.
     - To validate:
       1. Click Validate XML documents with the DTD.
       2. Select the DTD to be used for validation from the DTD ID list.

       If you have not imported any DTDs into the DTD repository for your database, you cannot validate your XML documents.

     - Click |Do NOT validate to continue without validating your XML documents.
  4. Click Next to open the Specify Text window.
  5. Type the prolog name in the Prolog field of the Specify Text window.

         <?xml version="1.0"?>

     If you are editing an existing DAD, the prolog is automatically displayed in the Prolog field.

  6. Enter the document type of the XML document in the Doctype field. Example:

         |<!DOCTYPE Order SYSTEM "C:\dxx\samples\dtd\getstart.dtd">

     If you are editing an existing DAD, the document type is automatically displayed in the Doctype field.

  7. |Click Next to open the Map RDB nodes window.
  8. Select an element or attribute node to map from by clicking on it in the field on the left of the |Map RDB nodes window.

     Map the elements and attributes in the XML document to element and attribute nodes that correspond to DB2 data. These nodes provide a path from the XML data to the DB2 data.

  9. To add the root node:
     1. Select the Root icon.
     2. Click New Element to define a new node.
     3. In the Details box, specify Node type as Element.
     4. Enter the name of the root node in the Node name field.
     5. Click Add to create the new node.

        You have create the root node or element, which is the parent to all the other element and attribute nodes in the map. The root node has table child elements and a join condition.

        Add table nodes for each table that is part of the collection.

        1. Highlight the root node name and select New Element.
        2. In the Details box, specify Node type as Table.
        3. Select the name of the table from Table name. The table must already exist.
        4. Click Add to add the table node.
        5. Repeat these steps for each table.

        Add a join condition for the table nodes.

        1. Highlight the root node name and select New Element.
        2. In the Details box, specify Node type as Condition.
        3. In the Condition field, enter the join condition using the following syntax:.

               table_name.table_column = table_name.table_column AND
               table_name.table_column = table_name.table_column ...

           Include as many conditions, joined by AND, as required to create the join condition.

        4. Click Add to add the condition.

     You can now add child elements and attributes to this node.

  10. To add a child element or an attribute node:
      1. Click on a parent node in the field on the left to add a child element or attribute.
      2. Click New Element. If you have not selected a parent node, New Element is not selectable.
      3. Select a node type from the Node type list in the Details box.

         The Node type list displays only the node types that are valid at that point in the map, which are either Element or Attribute.

      4. Type the name of the element or attribute in the Node name field.
      5. If you specified Attribute as the Node type, or Element for a bottom-level element, select a column from the Column field in the Details box.

         Restriction: New columns cannot be created using the administration wizard. If you specify Column as the node type, you can only select a column that already exists in your DB2 database.

      6. Click Add to add the new node.

         You can modify a node later by clicking on it in the field on the left and making any needed modifications to it in the Details box. Click Change to update the element.

         You can also add child elements or attributes to the node by highlighting the node repeating the add process.

      7. To map the contents of an element or attribute node to a relational table:
         1. Specify a text node.
            1. Click the parent node.
            2. Click New Element.
            3. In the Node type field, select Text.
            4. Select Add to add the node.
         2. Add a table node.
            1. Select the text node you just created and click New Element.
            2. In the Node type field, select Table and specify a table name for the element.
            3. Click Add to add the node.
         3. Add a column node.
            1. Select the text node again and click New Element.
            2. In the Node type field, select Column and specify a column name for the element.
            3. Click Add to add the node.

            Restriction: New columns cannot be created using the administration wizard. If you specify Column as the node type, you can only select a column that already exists in your DB2 database.

         4. Optionally add a condition for the column.
            1. Select the text node again and click New Element.
            2. In the Node type field, select Condition and the condition with the syntax:

                   operator LIKE|<|>|= value

            3. Click Add to add the node.
      8. Continue editing the RDB_node map or click Next to open the Specify a DAD window.
  11. To remove a node:
      1. Click on a node in the field on the left.
      2. Click Remove.
      3. Continue editing the RDB_node map or click Next to open the Specify a DAD window.
  12. Type in an output file name for the modified DAD in the File name field of the Specify a DAD window.
  13. Click Finish to remove the node and return to the LaunchPad.

  #### Decomposition with RDB_node mapping

  1. Click |Edit DAD from the LaunchPad. The Specify a DAD windows is displayed.
  2. Choose whether to edit an existing DAD file or to create a new DAD.

     To edit an existing DAD:

     1. Type the DAD file name into the File name field or click ... to browse for an existing DAD.
     2. Verify that the wizard recognizes the specified DAD file.
        - If the wizard recognizes the specified DAD file, Next is selectable, and XML collection RDB_node mapping is displayed in the Type field.
        - If the wizard does not recognize the specified DAD file, Next is not selectable. Either retype the DAD file name into the File name field or click ... to browse again for an existing DAD file. Continue these steps until Next is selectable.
     3. Click Next to open the Select Validation window.

     To create a new DAD:

     1. Leave the File name field blank.
     2. Select XML collection RDB_node mapping from the Type list.
     3. Click Next to open the Select Validation window.
  3. In the Select Validation window, choose whether to validate your XML documents with a DTD.
     - To validate:
       1. Click Validate XML documents with the DTD.
       2. Select the DTD to be used for validation from the DTD ID list.

       If you have not imported any DTDs into the DTD repository for your database, you cannot validate your XML documents.

     - Click |Do NOT validate to continue without validating your XML documents.
  4. Click Next to open the Specify Text window.
  5. If you are decomposing an XML document only, ignore the Prolog field. If you are using the DAD file for both composition and decomposition, type the prolog name in the Prolog field of the Specify Text window. The prolog is not required if you are decomposing XML documents into DB2 data.

         <?xml version="1.0"?>

     If you are editing an existing DAD, the prolog is automatically displayed in the Prolog field.

  6. If you are decomposing an XML document only, ignore the Doctype field. If you are using the DAD file for both composition and decomposition, enter the document type of the XML document in the Doctype field

     If you are editing an existing DAD, the document type is automatically displayed in the Doctype field. Example:

         |<!DOCTYPE Order SYSTEM "C:\dxx\samples\dtd\getstart.dtd">

  7. Click Next to open the RDB Mapping window.
  8. Select an element or attribute node to map from by clicking on it in the field on the left of the RDB Mapping window.

     Map the elements and attributes in the XML document to element and attribute nodes which correspond to DB2 data. These nodes provide a path from the XML data to the DB2 data.

  9. To add the root node:
     1. Select the Root icon.
     2. Click New Element to define a new node.
     3. In the Details box, specify Node type as Element.
     4. Enter the name of the root node in the Node name field.
     5. Click Add to create the new node.

        You have created the root node or element, which is the parent to all the other element and attribute nodes in the map. The root node has table child elements and a join condition.

        Add table nodes for each table that is part of the collection.

        1. Highlight the root node name and select New Element.
        2. In the Details box, specify Node type as Table.
        3. Select the name of the table from Table name. The table must already exist.
        4. Specify a key column for the table in the Table key field.
        5. Click Add to add the table node.
        6. Repeat these steps for each table.

        Add a join condition for the table nodes.

        1. Highlight the root node name and select New Element.
        2. In the Details box, specify Node type as Condition.
        3. In the Condition field, enter the join condition using the following syntax:.

               table_name.table_column = table_name.table_column AND
               table_name.table_column = table_name.table_column ...

        4. Click Add to add the condition.

     You can now add child elements and attributes to this node.

  10. To add a child element or an attribute node:
      1. Click on a parent node in the field on the left to add a child element or attribute.

         If you have not selected a parent node, New is not selectable.

      2. Click New Element.
      3. Select a node type from the Node type list in the Details box.

         The Node type list displays only the node types that are valid at that point in the map, which are either Element or Attribute.

      4. Click Add to add the new node. You can modify a node later by clicking on it in the field on the left and making any needed modifications in the Details box. Click Change to update the element.
      5. To map the contents of an element or attribute node to a relational table:
         1. Specify a text node.
            1. Click the parent node.
            2. Click New Element.
            3. In the Node type field, select Text.
            4. Select Add to add the node.
         2. Add a table node.
            1. Select the text node you just created and click New Element.
            2. In the Node type field, select Table and specify a table name for the element.
            3. Click Add to add the node.
         3. Add a column node.
            1. Select the text node again and click New Element.
            2. In the Node type field, select Column and specify a column name for the element.
            3. Specify a base data type for the column in the Type field, to specify what type the column must be to store the untagged data.
            4. Click Add to add the node.

            Restriction: New columns cannot be created using the administration wizard. If you specify Column as the node type, you can only select a column that already exists in your DB2 database.

         4. Optionally add a condition for the column.
            1. Select the text node again and click New Element.
            2. In the Node type field, select Condition and the condition with the syntax:

                   operator LIKE|<|>|= value

            3. Click Add to add the node.
      6. Continue editing the RDB_node map or click Next to open the Specify a DAD window.
  11. To remove a node:
      1. Click on a node in the field on the left.
      2. Click Remove.
      3. Continue editing the RDB_node map or click Next to open the Specify a DAD window.
  12. Type in an output file name for the modified DAD in the File name field of the Specify a DAD window.
  13. Click Finish to remove the node and return to the LaunchPad.

  # Working with XML columns

  From this wizard you can add, enable, or disable XML columns for the XML Extender.

  ## Fields and controls

  ### Select a task (for columns)

  Add an XML Column
    Select to open the Add an XML column window for adding a column to a table. This column will contain an intact XML document. This option is available only if the database is enabled.

  |Enable an XML Column
    Select to open the |Enable an XML column window for connecting to a database and enabling an XML column so that it can contain XML Extender UDTs. This option is available only if the database is enabled and columns are created for XML documents.

  |Disable an XML Column
    Select to open the |Disable an XML column window for disabling an existing column. If the database is not enabled or an enabled XML column does not exist, this option is not available. A disabled column can no longer contain XML documents. You must disable an XML column before dropping an XML table. If a table is dropped and its XML column is not disabled, XML Extender keeps the side tables it created and the XML column entry in the XML usage table.

  Next
    Opens the window you selected to add, enable, or disable an XML column.

  Finish
    Available when you finish working with the column.

  Cancel
    Cancels the wizard and returns you to the LaunchPad.

  ### Add an XML column

  Table name
    Type the table name or select the name from the list of available tables. The table must be defined to add an XML column. Example:

        SALES_DB

  Column name
    Type the name that you want to use for the XML column. Example:

        ORDER

  |Data type
    Select the data type from the list of available types, such as XMLCLOB, XMLVARCHAR, or XMLFILE. Example:

        XMLVARCHAR

  Back
    Opens the Select a task window you used to work with XML columns.

  Finish
    Adds the XML column and returns you to the LaunchPad.

  Cancel
    Cancels the wizard and returns you to the LaunchPad.

  ### Enable an XML column

  Table name
    Type the name of the table that has an XML column or select the name from the list of available table names. Example

        SALES_TAB

  Column name
    Type the name of an existing XML column in the table or select the name from the list of available columns. Example:

        ORDER

  DAD file name
    Type the location of the DAD file that maps the XML document to the XML column and side tables or click ... to browse for an existing DAD file. Example:

        c:\dxx\samples\dad\getstart.dad

  Table space
    Optional: Type the name of a previously created table space for side tables associated with the XML column. If the table space is not specified, a default table space is used.

  Default view
    Optional: Type the name of a default view that joins the XML table and all related side tables.

  |Root ID
    Recommended, but optional: type the column name of the primary key in the table to associate all side tables with the application table. If you don't specify a ROOT ID, XML Extender adds a DXXROOT_ID column to the table and generates an identifier.

  Back
    Opens the Select a task window you used to work with XML columns.

  Finish
    Enables the XML column and returns you to the LaunchPad. To enable the column, XML Extender determines whether the XML table has a primary key, creates side tables that are specified in the DAD file, and creates a default view for the XML table and side tables.

  Cancel
    Cancels the wizard and returns you to the LaunchPad

  ### Disable an XML column

  Table name
    Type the name of the table that contains the XML column or select the name from the list of available tables.

  Column name
    Type the name of an existing column in the table or select the name from the list of column names.

  Back
    Opens the Select a task window you used to work with XML columns.

  Finish
    Disables the XML column and returns you to the LaunchPad. A disabled XML column can no longer contain XML documents.

  Cancel
    Cancels the wizard and returns you to the LaunchPad.

  ## Tasks

  ### Adding an XML column

  1. Click Work with XML columns from the LaunchPad. The Select a task window opens.
  2. Click Add an XML Column. The Add an XML column window opens.
  3. Select the name of the table from the Table name list, or type the name of the table you want to alter.
  4. Type the name of the column to be added to the table in the Column name field.
  5. Select the UDT for the column from the |Data type list.
  6. Click Finish to add the column of XML type.

  ### Enabling an XML column

  1. Click Work with XML Columns from the LaunchPad to view the XML Extender column related tasks. The Select a Task window opens.
  2. Click |Enable an XML Column and then Next to enable an existing table column in the database.
  3. Select the table that contains the XML column from the Table name field.
  4. Select the column being enabled from the Column name field. The column must exist and be of XML type.
  5. Type the DAD path and file name into the DAD file name field, or click ... to browse for an existing DAD file.
  6. Optionally, type the name of an existing table space in the Table space field.

     The table space contains side tables that the XML Extender created. If you specify a table space, the side tables are created in the specified table space. If you do not specify a table space, the side tables are created in the default table space.

  7. Optionally, type the name of the default view in the Default view field.

     When specified, the default view is automatically created when the column is enabled and joins the XML table and all of the related side tables.

  8. Optionally, type the column name of the primary key in the application table in the Root ID field. This is recommended.

     The XML Extender uses the value of root ID as a unique identifier to associate all side tables with the application table. If not specified, the XML Extender adds the DXXROOT_ID column to the application table and generates an identifier.

  9. Click Finish to enable the XML column, create the side tables, and return to the LaunchPad.
     - If the column is successfully enabled, an `Enabled column is successful` message is displayed.
     - If the column is not successfully enabled, an error box is displayed. Correct the values in the entry fields until the column is successfully enabled.

  ### Disabling an XML column

  1. Click Working with XML Columns from the LaunchPad to view the XML Extender column related tasks. The Select a Task window opens.
  2. Click |Disable an XML Column and then Next from the Select a Task window to disable an existing table column in the database.
  3. Select the table that contains the XML column from the Table name field.
  4. Select the column being disabled from the Column name field.
  5. Click Finish.
     - If the column is successfully disabled, an `Disabled column is successful` message is displayed.
     - If the column is not successfully disabled, an error box is displayed. Correct the values in the entry fields until the column is successfully disabled.

  # Working with XML collections

  From this wizard you can enable or disable XML collections.

  ## Fields and controls

  ### Select a task (for collections)

  Enable an XML Collection
    Select to open the Enable an XML collection window. Enabling an XML collection parses the DAD file to identify tables and columns related to XML documents and records control information. This option is available only if the database is enabled and a DAD file exists.

  Disable an XML Collection
    Select to open the Disable a collection window for removing markers that identify tables and columns as part of an XML collection. If the collection is not enabled, this option is not available.

  Next
    Opens the window you selected to enable or disable an XML collection.

  Finish
    Available when you finish working with the collection.

  Cancel
    Cancels the wizard and returns you to the LaunchPad.

  ### Enable an XML collection

  Collection name
    Type the name of the XML collection that you want to enable.

  DAD file name
    Type the name of the DAD file that maps the structure of the XML document to the DB2 tables from which you compose or decompose a document or click ... to browse for an existing DAD file.

  ...
    Opens a Find window for you to select an existing DAD file name.

  Table space
    Type the name of a previously created table space if one exists. The table space will contain new DB2 tables generated for composition or decomposition.

  Back
    Opens the Select a task window you used to work with XML collections.

  Finish
    Enables the XML collection and returns you to the LaunchPad. To enable the collection, XML Extender used the DAD file to identify the XML document's tables and columns and records control information in the XML_USAGE table.

  Cancel
    Cancels the wizard and returns you to the LaunchPad.

  ### Disable an XML collection

  Collection name
    Select the name of the XML collection that you want to disable from the list of collections.

  Back
    Opens the Select a task window you used to work with XML collections.

  Finish
    Disables the XML collection and returns you to the LaunchPad. To disable a collection, XML Extender removes markers that identify tables and columns as part of an XML collection.

  Cancel
    Cancels the wizard and returns you to the LaunchPad.

  ## Tasks

  ### Enabling an XML collection

  1. Click Work with XML Collections from the LaunchPad. The Select a Task window is displayed.
  2. Click |Enable an XML Collection and then Next. The Enable a Collection window is displayed.
  3. Select the name of the collection you want to enable in the Collection name field from the list.
  4. Type the DAD file name into the DAD file name field or click ... to browse for an existing DAD file.
  5. Optionally, type the name of a previously created table space in the Table space field.

     The table space will contain new DB2 tables generated for decomposition.

  6. Click Finish to enable the collection and return to the LaunchPad.
     - If the collection is successfully enabled, an `Enabled collection is successful` message is displayed.
     - If the collection is not successfully enabled, an error message is displayed. Correct the values in the entry fields until the collection is successfully enabled.

  ### Disabling an XML collection

  1. Click Work with XML Collections from the LaunchPad to view the XML Extender collection related tasks. The Select a Task window is displayed.
  2. Click Disable an XML Collection and then Next to disable an XML collection. The Disable a Collection window is displayed.
  3. Type the name of the collection you want to disable in the Collection name field.
  4. Click Finish to disable the collection and return to the LaunchPad.
     - If the collection is successfully disabled, an `Disabled collection is successful message` is displayed.
     - If the collection is not successfully disabled, an error box is displayed. Correct the values in the entry fields until the collection is successfully disabled.