Skip Headers

Oracle9i XML Database Developer's Guide - Oracle XML DB
Release 2 (9.2)

Part Number A96620-02
Go to Documentation Home
Go to Book List
Book List
Go to Table of Contents
Go to Index
Go to Master Index
Master Index
Go to Feedback page

Go to previous page Go to next page
View PDF

Installing and Configuring Oracle XML DB

This appendix describes the ways you can manage and configure your Oracle XML DB applications. It contains the following sections:

Installing Oracle XML DB

You will need to install Oracle XML DB under the following conditions:

Installing or Reinstalling Oracle XML DB from Scratch

You can perform a new installation of Oracle XML DB with or without Database Configuration Assistant (DBCA):

Installing a New Oracle XML DB with DBCA

Oracle XML DB is part of the seed database and installed by DBCA as part of database installation by default. No additional steps are required to install Oracle XML DB, however, if you choose to install "Customized" database, you can configure Oracle XML DB tablespace and FTP, HTTP, and WebDAV port numbers.

By default DBCA performs the following tasks:

The Oracle XML DB tablespace holds the data that is stored in Oracle XML DB Repository. This includes data that is stored in the Repository using:

You can store data in tables outside this tablespace and access the data through the Repository by having REFs to that data stored in the tables in this tablespace.


The Oracle XML DB tablespace should not be dropped. If dropped it renders all Repository data inaccessible.

Dynamic Protocol Registration Registers FTP and HTTP Services with Local Listener

Oracle XML DB installation, includes a dynamic protocol registration that registers FTP and HTTP services with the local Listener. You can perform start, stop, and query with "lsnrctl". For example:

Changing FTP or HTTP Port Numbers

To change FTP or HTTP port numbers, update the tags <ftp-port> and <http-port> in file, /xdbconfig.xml in Oracle XML DB Repository.

See Also:

Chapter 19, "Using FTP, HTTP, and WebDAV Protocols" for a description of how to update /xdbconfig.xml.

After updating the port numbers dynamic protocol registration automatically stops FTP/HTTP service on old port numbers and starts them on new port numbers if the local Listener is up. If local Listener is not up, restart the Listener after updating the port numbers.

Post Installation

As explained in the previous section, Oracle XML DB uses dynamic protocol registration to setup FTP and HTTP listener services with the local Listener. So, make certain that the Listener is up when accessing Oracle XML DB protocols.

To allow for unauthenticated access to your Oracle XML DB Repository data through HTTP, you must unlock the ANONYMOUS user account.


If the Listener is running on a non-standard port (for example, not 1521) then in order for the protocols to register with the correct listener the init.ora file must contain a local_listener entry. This references a TNSNAME entry that points to the correct listener. After editing the init.ora parameter you must regenerate the SPFILE entry using CREATE SPFILE.

Installing a New Oracle XML DB Manually Without DBCA

After the database installation, you must run the following SQL scripts in rdbms/admin connecting to SYS to install Oracle XML DB after creating a new tablespace for Oracle XML DB Repository. Here is the syntax for this:

catqm.sql <xdb_pass> <XDB_TS_NAME> <TEMP_TS_NAME> #Create the tables and views 
needed to run XML DB   

For example:

catqm.sql change_on_install XDB TEMP

Reconnect to SYS again and run the following:

catxdbj.sql          #Load xdb java library 


Make sure that the database is started with Oracle9i Release 2 (9.2.0) compatibility or higher.

Post Installation

After the manual installation, carry out these tasks:

  1. Add the following dispatcher entry to the init.ora file:
    dispatchers="(PROTOCOL=TCP) (SERVICE=<sid>XDB)" 
  2. Restart database and listener to enable Oracle XML DB protocol access.
  3. To allow for unauthenticated access to your Oracle XML DB Repository data through HTTP, you must also unlock the ANONYMOUS user account.

Reinstalling Oracle XML DB

To reinstall Oracle XML DB, run following SQL commands connecting to SYS to drop Oracle XML DB user and tablespace:


All user data stored in Oracle XML DB Repository is also lost when you drop xdb user!

drop user xdb cascade;
alter tablespace <XDB_TS_NAME> offline; 
drop tablespace <XDB_TS_NAME> including contents; 

Install Oracle XML DB manually as described in "Installing a New Oracle XML DB Manually Without DBCA".

Upgrading an Existing Oracle XML DB Installation

Run the script, catproc.sql, as always.

