115
DBMS_XMLPARSER

Using DBMS_XMLPARSER, you can access the contents and structure of XML documents. XML describes a class of data XML document objects. It partially describes the behavior of computer programs which process them. By construction, XML documents are conforming SGML documents.

XML documents are made up of storage units called entities, which contain either parsed or unparsed data. Parsed data is made up of characters, some of which form character data, and some of which form markup. Markup encodes a description of the document's storage layout and logical structure. XML provides a mechanism to impose constraints on the storage layout and logical structure.

A software module called an XML processor is used to read XML documents and provide access to their content and structure. It is assumed that an XML processor is doing its work on behalf of another module, called the application. This PL/SQL implementation of the XML processor (or parser) follows the W3C XML specification REC-xml-19980210 and includes the required behavior of an XML processor in terms of how it must read XML data and the information it must provide to the application.

The default behavior for this PL/SQL XML parser is to build a parse tree that can be accessed by DOM APIs, validate it if a DTD is found (otherwise, it is non-validating), and record errors if an error log is specified. If parsing fails, an application error is raised.

This chapter contains the following topics:

• Summary of DBMS_XMLPARSER Subprograms

  See Also: Oracle XML DB Developer's Guide

Summary of DBMS_XMLPARSER Subprograms

Table 115-1   DBMS_XMLPARSER Package Subprograms

FREEPARSER

Frees a parser object.

Syntax

PROCEDURE freeParser(
   p Parser); 

p

(IN)

GETDOCTYPE

Returns the parsed DTD; this function must be called only after a DTD is parsed.

Syntax

FUNCTION getDoctype(
   p Parser)
RETURN DOMDocumentType; 

p

(IN)

GETDOCUMENT

Returns the document node of a DOM tree document built by the parser; this function must be called only after a document is parsed.

Syntax

FUNCTION getDocument(
   p Parser)
RETURN DOMDocument; 

p

(IN)

GETRELEASEVERSION

Returns the release version of the Oracle XML parser for PL/SQL.

Syntax

FUNCTION getReleaseVersion
RETURN VARCHAR2;

GETVALIDATIONMODE

Retrieves validation mode; TRUE for validating, FALSE otherwise.

Syntax

FUNCTION getValidationMode(
   p Parser)
RETURN BOOLEAN; 

p

(IN)

NEWPARSER

Returns a new parser instance. This function must be called before the default behavior of Parser can be changed and if other parse methods need to be used.

Syntax

FUNCTION newParser 
RETURN Parser; 

PARSE

Parses XML stored in the given URL or file. An application error is raised if parsing fails. There are several versions of this method.

FUNCTION parse(
   url VARCHAR2)
RETURN DOMDocument;

PROCEDURE parse(
   p    Parser, 
   url  VARCHAR2);

url

(IN)

p

(IN)

PARSEBUFFER

Parses XML stored in the given buffer. Any changes to the default parser behavior should be effected before calling this procedure. An application error is raised if parsing fails.

Syntax

PROCEDURE parseBuffer(
   p   Parser,
   doc VARCHAR2); 

p

(IN)

doc

(IN)

PARSECLOB

Parses XML stored in the given clob. Any changes to the default parser behavior should be effected before calling this procedure. An application error is raised if parsing fails.

Syntax

PROCEDURE parseClob(
   p   Parser,
   doc CLOB); 

p

(IN)

doc

(IN)

PARSEDTD

Parses the DTD stored in the given URL or file. Any changes to the default parser behavior should be effected before calling this procedure. An application error is raised if parsing fails.

Syntax

PROCEDURE parseDTD(
   p     Parser,
   url   VARCHAR2,
   root  VARCHAR2); 

p

(IN)

url

(IN)

root

(IN)

PARSEDTDBUFFER

Parses the DTD stored in the given buffer. Any changes to the default parser behavior should be effected before calling this procedure. An application error is raised if parsing fails.

Syntax

PROCEDURE parseDTDBuffer(
   p    Parser,
   dtd  VARCHAR2,
   root VARCHAR2); 

p

(IN)

dtd

(IN)

root

(IN)

PARSEDTDCLOB

Parses the DTD stored in the given clob. Any changes to the default parser behavior should be effected before calling this procedure. An application error is raised if parsing fails.

Syntax

PROCEDURE parseDTDClob(
   p    Parser,
   dtd  CLOB,
   root VARCHAR2);

p

(IN)

dtd

(IN)

root

(IN)

SETBASEDIR

Sets base directory used to resolve relative URLs. An application error is raised if parsing fails.

Syntax

PROCEDURE setBaseDir(
   p   Parser,
   dir VARCHAR2); 

p

(IN)

dir

(IN)

SETDOCTYPE

Sets a DTD to be used by the parser for validation. This call should be made before the document is parsed.

Syntax

PROCEDURE setDoctype(
   p   Parser,
   dtd DOMDocumentType); 

p

(IN)

dtd

(IN)

SETERRORLOG

Sets errors to be sent to the specified file.

Syntax

PROCEDURE setErrorLog(
   p        Parser,
   fileName VARCHAR2); 

p

(IN)

fileName

(IN)

SETPRESERVEWHITESPACE

Sets whitespace preserving mode.

Syntax

PROCEDURE setPreserveWhitespace(
   p   Parser,
   yes BOOLEAN); 

p

(IN)

yes

(IN)

SETVALIDATIONMODE

Sets validation mode.

Syntax

PROCEDURE setValidationMode(
   p   Parser,
   yes BOOLEAN); 

p

(IN)

yes

(IN)

SHOWWARNINGS

Turns warnings on or off.

Syntax

PROCEDURE showWarnings(
   p   Parser,
   yes BOOLEAN); 

p

(IN)

yes

(IN)