xmlparse

A built-in function that parses the XML document passed as a parameter, and returns an image value that contains a parsed form of the document.

Syntax

xmlparse_call ::= 
      xmlparse(general_string_expression   [options_parameter])
 options_parameter ::=  [,] option option_string
 option_string ::= basic_string_expression

Description

A basic_string_expression is a sql_query_expression whose datatype is character, varchar, or java.lang.String.
A general_string_expression is a sql_query_expression whose datatype is character, varchar, or java.lang.String.
If any parameter of an xmlparse call is null, the result of the call is null.
If the general_string_expression is an all-blank string, the result of xmlparse is an empty XML document.
An xmlparse call parses the general_string_expression as an XML document and returns an image value containing the parsed document.

See Chapter 3, “XML Language and XML Query Language,”for the following topics:

Restrictions on external URL references, XML namespaces, and XML schemas.
Treatment of predefined entities and their corresponding characters: & (&), < (,), > (>), &quote; (“), and ' (;). Be careful to include the semicolon as part of the entity.
Treatment of whitspace.
Treatment of empty elements.

Option

The general format of the option_string is described in “option_strings: general format”. The options supported for the xmlparse function are:
```
dtdvalidate = {yes | no}xmlerror = {exception | null | message }
```
If dtdvalidate=yes is specified, the XML document is validated against its embedded DTD (if any). This option is for compatibility with the Java-based XQL processor of Adaptive Server Enterprise 12.5.

If dtdvalidate=no is specified, no DTD validation is performed. This is the default.
```
xmlerror = {exception | null | message}
```
For the xmlerror option, see “Exceptions” below.

Exceptions

If the value of the xml_data_expression is not valid XML, then:

If the explicit or default options specifies xmlerror=exception, an exception is raised:
```
invalid XML data
```
If the explicit or default options specifies xmlerror=null, then a null value will be returned.
If the explicit or default options specifies xmlerror=message, then a character string containing an XML element with the exception message is returned. This value is valid parsed XML.

Examples

These examples use the sample_docs table described in

As created and initialized, the text_doc column of the sample_docs table contains documents, and the image_doc column is null. You can update the image_doc columns to contain parsed XML versions of the text_doc columns:

update sample_docs
set image_doc = xmlparse(text_doc) 

(3 rows affected)

You can then apply the xmlextract function to the parsed XML documents in the image column in the same way as you apply it to the unparsed XML documents in the text column. Operations on parsed XML documents generally execute faster than on unparsed XML documents.

select name_doc,   
  xmlextract('/bookstore/book[title="History of Trenton"]/price', text_doc)    
    as extract_from_text_doc,  
  xmlextract('/bookstore/book[title="History of Trenton"]/price', image_doc)    
    as extract_from_image_doc
from sample_docs

name_doc   extract_from_text_doc  extract_from_image_doc
----------  ---------------------  ------------------------ 
bookstore   <price>55</price>     <price>55</price>               
publishers  NULL                  NULL                    
titles      NULL                  NULL       
(3 rows affected)

To illustrate the xmlerror options, this command inserts an invalid document into the sample_docs table

insert into sample_docs (name_doc, text_doc)
values ('invalid doc', '<a>unclosed element<a>)

(1 row affected)

In this example, the xmlerror options determine the treatment of invalid XML documents by the xmlparse function:

If xmlerror=exception (the default), an exception is raised:

update sample_docs
set image_doc = xmlparse(text_doc option 'xmlerror=exception')

Msg 14702, Level 16, State 0:
Line 2:
XMLPARSE(): XML parser fatal error   
  <<The input ended before all started tags were ended. Last tag started
was 'a'>> at line 1, offset 23.

If xmlerror=null, a null value is returned:

update sample_docs
set image_doc = xmlparse(text_doc option 'xmlerror=null')

select image_doc from sample_docs
where name_doc='invalid doc'
------
NULL

If xmlerror=message, then parsed XML document with the error message is returned:

update sample_docs
set image_doc = xmlparse(text_doc option 'xmlerror=message')

select xmlextract('/', image_doc) 
from sample_docs
where name_doc = 'invalid doc'
------------------------
<xml_parse_error>The input ended before all started tags were ended.  Last tag started was 'a'</xml_parse_error>

This command restores the sample_docs table to its original state:

delete from sample_docs
where name_doc='invalid doc'