As a post upgrade step, if you want Oracle XML DB functionality, you must install Oracle XML DB manually as described in "Installing a New Oracle XML DB Manually Without DBCA" .

Upgrading XML DB From Release 2 ( to Release 2 (

Oracle9i Release 2 ( patchset for the Oracle9i Release 2 (9.2) database is a required upgrade for users of Oracle XML DB Release 2 ( Oracle XML DB requires schema based XMLType tables and columns from release to be migrated to release This mandatory migration is done automatically as part of the database upgrade process. The migration is transparent except for a few restrictions.

Migrating Data From Release 2 ( to Release 2 (

If you are migrating your data, follow these important instructions:

Before the Upgrade

You must back up all your XML schema-based data that is stored as object-relational. This minimizes any data-corruption during the migration process by deleting the corrupted rows and reloading the XML from scratch.

Also, before the upgrade, you must ensure that all XML schema-based XMLType rows and columns stored as object-relational are schema-valid. In Release 2 (, Oracle XML DB did not perform rigorous checks that an XML document being inserted into a table was valid against its XML schema. However, in Release 2 (, certain aspects of data storage rely on the schema-validity of XML documents stored. For this reason, non-conforming XML documents stored using Release 2 ( may not migrate to Release 2 (

When is Data Non-Migratable to Release 2 (

There are two instances where an XML schema-based document cannot be migrated to Release 2 ( If your data falls in either of these two categories, Oracle recommends that you do the following:

  1. Save all documents conforming to the non-migrated XML schema as text XML
  2. Unregister the XML schema before upgrading
  3. Re-register the XML schema
  4. Reload the documents after the upgrade is complete.

If you try to migrate data that falls under one of the two following categories, an error is logged in the trace file for each row that fails migration.

You Cannot Migrate a Document with anyType Element in the XML Schema

The first type of XML document that cannot be migrated is one whose XML schema contains the anyType element. Due to storage limitations for anyType in Release 2 (, Oracle changed the storage format of anyType in Release 2 ( so that XML documents with one or more non-NULL anyType element cannot be migrated.

You Cannot Migrate a Document with SubTyped Element Namespace Different from its Parent Element Namespace

The second type of XML document that cannot be migrated is one whose XML schema contains a subtyped element with a namespace that differs from the namespace of its parent element. This is because in Release 2 (, Oracle XML DB required and assumed the namespace of the subtyped element to be that of its parent's namespace, and thus the real namespace of the subtyped element was lost during the storage phase. For this reason, you cannot migrate these XML schema, along with their conforming XML documents, to Release 2 (

The Release 2 ( Oracle XML DB Upgrade Process

The migration of XMLType data happens transparently within the upgrade script catpatch.sql.

See Also:

.... for instructions on running this script.

Errors occurring during Oracle XML DB migration are reported to the trace file, along with the table name and ROWID of the row for which the migration failed. If an error occurs during migration of a row, the migration script simply reports the error to the trace file and continues migrating the next row. In other words, the script is not interrupted by errors.

If all rows are successfully migrated, Oracle XML DB is ready to use once the database has been restarted.

Oracle XMl DB: Error Handling When Migrating to Release 2 (

If the trace file shows that errors occurred during migration of one or more XMLType rows, the remainder of Oracle XML DB should remain usable despite the lack of completion. If you later try to access an non-migrated row, Oracle throws an ORA-1038 error. You can delete non-migrated rows from XMLType tables without harm.

When a row is migrated and does not produce an error yet yields the row unusable after the upgrade is complete, you should delete the row then restore it using the raw XML data, assuming that a backup was taken prior to upgrade.

Even after upgrade, any XMLType table, migrated or not, can be re-run through the migration engine. This may be useful when a particular XMLType row fails to be migrated as a part of catpatch.sql, but you have since taken some action to make the migration run successfully.

Summary of Functions that Trigger Migration of a Table

Table A-1 lists the migration procedures available from XDB.DBMS_XDB package after upgrading to Release 2 (

Table A-1 XDB.DBMS_XDB Package Release 2 ( Migration Procedures
PROCEDURE Description


Migrates one XMLType column from Release 2 ( to Release 2 ( format. The column must exist inside an object table and must be of type XMLType, XML schema-based, and stored in object-relational format. An exclusive lock is taken on the table before the column is migrated.

PARAMETERS: owner (IN) - Database user who owns the XMLType table, table_name (IN) - Name of the table, column_name (IN) - Name of the XMLType column within the table, For example: "FOO"."BAR"


MigrateColumnFrom9201(owner IN VARCHAR2, table_name IN VARCHAR2, column_name IN VARCHAR2)


Migrates one XMLType table from the format to the format. The table must have XMLType as its rowtype, and the XMLType row must be schema-based and stored in object-relational format. An exclusive lock is taken on the table before it is operated on.

PARAMETERS: owner (IN) - Database user who owns the XMLType table, table_name (IN) - Name of the XMLType table.


MigrateTableFrom9201(owner IN VARCHAR2, table_name IN VARCHAR2);


Migrates all object-relational XMLType tables and XMLType columns from the format to the format. An exclusive lock is taken each table before it is operated on.




Configuring Oracle XML DB

The following sections describe how to configure Oracle XML DB. You can also configure Oracle XML DB using Oracle Enterprise Manager.

See Also:

Chapter 21, "Managing Oracle XML DB Using Oracle Enterprise Manager"

Oracle XML DB is managed through a configuration resource stored in Oracle XML DB Repository, /sys/xdbconfig.xml.

The Oracle XML DB configuration file is alterable at runtime. Simply updating the configuration file, causes a new version of the file to be generated. At the start of each session, the current version of the configuration is bound to that session. The session will use this configuration for its life, unless you invoke an explicit call to refresh to the latest configuration.

Oracle XML DB Configuration File, xdbconfig.xml

Oracle XML DB configuration is stored as an XML resource, /xdbconfig.xml conforming to the Oracle XML DB configuration XML schema:

To configure or modify the configuration of Oracle XML DB, update the /xdbconfig.xml file by inserting, removing, or editing the appropriate XML elements in xdbconfig.xml.

Oracle XML DB configuration XML schema has the following structure:

Top Level Tag <xdbconfig>

A top level tag, <xdbconfig> is divided into two sections:

The following describes the syntax:

    <sysconfig> ... </sysconfig> 
    <userconfig>  ...  </userconfig> 


The <sysconfig> section is further subdivided as follows:

    General parameters
      <protocolconfig> ... </protocolconfig> 

It stores several general parameters that apply to all Oracle XML DB, for example, the maximum age for an ACL, whether Oracle XML DB should be case sensitive, and so on.

Protocol-specific parameters are grouped inside the <protocolconfig> tag.


The <userconfig> section contains any parameters that you may want to add.


The structure of the <protocolconfig> section is as follows:

  <common> ... </common> 
  <httpconfig> ... </httpconfig> 
  <ftpconfig> ... </ftpconfig> 

Under <common> Oracle9i stores parameters that apply to all protocols, such as MIME type information. There are also HTTP and FTP specific parameters under sections <httpconfig> and <ftpconfig> respectively.


Inside <httpconfig> there is a further subsection, <webappconfig> that corresponds to Web-based applications. It includes Web application specific parameters, for example, icon name, display name for the application, list of servlets in Oracle XML DB, and so on.

See Also:

Oracle XML DB Configuration Example

The following is a sample Oracle XML DB configuration file:

Example A-1 Oracle XML DB Configuration File

<xdbconfig xmlns="" 



                    <encoding>zip file</encoding>      
                    <encoding>tar file</encoding>        



            <server-name>XDB HTTP Server</server-name>
            <servlet-realm>Basic realm="XDB"</servlet-realm>
                    <description>Servlet for accessing DBURIs</description>


Oracle XML DB Configuration API

The Oracle XML DB Configuration API can be accessed just like any other XML schema-based resource in the hierarchy. It can be accessed and manipulated using FTP, HTTP, WebDav, Oracle Enterprise Manager, or any of the resource and DOM APIs for Java or PL/SQL.

For convenience, there is a PL/SQL API provided as part of the DBMS_XDB package for configuration access. It exposes the following functions:

Get Configuration, cfg_get()

The cfg_get() function returns a copy of the configuration as an XMLType:


cfg_get() is auto-commit.

Update Configuration, cfg_update()

The cfg_update() function updates the configuration with a new one:


Example A-2 Updating the Configuration File Using cfg_update() and cfg_get()

If you have a few parameters to update in the configuration file, you can use the following:

        /xdbconfig/descendant::ftp-port/text()',   '2121'), 

If you have many parameters to update, the preceding example may prove too cumbersome. Use instead FTP, HTTP, or Oracle Enterprise Manager.

Refresh Configuration, cfg_refresh()

The cfg_refresh() function updates the configuration snapshot to correspond to the latest version on disk at that instant:


Typically, cfg_refresh() is called in one of the following scenarios: