284 XMLTYPE
XMLType
is a system-defined opaque type for handling XML data. It as predefined member functions on it to extract XML nodes and fragments.
You can create columns of XMLType
and insert XML documents into it. You can also generate XML documents as XMLType
instances dynamically using the SYS_XMLAGG SQL
function.
This chapter contains the following topics:
284.1 Summary of XMLType Subprograms
This table summarizes functions and procedures of XMLType
.
Table 284-1 XMLTYPE Subprograms
Method | Description |
---|---|
Creates a non schema based XML from the input schema based instance. |
|
Creates a schema based |
|
Static function for creating and returning an |
|
Takes a |
|
Takes a |
|
Returns the value of the |
|
Returns the value of the |
|
Returns the namespace for the top level element in a schema based document. |
|
Returns the value of the |
|
Returns the root element of the input instance. Returns |
|
Returns the XML schema URL if the input is an XML Schema based. |
|
Returns the value of the |
|
Checks if the input |
|
Returns 1 or 0 indicating if the input |
|
Checks if the input instance is schema valid according to the given schema URL. |
|
Checks if the instance has been validated against the schema. |
|
Validates the input instance according to the XML Schema. Raises error if the input instance is non-schema based. |
|
Sets the schema valid flag to avoid costly schema validation. |
|
Converts the |
|
Takes an |
|
Constructs an instance of the |
284.1.1 CREATENONSCHEMABASEDXML
This member function creates a non-schema based XML document from a schema based instance.
Syntax
MEMBER FUNCTION CREATENONSCHEMABASEDXML return XMLType deterministic;
284.1.2 CREATESCHEMABASEDXML
This member function creates a schema based XMLType
instance from a non-schema based XMLType
value.
It uses either the supplied SCHEMA
URL, or the SCHEMALOCATION
attribute of the instance.
Syntax
MEMBER FUNCTION createSchemaBasedXML( schema IN varchar2 := NULL) return XMLType deterministic;
Table 284-2 CREATESCHEMABASEDXML Subprogram Parameters
Parameter | Description |
---|---|
|
Optional XMLSchema URL used to convert the value to the specified schema. |
284.1.3 CREATEXML
This static function creates and returns an XMLType
instance. The string and CLOB
parameters used to pass in the date must contain well-formed and valid XML documents.
The options are described in the following table.
Table 284-3 CREATEXML Subprograms
Syntax | Description |
---|---|
|
Creates the |
|
Creates the |
|
This static function creates a schema-based |
|
This static function creates a schema-based |
|
Creates an XML instance from an instance of an user-defined type. |
|
Creates an XML instance from a cursor reference. You can pass in any arbitrary SQL query as a |
|
Creates an XML instance from |
|
Creates an XML instance from a |
|
Creates an XML instance from a |
Table 284-4 CREATEXML Parameters
Parameter | Description |
---|---|
|
The actual data in the form of a |
|
Optional Schema URL to be used to make the input conform to the given schema. Caution: Oracle does not support use of types generated by Schema Registration (see Oracle XML DB Developer's Guide). |
|
Flag to indicate that the instance is valid according to the given XML Schema. (Default is |
|
Flag to indicate that the input is well formed. If set, then the database would not do well formed check on the input instance. (Default is |
|
Optional element name in the case of the |
|
The character set id of input XML data. |
284.1.4 EXISTSNODE
This member function checks if the node exists.
If the XPath string is NULL
or the document is empty, then a value of 0 is returned, otherwise returns 1.
The options are described in the following table.
Syntax | Description |
---|---|
|
Given an XPath expression, checks if the XPath applied over the document can return any valid nodes. |
|
This member function uses the XPath expression with the namespace information and checks if applying the XPath returns any nodes or not. |
Table 284-5 EXISTSNODE Subprogram Parameters
Parameter | Description |
---|---|
|
The XPath expression to test. |
|
Optional namespace mapping. |
284.1.5 EXTRACT
This member function extracts an XMLType
fragment and returns an XMLType
instance containing the result nodes. If the XPath does not result in any nodes, it then returns NULL
.
The options are described in the following table.
Syntax | Description |
---|---|
|
Given an XPath expression, applies the XPath to the document and returns the fragment as an |
|
This member function applies the XPath expression and namespace mapping, over the XML data to return a |
Table 284-6 EXTRACT Subprogram Parameters
Parameter | Description |
---|---|
|
The XPath expression to apply. |
|
Optional prefix to namespace mapping information. |
284.1.6 GETBLOBVAL
This member function returns a BLOB
containing the serialized XML representation. If the BLOB
returned is temporary, it must be freed after use.
Syntax
MEMBER FUNCTION getBlobVal( csid IN NUMBER) RETURN BLOB DETERMINISTIC;
Table 284-7 GETBLOBVAL Subprogram Parameters
Parameter | Description |
---|---|
|
The desired character set ID of output |
284.1.7 GETCLOBVAL
This member function returns a CLOB
containing the serialized XML representation. If the CLOB
returned is temporary, it must be freed after use.
Syntax
MEMBER FUNCTION getClobVal() RETURN clob deterministic;
284.1.8 GETNAMESPACE
GETNAMESPACE
is a member function. It returns the namespace of the top level element in the instance. It returns NULL
if the input is a fragment or is a non-schema based instance.
Syntax
MEMBER FUNCTION getNamespace return varchar2 deterministic;
284.1.9 GETNUMBERVAL
This is a member function. It returns a numeric value, formatted from the text value pointed to by the XMLType
instance. The XMLType
must point to a valid text node that contains a numerical value.
The options are described in the following table.
Syntax
MEMBER FUNCTION getNumberVal() RETURN number deterministic;
284.1.10 GETROOTELEMENT
this member function gets the root element of the XMLType
instance. It returns NULL
if the instance is a fragment.
Syntax
MEMBER FUNCTION getRootElement return varchar2 deterministic;
284.1.11 GETSCHEMAURL
This member function returns the XML Schema URL corresponding to the XMLType
instance, if the XMLType
instance is a schema-based document. Otherwise, it returns NULL
.
Syntax
MEMBER FUNCTION getSchemaURL return varchar2 deterministic;
284.1.12 GETSTRINGVAL
This member function returns the document as a string. It returns a string containing the seralized XML representation, or in the case of text nodes, the text itself.
If the XML document exceeds the VARCHAR2
maximum size (4000), then an error is raised at run time.
Syntax
MEMBER FUNCTION getStringVal() RETURN varchar2 deterministic;
284.1.13 ISFRAGMENT
ISFRAGMENT
determines if the XMLType
instance corresponds to a well-formed document, or a fragment. It returns 1 or 0 indicating if the XMLType
instance contains a fragment or a well-formed document.
Syntax
MEMBER FUNCTION isFragment() RETURN number deterministic;
284.1.14 ISSCHEMABASED
This member function determines whether the XMLType
instance is schema-based or not. It returns 1 or 0 depending on whether the XMLType
instance is schema-based.
Syntax
MEMBER FUNCTION isSchemaBased return number deterministic;
284.1.15 ISSCHEMAVALID
This member function checks if the input instance conforms to a specified schema. I does not change the validation status of the XML instance.
If an XML Schema URL is not specified and the xml document is schema based, the conformance is checked against the XMLType
instance's own schema.
Syntax
member function isSchemaValid( schurl IN VARCHAR2 := NULL, elem IN VARCHAR2 := NULL) return NUMBER deterministic;
Table 284-8 ISSCHEMAVALID Subprogram Parameters
Parameter | IN / OUT | Description |
---|---|---|
|
|
The URL of the XML Schema against which to check conformance. |
|
|
Element of a specified schema, against which to validate. This is useful when we have a XML Schema which defines more than one top level element, and we want to check conformance against a specific one of these elements. |
284.1.16 ISSCHEMAVALIDATED
This member function returns the validation status of the XMLType
instance to tell if a schema-based instance has been actually validated against its schema. It returns 1 if the instance has been validated against the schema, 0 otherwise.
Syntax
MEMBER FUNCTION isSchemaValidated return NUMBER deterministic;
284.1.17 SCHEMAVALIDATE
This member procedure validates the XML instance against its schema, if it has not already been done.
For non-schema based documents an error is raised. If validation fails an error is raised; else, the document's status is changed to validated.
Syntax
MEMBER PROCEDURE schemaValidate( self IF OUT NOCOPY XMLType);
Table 284-9 SCHEMAVALIDATE Subprogram Parameters
Parameter | IN / OUT | Description |
---|---|---|
|
|
XML instance being validated against the schema. |
284.1.18 SETSCHEMAVALIDATED
This member function sets the VALIDATION
state of the input XML instance.
Syntax
MEMBER PROCEDURE setSchemaValidated( self IF OUT NOCOPY XMLType, flag IN BINARY_INTEGER := 1);
Table 284-10 SERTSSCHEMAVALIDATED Subprogram Parameters
Parameter | IN / OUT | Description |
---|---|---|
|
|
XML instance. |
|
|
0 - |
284.1.19 TOOBJECT
This member procedure converts the XML value to an object type using the XMLSCHEMA
mapping, if available. If a SCHEMA
is not supplied or the input is a non-schema based XML, the procedure uses cannonical mapping between elements and object type attributes.
Syntax
MEMBER PROCEDURE toObject( SELF in XMLType, object OUT "<ADT_1>", schema in varchar2 := NULL, element in varchar2 := NULL);
Table 284-11 TOOBJECT Subprogram Parameters
Parameter | IN / OUT | Description |
---|---|---|
|
|
Instance to be converted. Implicit if used as a member procedure. |
|
|
Converted object. An object instance of the required type may be passed in to this function |
|
|
Schema URL. The mapping of the |
|
|
Top-level element name. An XML Schema document does not specify the top-level element for a conforming XML instance document without this parameter. Caution: Oracle does not support use of types generated by Schema Registration (see Oracle XML DB Developer's Guide). |
284.1.20 TRANSFORM
This member function transforms the XML data using the XSL stylesheet argument and the top-level parameters passed as a string of name=value pairs
If any of the arguments other than the parammap is NULL
, then a NULL
is returned.
Syntax
MEMBER FUNCTION transform( xsl IN XMLType, parammap in varchar2 := NULL) RETURN XMLType deterministic;
Table 284-12 TRANSFORM Subprogram Parameters
Parameter | IN / OUT | Description |
---|---|---|
|
|
The XSL stylesheet describing the transformation |
|
|
Top level parameters to the XSL - string of name=value pairs |
284.1.21 XMLTYPE
This is an XMLType
constructor.
The options are described in the following table.
Table 284-13 XMLTYPE Member Subprogram Parameters
Syntax | Description |
---|---|
|
This constructor function creates an optionally schema-based |
|
This constructor function creates an optionally schema-based |
|
This constructor function creates an optionally schema-based |
|
This constructor function creates an optionally schema-based |
|
This constructor function creates an optionally schema-based |
|
This constructor function creates an optionally schema-based |
|
This constructor function creates an optionally schema-based |
Table 284-14 XMLTYPE Constructor Subprogram Parameters
Parameter | Description |
---|---|
|
The data in the form of a |
|
Optional Schema URL to be used to make the input conform to the given schema. Caution: Oracle does not support use of types generated by Schema Registration (see Oracle XML DB Developer's Guide). |
|
Indicates that the instance is valid to the given XML Schema. |
|
Indicates that the input is well formed. If set, then the database would not do well formed check on the input instance. |
|
Optional element name in the case of the |
|
The character set id of input XML data. |