Requirements for Running XML-SQL Utility

There are two versions of the utility - XSU111.zip and XSU12.zip, one compatible for JDK 1.1.x and the other with JDK1.2 respectively.

XSU111 - XML-SQL Utility (for JDK 1.1.x)

This is the JDK 1.1.x compatible version. It needs Java JDK 1.1.x version and the JDBC 1.x compliant drivers. Oracle ships classes111.zip as the JDBC 1.x compliant driver. The utility is also dependent on the Oracle XML Parser V2 for parsing documents and for creating DOM nodes. To load this into the database, the database must be running Oracle8i JVM (JServer) version 8.1.5 or above.

XSU12 - XML-SQL Utility (for JDK 2.x)

This version of the utility is JDK1.2.x/JDK 2.x compliant. It needs Java JDK 1.2.x (or JDK2.x) to be available. The JDBC drivers need to be JDK1.2 compliant as well. Oracle ships classes12.zip as the JDBC2.0 compliant driver. The XSU utility is also dependent on the Oracle XML parser V2. The database version must be 8.1.6 or above, with Oracle8i JVM (JServer) enabled, for the utility to be uploaded in to the server and run inside the database.

XSU Requirements

Before installing the utility make sure that you choose the right version of the utility depending on your particular needs. For example, if you can only use the JDK1.1.x version, then download the XSU111.zip file. Ensure that you have the JDK and the JDBC drivers correctly downloaded and installed, if not already available.

Extract the XSU Files

After downloading the zip file, simply extract the contents to a directory of your choice, say C:\xml. The files will get expanded in to a subdirectory called XSU111 or XSU12 depending on the version of the utility.

Setting Up the Correct XSU Environment: Client Side

Depending on the way you plan to use the utility, on the client or server side, perform different set up tasks.

CLASSPATH Settings

If you are running XSU from the client side, you need to correct CLASSPATH settings. If these variables are already set correctly in your environment, then you need to only ensure that oraclexmlsql.jar is included in this CLASSPATH. You can do this by either editing your global settings or changing the settings for your current shell.

Global Settings: To edit your global settings proceed as follows:

UNIX: Set the CLASSPATH variable in your login or .tcsh scripts. Simply edit them and include the path to the oraclexmlsql.jar file. For example,

Windows: Modify the enviroment variable in the System Properties folder under the Settings/Control Panel in Windows to include the path. For example, if you expanded the utility under D:\xml, include D:\xml\XSU12\lib\oraclexmlsql.jar in the variable setting.

Current Shell Settings: To modify the settings for the particular shell you are running in follow these steps:

UNIX: Edit the env.csh file Make sure that the path names in env.csh are correct and then source the env.csh file. This sets the environment variables correctly. If you are using a shell other than csh or tcsh, edit the file to use your shell's syntax.

Windows: Edit the env.bat file, and ensure that the variable settings are correct and then execute the file to set up the variables in the current environment.

The latter operation only affects the current shell you are running in and consequently you have to source or execute these batch files for every different shell.

Database

Ensure that Your database is up and running.

After this, you are ready to use the utility from the client side.

Setting Up the Correct XSU Environment: Server Side

To use XSU's PL/SQL API, or write Java stored procedures on top of XSU Java APIs, perform the following steps:

Choose the database schema into which you want to upload XSU. The default schema is "scott". To change this schema, edit the oraclexmlsql.xxx file and modify the USER_PASSWORD macro file to the desired schema.

UNIX: Modify oraclexmlsqlload.csh file

Windows: Modify oraclexmlsqlload.bat file

Confirm that the Oracle database into which you are planning to load XSU is Java enabled and is up and running.

Execute the appropriate oraclexmlsqlload.xxx file: This does the following:

Loads Oracle XML Parser for Java, V2, into the database. If the Parser is already loaded into the database, you can comment out the line in oraclexmlsqlload.xxx which loads the Parser.

Loads oraclexmlsql.jar, the Java classes that make up XSU, into your Oracle database.

Executes the xmlgenpkg.sql SQL script. This creates the PL/SQL API on top of the loaded Java classes.

Executes oraclexmltest.sql which tests that the PL/SQL API is loaded and operational. As you run this, you will see SQLPlus come up and the various queries run and XML results displayed. If the tests fail to run, you need to re-load XSU after taking appropriate steps to fix the problems.

Now, you are ready to use the Java and PL/SQL APIs inside the Oracle server.