XML Extender Administration Wizard Release Notes

© Copyright IBM Corporation 2004
September 2004

Contents

Setting up the XML Extender administration wizard

Web Services Development Environment: alternate document access definition (DAD) editing tool

What's new in XML Extender administration wizard with version dated 08-18-04?

Notices

Setting up the XML Extender administration wizard

The administration wizard helps you manage your database and tables for use with XML files. The wizard helps you complete the following tasks:

1. Enable or disable a database for XML Extender.
2. Enable table columns for XML Extender.
3. Create collections of table columns that are mapped to XML document trees.
4. Create and edit document access definition files that map the XML tree structure to relational tables to generate or shred XML documents. An alternative DAD editor is provided in the XML and Web Services Development Environment (WSDE) tool set. See Web Services Development Environment: alternate document access definition (DAD) editing tool.
5. Import DTDs into the database.

The following instructions will guide you through setting up your system to use the wizard.

Product assumptions

This document assumes that you have downloaded the wizard package because any of the following conditions apply to you:

• You are running in a UNIX or Windows client/server environment, have installed DB2 XML Extender, and you are upgrading the wizard delivered with DB2 UDB XML Extender, Version 7 or later.
• You are running in an OS/390 environment, and want to administer DB2 XML Extender using the administration wizard from a UNIX or Windows client. You are upgrading the version of the wizard delivered with the DB2 UDB XML Extender for OS/390 or z/OS, Version 7 or later.
• You are running in OS/400, OS/390, UNIX or Windows environment, want to administer DB2 XML Extender, and are installing the administration wizard on to a UNIX or Windows client by Web download.

Setting up the adminstration wizard on all operating systems except OS/400

To set up and start the XML Extender administration wizard:

• Ensure that you have a swingall.jar file. This file is available from the following sources:
  • JDK 1.2 or later
  • DB2 Connect Personal Edition Version 7 or later
• Ensure that you have Java or a supported JRE or JDK installed.
  The JDK and JRE are provided with DB2 UDB Version 7.1, on certain operating systems. When available, the JRE is automatically installed, and the JDK is installed when you choose to install the DB2 UDB Application Development selection. You do not need to use the JDK or JRE that is provided with DB2 UDB. See the DB2 Universal Database: Java Enablement with DB2 Universal Database Web site at http://www.ibm.com/software/data/db2/java.

  If you are using an operating system in which Java support is not provided by DB2 UDB, you must install the JDK or JRE yourself. Use the link above to the DB2 Java Web site to find download packages for the various levels of Java that have been tested with DB2 UDB. You can also choose to install another version of the JDK or JRE even if you have the DB2-provided versions installed.

1. Set your PATH and CLASSPATH environment variables. In this step, the following terms are used to indicate product installation directories. These are documentation conventions, not actual variables.
   

   dxx_install_directory

   The directory under which the XML Extender is installed. For example, on Windows operating systems, the default is: c:\dxx

   db2_install_directory

   The directory under which DB2 UDB is installed. For example, on Windows operating systems, the default is: c:\program files for DB2 UDB Version 7 and c:\program files\IBM for Version 8.
   

   1. Set the PATH variable.
      The PATH statement must contain the directories for the Java™ binary files and optionally the XML Extender administration directory. See Table 1 and Table 2 to learn how to set this up.
      
   2. Set the CLASSPATH variable. The CLASSPATH points to the administration wizard jar files, Java class libraries, the Swingall jar file, and the DB2 JDBC™ driver file. See Table 1 and Table 2 to learn how to set up.

   
   
2. Test the installation by invoking the DB2 XML Extender administration wizard as follows:
   • To start the administration wizard for Windows Version 7, click Start -> Programs -> DB2 XML Extender -> XML Extender Administration Wizard.
   • To start the administration wizard for Version 8, enter the following command from the command line:
     

     dxxadmin

3. On the Logon window of the XML Extender administration Launchpad, specify the information for the server that is associated with the XML data that you want to work with. The following example accesses the OS/390 remote database from the workstation:

   Address

   This field contains the fully qualified JDBC URL to the data source that you are connecting to. For example:

   Jdbc:db2:ISC710P1

   where ISC710P1 is the alias database name that is cataloged on the local system.

   Tip: If you want to specify a database name instead of a JDBC URL, you must first run the following commands to allow the local DB2 UDB system to forward the SQL requests to the remote server:

   -- Remove prior catalog entries 
   db2 uncatalog node ISC710P1
   db2 uncatalog database db710p1
   db2 uncatalog dcs database ISC710P1
   -- Add TCP/IP node entry to the node directory to access the remote node
   db2 catalog tcpip node isc710p1 remote isc710p1.stl.ibm.com server 446
   -- Store remote database location information in the local database directory
   db2 catalog database isc710p1 as db710p1 at node isc710p1 authentication
   dcs
   -- Store remote database information in the Database Connection Services (DCS) directory
   db2 catalog dcs database isc710p1 as stlec1

   DB710P1 is the database name that is successfully cataloged into the client system. Then in the Logon window, you can specify DB710P1 as the database name that you want to access.

   User ID and Password

   In these fields, specify a user ID and password to connect to OS/390 or z/OS.

   JDBC driver

   In this field, specify the following value for the JDBC Driver name:

   COM.ibm.db2.jdbc.app.DB2Driver

   The XML Extender administration launchpad is started when you complete the logon window. You can use this launchpad to do any of the following tasks:

   • Enable or disable a server for XML Extender
   • Add, enable, or disable an XML column
   • Enable or disable an XML collection
   • Create and edit DAD files
   
   Table 1 describes the requirements for the PATH statement:
   

   Table 1. PATH values
   

   Software	PATH value
   Java binary files	Depends on the Java package that you use: DB2 JDK: db2_install_directory/sqllib/java/jdk/bin DB2 JRE: db2_install_directory/sqllib/java/jre/bin User-installed JDK: install_directory/bin User-installed JRE: install_directory/bin
   XML Extender administration directory	Version 7: For all operating systems except Linux, the directory is: dxx_install_directory/dxxadmin/ For Linux, the directory is: dxx_install_directory/adm_g/ Version 8: db2_install_directory/sqllib/bin

   Table 2 describes the directories and requirements for the CLASSPATH.
   

   Table 2. CLASSPATH values
   

   Software	CLASSPATH value
   XML Extender jar files (V7 only): dxxadmin.jar xml4j.jar	For all operating systems except Linux: dxx_install_directory/dxxadmin/ For Linux: dxx_install_directory/adm_g
   XML Extender jar files (V8 only): dxxadmin.jar xerces.jar xml_apis.jar	db2_install_directory/sqllib/tools
   Java class libraries	Depends on whether you are running the java or jre command: java command: Point to the classes.zip file. For example: db2_install_directory/SQLLIB/java/jdk/lib/classes.zip jre command: Point to the rt.jar file. For example: db2_install_directory/SQLLIB/java/jre/lib/rt.jar
   Swingall.jar file	For V7 using the DB2-provided swingall: db2_install_directory/SQLLIB/java/swingall.jar For V8 using the DB2-provided swingall: db2_install_directory/SQLLIB/doc/prodcdsen_US/swingall.jar
   JDBC: db2java.zip	For DB2 Connect Personal Edition V7 or later: db2_install_directory/SQLLIB/java/db2java.zip

See the DB2 UDB XML Extender Administration and Programming to learn how to start the wizard and connect to the database. OS/400 users, see Setting up the wizard on OS/400 to learn how to configure and start the wizard when connecting to OS/400 systems.

Setting up the wizard on OS/400

The set up for the administration wizard has some minor differences from the other operating systems.

Before you run the wizard, you must configure the CLASSPATH statement on your workstation system. Setting up the adminstration wizard on all operating systems except OS/400 describes the general steps. The exception to this process for OS/400 is the JDBC driver path, which is not provided with DB2 UDB for iSeries.

To set up, download and install the JDBC driver, and add the file name to the CLASSPATH. Additionally, to connect to an OS/400 database system, you must provide connectivity information in a slightly different format from OS/390, UNIX, or Windows. The follow sections describe how to install and configure the JDBC driver, and how to enter the initial settings for the wizard.

Installing and configuring the OS/400 JDBC driver for DB2 XML Extender

The JDBC driver for AS/400 is delivered in the AS/400 Toolbox for Java class files. To use it, you must copy the toolbox on your workstation.

Copying the AS/400 Toolbox for Java class files on your workstation:

You can get server updates on your workstation by using the AS400ToolboxInstaller class or other means, such as ftp. To use the AS400TolboxInstaller class, complete the following steps:

