Skip Headers
Oracle® Database PL/SQL Packages and Types Reference
10g Release 2 (10.2)

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

Go to previous page
Previous
Go to next page
Next
View PDF

129 DBMS_XMLSCHEMA

DBMS_XMLSCHEMA package provides procedures to manage XML schemas. It is created by script dbmsxsch.sql during Oracle database installation.


See Also:

Oracle XML DB Developer's Guide

This chapter contains the following topics:


Using DBMS_XMLSCHEMA

This section contains topics which relate to using the DBMS_XMLSCHEMA package.


Overview

This package provides subprograms to


Constants

The DBMS_XMLSCHEMA package uses the constants shown in following tables.

Table 129-1 DBMS_XMLSCHEMA Constants - Delete Option

Constant Type Value Description
DELETE_RESTRICT NUMBER 1 Deletion of an XML schema fails if there are any tables or XML schemas that depend on it
DELETE_INVALIDATE NUMBER 2 Deletion of an XML schema does not fail if there are tables or XML schemas that depend on it. All dependent tables and schemas are invalidated.
DELETE_CASCADE NUMBER 3 Deletion of an XML schema also drops all SQL types and default tables associated with it. SQL types are dropped only if gentypes argument was set to TRUE during registration of the XML schema. However, deletion of the XML schema fails if there are any instance documents conforming to the schema or any dependent XML schemas.
DELETE_CASCADE_FORCE NUMBER 4 This option is similar to DELETE_CASCADE except that it does not check for any stored instance documents conforming to the schema or any dependent XML schemas. Also, it ignores any errors.

Table 129-2 DBMS_XMLSCHEMA Constants - Enable Hierarchy

Constant Type Value Description
ENABLE_HIERARCHY_NONE PLS_INTEGER 1 The ENABLE_HIERARCHY procedure of the DBMS_XDBZ package will not be called on any tables created while registering that schema
ENABLE_HIERARCHY_CONTENTS PLS_INTEGER 2 The ENABLE_HIERARCHY procedure of the DBMS_XDBZ package will be called for all tables created during schema registration with hierarchy_type as DBMS_XDBZ.ENABLE_CONTENTS
ENABLE_HIERARCHY_RESMETADATA PLS_INTEGER 3 The ENABLE_HIERARCHY procedure of the DBMS_XDBZ package will be called on all tables created during schema registration with hierarchy_type as DBMS_XDBZ.ENABLE_RESMETADATA. Users should pass in DBMS_XMLSCHEMA.ENABLE_RESMETADATA for schemas they intend to use as resource metadata tables.

Table 129-3 DBMS_XMLSCHEMA Constants - Register CSID

Constant Type Value Description
REGISTER_NODOCID NUMBER 1 If a schema is registered for metadata use (using the value ENABLE_HIER_RESMETADATA for parameter enablehierarchy during registration), a column named DOCID is added to all tables created during schema registration. This constant can be used in the options argument of REGISTERSCHEMA to prevent the creation of this column if the user wishes to optimize on storage
REGISTER_CSID_NULL NUMBER -1 If user wishes to not specify the character set of the input schema document when invoking REGISTERSCHEMA, this value can be used for the csid parameter


Views

The DBMS_XMLSCHEMA package uses the views shown in Table 129-4. The columns of these views are described in detail in the Oracle Database Reference.

Table 129-4 Summary of Views used by DBMS_XMLSCHEMA

Schema Description
USER_XML_SCHEMAS All registered XML Schemas owned by the user
ALL_XML_SCHEMAS All registered XML Schemas usable by the current user
DBA_XML_SCHEMAS All registered XML Schemas in the database
DBA_XML_TABLES All XMLType tables in the system
USER_XML_TABLES All XMLType tables owned by the current user
ALL_XML_TABLES All XMLType tables usable by the current user
DBA_XML_TAB_COLS All XMLType table columns in the system
USER_XML_TAB_COLS All XMLType table columns in tables owned by the current user
ALL_XML_TAB_COLS All XMLType table columns in tables usable by the current user
DBA_XML_VIEWS All XMLType views in the system
USER_XML_VIEWS All XMlType views owned by the current user
ALL_XML_VIEWS All XMLType views usable by the current user
DBA_XML_VIEW_COLS All XMLType view columns in the system
USER_XML_VIEW_COLS All XMLType view columns in views owned by the current user
ALL_XML_VIEW_COLS All XMLType view columns in views usable by the current user


Summary of DBMS_XMLSCHEMA Subprograms

Table 129-5 DBMS_XMLSCHEMA Package Subprograms

Method Description
COMPILESCHEMA Procedure
Used to re-compile an already registered XML schema. This is useful for bringing a schema in an invalid state to a valid state.
COPYEVOLVE Procedure
Evolves registered schemas so that existing XML instances remain valid
DELETESCHEMA Procedure
Removes the schema from the database
GENERATEBEAN Procedure
Generates the Java bean code corresponding to a registered XML schema
GENERATESCHEMA Function
Generates an XML schema from an oracle type name
GENERATESCHEMAS Function
Generates several XML schemas from an oracle type name
REGISTERSCHEMA Procedures
Registers the specified schema for use by Oracle. This schema can then be used to store documents conforming to this.
REGISTERURI Procedure
Registers an XML schema specified by a URI name


COMPILESCHEMA Procedure

This procedure can be used to re-compile an already registered XML schema. This is useful for bringing a schema in an invalid state to a valid state. Can result in a ORA-31001 exception: invalid resource handle or path name.

Syntax

DBMS_XMLSCHEMA.COMPILESCHEMA(
   schemaurl IN VARCHAR2);

Parameters

Table 129-6 COMPILESCHEMA Procedure Parameters

Parameter Description
schemaurl URL identifying the schema


COPYEVOLVE Procedure

This procedure evolves registered schemas so that existing XML instances remain valid.

This procedure is accomplished in according to the following basic scenario (alternative actions are controlled by the procedure's parameters):

Syntax

DBMS_XMLSCHEMA.COPYEVOLVE(
   schemaurls       IN  XDB$STRUBG_LIST_T,
   newschemas       IN  XMLSequenceType,
   transforms       IN  XMLSequenceType :=NULL,
   preserveolddocs  IN  BOOLEAN :=FALSE,
   maptablename     IN  VARCHAR2 :=NULL,
   generatetables   IN  BOOLEAN :=TRUE,
   force            IN  BOOLEAN :=FALSE,
   schemaowners     IN  XDB$STRING_LIST_T :=NULL);

Parameters

Table 129-7 COPYEVOLVE Procedure Parameters

Parameter Description
schemaurls VARRAY of URLs of all schemas to be evolved. Should include the dependent schemas. Unless the FORCE parameter is TRUE, URLs should be in the order of dependency.
newschemas VARRAY of new schema documents. Should be specified in same order as the corresponding URLs.
transforms VARRAY of transforming XSL documents to be applied to schema-based documents. Should be specified in same order as the corresponding URLs. Optional if no transformations are required.
preserveolddocs Default is FALSE, and temporary tables with old data are dropped. If TRUE, these table are still available after schema evolution is complete.
maptabname Specifies the name of the table mapping permanent to temporary tables during the evolution process. Valid columns are:
  • SCHEMA_URL - VARCHAR2(700) - URL of schema to which this table conforms

  • SCHEMA_OWNER -VARCHAR2(30) - Owner of the schema

  • ELEMENT_NAME - VARCHAR2(256)- Element to which this table conforms

  • TAB_NAME - VARCHAR2(65) - Qualified table name: <owner_name>.<table_name>

  • COL_NAME - VARCHAR2(4000) - Name of the column (NULL for XMLType tables)

  • TEMP_TABNAME - VARCHAR2(30) - Name of temporary tables which holds data for this table.

generatetables Default is TRUE, and new tables will be generated.

If FALSE:

  • new tables will not be generated after registration of new schemas

  • preserveolddocs must be TRUE

  • maptablename must be non-NULL

force Default is FALSE.

If TRUE, ignores errors generated during schema evolution. Used when there are circular dependencies among schemas to ensure that all schemas are stored despite possible errors in registration.

schemaowners VARRAY of names of schema owners. Should be specified in same order as the corresponding URLs. Default is NULL, assuming that all schemas are owned by the current user.

Usage Notes

You should back up all schemas and documents prior to invocation because COPYEVOLVE Procedure deletes all conforming documents prior to implementing the schema evolution.


DELETESCHEMA Procedure

This procedure deletes the XML Schema specified by the URL.

Syntax

DBMS_XMLSCHEMA.DELETESCHEMA(
   schemaurl      IN  VARCHAR2,
   delete_option  IN  PLS_INTEGER := DELETE_RESTRICT);

See Also:

"XMLSCHEMA Storage and Query: Basic" chapter of the Oracle XML DB Developer's Guide

Parameters

Table 129-8 DELETESCHEMA Procedure Parameters

Parameter Description
schemaurl URL identifying the schema to be deleted

Exceptions

Table 129-9 DELETESCHEMA Procedure Exceptions

Exception Description
ORA-31001 Invalid resource handle or path name


GENERATEBEAN Procedure

This procedure can be used to generate the Java bean code corresponding to a registered XML schema.

Syntax

DBMS_XMLSCHEMA.GENERATEBEAN(
   schemaurl  IN  VARCHAR2);

Parameters

Table 129-10 GENERATEBEAN Procedure Parameters

Parameter Description
schemaurl Name identifying a registered XML schema

Exceptions

Table 129-11 GENERATEBEAN Procedure Exceptions

Exception Description
ORA-31001 Invalid resource handle or path name

Usage Notes

Note that there is also an option to generate the beans as part of the registration procedure itself (see the genbean parameter of the REGISTERSCHEMA Procedures).


GENERATESCHEMA Function

This function generates XML schema(s) from an Oracle type name. It inlines all in one schema (XMLType).


See Also:

"XMLSCHEMA Storage and Query: Advanced" chapter of the Oracle XML DB Developer's Guide

Syntax

DBMS_XMLSCHEMA.GENERATESCHEMA( 
   schemaname    IN  VARCHAR2,
   typename      IN  VARCHAR2,
   elementname   IN  VARCHAR2 := NULL,
   recurse       IN  BOOLEAN  := TRUE,
   annotate      IN  BOOLEAN  := TRUE,
   embedcoll     IN  BOOLEAN  := TRUE) 
RETURN SYS.XMLTYPE;

Parameters

Table 129-12 GENERATESCHEMA Function Parameters

Parameter Description
schemaname Name of the database schema containing the type
typename Name of the Oracle type
elementname The name of the top level element in the XML Schema. Defaults to typename.
recurse Whether or not to also generate schema for all types referred to by the type specified
annotate Whether or not to put the SQL annotations in the XML Schema
embedcoll Determines whether the collections should be embedded in the type which refers to them, or create a complextype. Cannot be FALSE if annotations are turned on

Exceptions

Table 129-13 GENERATESCHEMA Procedure Exceptions

Exception Description
ORA-31001 Invalid resource handle or path name


GENERATESCHEMAS Function

This function generates XML schema(s) from an Oracle type name. It returns a collection of XMLTypes, one XML Schema document for each database schema.


See Also:

"XMLSCHEMA Storage and Query: Advanced" chapter of the Oracle XML DB Developer's Guide

Syntax

DBMS_XMLSCHEMA.GENERATESCHEMAS( 
   schemaname   IN  VARCHAR2,
   typename     IN  VARCHAR2,
   elementname  IN  VARCHAR2 := NULL,
   schemaurl    IN  VARCHAR2 := NULL,
   annotate     IN  BOOLEAN := TRUE,
   embedcoll    IN  BOOLEAN := TRUE ) 
 RETURN SYS.XMLTYPE;

Parameters

Table 129-14 GENERATESCHEMAS Procedure Parameters

Parameter Description
schemaname Name of the database schema containing the type
typename Name of the Oracle type
elementname The name of the top level element in the XML Schema defaults to typeName
schemaurl Specifies base URL where schemas will be stored, needed by top level schema for import statement
annotate Whether or not to put the SQL annotations in the XML Schema
embedcoll Determines whether the collections be embedded in the type which refers to them, or create a complextype. Cannot be FALSE if annotations are turned on

Exceptions

Table 129-15 GENERATESCHEMAS Procedure Exceptions

Exception Description
ORA-31001 Invalid resource handle or path name


REGISTERSCHEMA Procedures

This procedure registers the specified schema for use by the database. The procedure is overloaded. The different functionality of each form of syntax is presented along with the definition.


See Also:

"XMLSCHEMA Storage and Query: Basic" chapter of the Oracle XML DB Developer's Guide

Syntax

Registers a schema specified as a VARCHAR2:

DBMS_XMLSCHEMA.REGISTERSCHEMA(
    schemaurl        IN  VARCHAR2,
    schemadoc        IN  VARCHAR2,
    local            IN  BOOLEAN := TRUE,
    gentypes         IN  BOOLEAN := TRUE,
    genbean          IN  BOOLEAN := FALSE,
    gentables        IN  BOOLEAN := TRUE,
    force            IN  BOOLEAN := FALSE,
    owner            IN  VARCHAR2 := NULL,
    enablehierarchy  IN  PLS_INTEGER := DBMS_XMLSCHEMA.ENABLE_CONTENTS,
    options          IN  PLS_INTEGER := 0);
 

Registers the schema specified as a BFILE. The contents of the schema document must be in the database character set:

DBMS_XMLSCHEMA.REGISTERSCHEMA(
   schemaurl        IN  VARCHAR2,
   schemadoc        IN  BFILE,
   local            IN  BOOLEAN := TRUE,
   gentypes         IN  BOOLEAN := TRUE,
   genbean          IN  BOOLEAN := FALSE,
   force            IN  BOOLEAN := FALSE,
   owner            IN  VARCHAR2 := NULL,
   enablehierarchy  IN  PLS_INTEGER := DBMS_XMLSCHEMA.ENABLE_CONTENTS,
   options          IN  PLS_INTEGER := 0);
 

Registers the schema specified as a BFILE and identifies the character set id of the schema document:

DBMS_XMLSCHEMA.REGISTERSCHEMA(
   schemaurl        IN  VARCHAR2, 
   schemadoc        IN  BFILE, 
   local            IN  BOOLEAN := TRUE, 
   gentypes         IN  BOOLEAN := TRUE, 
   genbean          IN  BOOLEAN := TRUE,
   gentables        IN  BOOLEAN := TRUE,
   force            IN  BOOLEAN := TRUE,
   owner            IN  VARCHAR2 := '',
   csid             IN  NUMBER,
   enablehierarchy  IN  PLS_INTEGER := DBMS_XMLSCHEMA.ENABLE_CONTENTS,
   options          IN  PLS_INTEGER := 0);
 

Registers the schema specified as a BLOB. The contents of the schema document must be in the database character set:

DBMS_XMLSCHEMA.REGISTERSCHEMA(
   schemaurl        IN  VARCHAR2, 
   schemadoc        IN  BLOB, 
   local            IN  BOOLEAN := TRUE, 
   genTypes         IN  BOOLEAN := TRUE, 
   genBean          IN  BOOLEAN := FASLE,
   force            IN  BOOLEAN := FALSE,
   owner            IN  VARCHAR2 := NULL,
   enablehierarchy  IN  PLS_INTEGER := DBMS_XMLSCHEMA.ENABLE_CONTENTS,
   options          IN  PLS_INTEGER := 0);
 

Registers the schema specified as a BLOB and identifies the character set id of the schema document:

DBMS_XMLSCHEMA.REGISTERSCHEMA(
   schemaurl        IN  VARCHAR2, 
   schemadoc        IN  BLOB, 
   local            IN  BOOLEAN := TRUE, 
   gentypes         IN  BOOLEAN := TRUE, 
   genbean          IN  BOOLEAN := TRUE,
   gentables        IN  BOOLEAN := TRUE,
   force            IN  BOOLEAN := TRUE,
   owner            IN  VARCHAR2 := '',
   csid             IN  NUMBER,
   enablehierarchy  IN  PLS_INTEGER := DBMS_XMLSCHEMA.ENABLE_CONTENTS,
   options          IN  PLS_INTEGER := 0);
 

Registers the schema specified as a CLOB

DBMS_XMLSCHEMA.REGISTERSCHEMA(
   schemaurl        IN  VARCHAR2, 
   schemadoc        IN  CLOB, 
   local            IN  BOOLEAN := TRUE, 
   gentypes         IN  BOOLEAN := TRUE, 
   genbean          IN  BOOLEAN := FALSE,
   force            IN  BOOLEAN := FALSE,
   owner            IN  VARCHAR2 := NULL,
   options          IN  PLS_INTEGER := 0);
 

Registers the schema specified as an XMLTYPE.

DBMS_XMLSCHEMA.REGISTERSCHEMA(
   schemaurl        IN  VARCHAR2, 
   schemadoc        IN  SYS.XMLTYPE, 
   local            IN  BOOLEAN := TRUE, 
   gentypes         IN  BOOLEAN := TRUE, 
   genbean          IN  BOOLEAN := FALSE,
   force            IN  BOOLEAN := FALSE,
   owner            IN  VARCHAR2 := NULL,
   enablehierarchy  IN  PLS_INTEGER := DBMS_XMLSCHEMA.ENABLE_CONTENTS,
   options          IN  PLS_INTEGER := 0);
 

Registers the schema specified as a BLOB. The contents of the schema document must be in the database character set:

DBMS_XMLSCHEMA.REGISTERSCHEMA(
   schemaurl        IN  VARCHAR2, 
   schemadoc        IN  SYS.URIType, 
   local            IN  BOOLEAN := TRUE, 
   gentypes         IN  BOOLEAN := TRUE, 
   genbean          IN  BOOLEAN := FALSE,
   force            IN  BOOLEAN := FALSE,
   owner            IN  VARCHAR2 := NULL,
   enablehierarchy  IN  PLS_INTEGER := DBMS_XMLSCHEMA.ENABLE_CONTENTS,
   options          IN  PLS_INTEGER := 0);

Parameters

Table 129-16 REGSITERSCHEMA Procedure Parameters

Parameter Description
schemaurl URL that uniquely identifies the schema document. This value is used to derive the path name of the schema document within the database hierarchy. Can be used inside schemalocation attribute of XML Schema import element.
schemadoc A valid XML schema document
local Is this a local or global schema?
  • By default, all schemas are registered as local schemas, under /sys/schemas/<username>/...

  • If a schema is registered as global, it is added under /sys/schemas/PUBLIC/...

You need write privileges on the directory to be able to register a schema as global.

gentypes Determines whether the schema compiler generates object types. By default, TRUE.
genbean Determines whether the schema compiler generates Java beans. By default, FALSE.
gentables Determines whether the schema compiler generates default tables. By default, TRUE
force If this parameter is set to TRUE, the schema registration will not raise errors. Instead, it creates an invalid XML schema object in case of any errors. By default, the value of this parameter is FALSE.
owner This parameter specifies the name of the database user owning the XML schema object. By default, the user registering the schema owns the XML schema object. This parameter can be used to register a XML schema to be owned by a different database user.
csid Identifies the character set of the input schema document. If this value is 0, the schema document's encoding is determined by the current rule for "text/xml" MIME type.
enablehierarchy
  • ENABLE_HIERARCHY_NONE - enable hierarchy will not be called on any tables created while registering that schema
  • ENABLE_HIERARCHY_CONTENTS - enable hierarchy will be called for all tables created during schema registration with hierarchy_type as DBMS_XDBZ.ENABLE_CONTENTS. This is the default.

  • ENABLE_HIERARCHY_RESMETADATA - enable hierarchy will be called on all tables created during schema registration with hierarchy_type as DBMS_XDBZ.ENABLE_RESMETADATA. Users should pass in DBMS_XMLSCHEMA.ENABLE_RESMETADATA for schemas they intend to use as resource metadata tables.

options Additional options to specify how the schema should be registered. The various options are represented as bits of an integer and the options parameter should be constructed by doing a BITOR of the desired bits. Possible bits:
  • REGISTER_NODOCID - this will suppress the creation of the DOCID column for out of line tables. This is a storage optimization which might be desirable when we do not need to join back to the document table (for example if we do not care about rewriting certain queries that could be rewritten by making use of the DOCID column)



REGISTERURI Procedure

This procedure registers an XML Schema specified by a URI name.

Syntax

DBMS_XMLSCHEMA.REGISTERURI(
   schemaurl      IN  VARCHAR2,
   schemadocuri   IN  VARCHAR2,
   local          IN  BOOLEAN := TRUE,
   gentypes       IN  BOOLEAN := TRUE,
   genbean        IN  BOOLEAN := FALSE,
   gentables      IN  BOOLEAN := TRUE,
   force          IN  BOOLEAN := FALSE,
   owner          IN  VARCHAR2 := NULL, 
   options          IN  PLS_INTEGER := 0);

Parameters

Table 129-17 REGISTERURI Procedure Parameters

Parameter Description
schemaurl Uniquely identifies the schema document. Can be used inside schemaLocation attribute of XML Schema import element.
schemadocuri Pathname (URI) corresponding to the physical location of the schema document. The URI path could be based on HTTP, FTP, DB or Oracle XML DB protocols. This function constructs a URIType instance using the urifactory - and invokes the REGISTERSCHEMA Procedures function.
local Determines whether this is a local or global schema. By default, all schemas are registered as local schemas, under /sys/schemas/ <username>/... If a schema is registered as global, it is added under /sys/schemas/PUBLIC/... The user needs write privileges on the directory to register a global schema.
gentypes Determines whether the compiler generate object types. By default, TRUE.
genbean Determines whether the compiler generate Java beans. By default, FALSE.
gentables Determines whether the compiler generate default tables. TRUE by default.
force TRUE: schema registration will not raise errors. Instead, it creates an invalid XML schema object in case of any errors. By default, the value of this parameter is FALSE.
owner This parameter specifies the name of the database user owning the XML schema object. By default, the user registering the schema owns the XML schema object. This parameter can be used to register a XML schema to be owned by a different database user.
options Additional options to specify how the schema should be registered. The various options are represented as bits of an integer and the options parameter should be constructed by doing a BITOR of the desired bits. Possible bits:
  • REGISTER_NODOCID - this will suppress the creation of the DOCID column for out of line tables. This is a storage optimization which might be desirable when we do not need to join back to the document table (for example if we do not care about rewriting certain queries that could be rewritten by making use of the DOCID column)