1. Read the topic Client installation and update classes in the iSeries Information Center. This topic documents the class.
2. Find the file named jt400.jar on your AS/400 system. The default path is /QIBM/ProdData/HTTP/Public/jt400/lib.
3. Update the CLASSPATH environment variable of your workstation by adding the location where you copied jt400.jar.

To use an alternative method, complete the following steps:

1. Find the file named jt400.jar on your AS/400 system. The default path is /QIBM/ProdData/HTTP/Public/jt400/lib.
2. Connect the workstation to your system by ftp, map a network drive with Client Access/400, or another method that you might have.
3. Copy jt400.jar from the AS/400 to your workstation. If you use ftp to transfer the file, transfer the file in binary mode.
4. Update the CLASSPATH environment variable of your workstation by adding the location where you copied jt400.jar.

Starting the administration wizard

On Windows, you can start the wizard by creating a shortcut and clicking on the icon. On Windows or UNIX, you can also modify the dxxadmin400.cmd file and run the cmd file to start the wizard. In both cases, you enter connectivity values. The following sections describe the start up values required for using the wizard.

Connect to a RDB database

When you start the XML Extender administration wizard, the Logon window opens, and requests information required to connect to a DB2 database.

To connect to the database, enter the following values on the first screen:

1. In the Address field, enter the fully-qualified JDBC URL to the data source to which you are connecting. The address has the following syntax:

   jdbc:as400://host_name/database_name
   

   Where database_name is the database to which you are connecting and storing XML documents.

   For example:

   jdbc:as400://host1.mycompany.com/mydb
   

2. In the User ID and Password fields, enter or verify the DB2 user ID and password for the database to which you are connecting.
3. In the JDBC Driver field, verify the JDBC driver name for the specified address using the following value:

   com.ibm.as400.access.AS400JDBCDriver
   

4. Click Finish to connect to the wizard and advance to the Launchpad window. For more information about the XML Extedner administration wizard, see the DB2 Information Center.

Updating the dxxadmin400.cmd file

Customize the dxxadmin400.cmd file to save your startup values and start the wizard. To customize the file, locate the file in the directory with the wizard files and open it in a text editor. Replace the existing text with the following value:

java -classpath "dxxadmin.jar;xml4j.jar;jt400.jar" com.ibm.dxx.admin.Admin url=jdbc:

as400://host_name/database_name driver=com.ibm.as400.access.AS400JDBCDriver

When you start the wizard, these values are entered in the Logon window, and you can connect to the database.

Web Services Development Environment: alternate document access definition (DAD) editing tool

WebSphere Studio provides a tool that can create document access definitions (DAD) for XML Extender. For more information, see Exploring the RDB to XML Mapping Editor.

What's new in XML Extender administration wizard that is dated 18 August 2004?

• The drop-down list of table names now shows schema-qualified table names.
• The drop-down list of table names no longer shows tables that are in the db2xml schema.
• The drop-down list of table names no longer includes any view names.
• The Work with XML Collections function reflects errors. For example, if the passed DAD file for XML collection enablement is invalid, Administration Wizard issues a corresponding message.

Notices

This information was developed for products and services offered in the U.S.A. IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate and verify the operation of any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to:

For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual Property Department in your country or send inquiries, in writing, to:

The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you.

This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice.

Licensees of this program who want to have information about it for the purpose of enabling: (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact:

Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee.

The licensed program described in this information and all licensed material available for it are provided by IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement, or any equivalent agreement between us.

Information concerning non-IBM products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not tested those products and cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products.

All statements regarding IBM's future direction or intent are subject to change or withdrawal without notice, and represent goals and objectives only.

COPYRIGHT LICENSE:

This information contains sample application programs in source language, which illustrates programming techniques on various platforms. You may copy, modify, and distribute these sample programs in any form without payment to IBM, for the purposes of developing, using, marketing or distributing application programs conforming to the application programming interface for the operating platform for which the sample programs are written. These examples have not been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or imply reliability, serviceability, or function of these programs.

Trademarks

The following terms are trademarks of the International Business Machines Corporation in the United States, or other countries, or both:

DB2
DB2 UDB
DB2 Universal Database
iSeries
OS/390
OS/400
z/OS

Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States, other countries, or both.

Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in the United States, other countries, or both.

UNIX is a registered trademark in the United States, other countries, or both and is licensed exclusively through X/Open Company Limited.

Other company, product, and service names may be trademarks or service marks of others.