Skip Headers

Oracle9i XML API Reference - XDK and Oracle XML DB
Release 2 (9.2)

Part Number A96616-01
Go To Documentation Library
Home
Go To Product List
Book List
Go To Table Of Contents
Contents
Go To Index
Index

Master Index

Feedback

Go to previous page Go to next page

26
PL/SQL Parser API for XMLType

The user can access the contents and structure of XML documents through the APIs of the DBMS_XMLPARSER Package.

This chapter discusses the following topics:


DBMS_XMLPARSER Package


Description of DBMS_XMLPARSER

The Extensible Markup Language (XML) describes a class of data objects called XML documents. It partially describes the behavior of computer programs which process them. XML is an application profile or restricted form of the Standard Generalized Markup Language (SGML). 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) followed the W3C XML specification (rev. REC-xml-19980210) and included 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 following is the default behavior for this PL/SQL XML parser:


Subprograms of DBMS_XMLPARSER

Table 26-1 Summary of Subprograms of DBMS_XMLPARSER  
Subprogram Description

parse()

Parses XML stored in the given url/file.

newParser()

Returns a new parser instance

parseBuffer()

Parses XML stored in the given buffer

parseClob()

Parses XML stored in the given clob

parseDTD()

Parses DTD stored in the given url/file

parseDTDBuffer()

Parses DTD stored in the given buffer

parseDTDClob()

Parses DTD stored in the given clob

setBaseDir()

Sets base directory used to resolve relative URLs.

showWarnings()

Turns warnings on or off.

setErrorLog()

Sets errors to be sent to the specified file

setPreserveWhitespace()

Sets white space preserve mode

setValidationMode()

Sets validation mode.

getValidationMode()

Returns validation mode.

setDoctype()

Sets DTD.

getDoctype()

Gets DTD Parser.

getDocument()

Gets DOM document.

freeParser()

Frees a parser object.

getReleaseVersion()

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

parse()

Description

Parses XML stored in the given url/file. An application error is raised if parsing fails. The options are described in the following table.

Syntax Description

FUNCTION parse(

url VARCHAR2)

RETURN DOMDocument;

Returns the built DOM Document. This is meant to be used when the default parser behavior is acceptable and just a url/file needs to be parsed.

PROCEDURE parse(

p Parser,

url VARCHAR2);

Any changes to the default parser behavior should be effected before calling this procedure.

Parameter IN / OUT Description

url

(IN)

Complete path of the url/file to be parsed.

p

(IN)

Parser instance.

newParser()

Description

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; 

parseBuffer()

Description

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); 

Parameter IN / OUT Description

p

(IN)

Parser instance.

doc

(IN)

XML document buffer to parse.

parseClob()

Description

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); 

Parameter IN / OUT Description

p

(IN)

Parser instance.

doc

(IN)

XML document buffer to parse.

parseDTD()

Description

Parses the DTD stored in the given url/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); 

Parameter IN / OUT Description

p

(IN)

Parser instance.

url

(IN)

Complete path of the url/file to be parsed.

p

(IN)

Parser instance.

parseDTDBuffer()

Description

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); 

Parameter IN / OUT Description

p

(IN)

Parser instance.

dtd

(IN)

DTD buffer to parse.

root

(IN)

Name of the root element.

parseDTDClob()

Description

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);

Parameter IN / OUT Description

p

(IN)

Parser instance.

dtd

(IN)

DTD Clob to parse.

root

(IN)

Name of the root element.

setBaseDir()

Description

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

Syntax

PROCEDURE setBaseDir( p   Parser,
                      dir VARCHAR2); 

Parameter IN / OUT Description

p

(IN)

Parser instance.

dir

(IN)

Directory used as a base directory.

showWarnings()

Description

Turns warnings on or off.

Syntax

PROCEDURE showWarnings( p   Parser,
                        yes BOOLEAN); 

Parameter IN / OUT Description

p

(IN)

Parser instance.

yes

(IN)

Mode to set: TRUE - show warnings, FALSE - don't show warnings.

setErrorLog()

Description

Sets errors to be sent to the specified file

Syntax

PROCEDURE setErrorLog( p        Parser,
                       fileName VARCHAR2); 

Parameter IN / OUT Description

p

(IN)

Parser instance.

fileName

(IN)

Complete path of the file to use as the error log.

setPreserveWhitespace()

Description

Sets whitespace preserving mode.

Syntax

PROCEDURE setPreserveWhitespace( p   Parser,
                                 yes BOOLEAN); 

Parameter IN / OUT Description

p

(IN)

Parser instance.

yes

(IN)

Mode to set: TRUE - preserve, FALSE - don't preserve.

setValidationMode()

Description

Sets validation mode.

Syntax

PROCEDURE setValidationMode( p   Parser,
                             yes BOOLEAN); 

Parameter IN / OUT Description

p

(IN)

Parser instance.

yes

(IN)

Mode to set: TRUE - validate, FALSE - don't validate.

getValidationMode()

Description

Retrieves validation mode; TRUE for validating, FALSE otherwise.

Syntax

FUNCTION getValidationMode( p Parser)
                          RETURN BOOLEAN; 

Parameter IN / OUT Description

p

(IN)

Parser instance.

setDoctype()

Description

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); 

Parameter IN / OUT Description

p

(IN)

Parser instance.

dtd

(IN)

DTD to set.

getDoctype()

Description

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

Syntax

FUNCTION getDoctype( p Parser)
                   RETURN DOMDocumentType; 

Parameter IN / OUT Description

p

(IN)

Parser instance.

getDocument()

Description

Returns the root of the 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; 

Parameter IN / OUT Description

p

(IN)

Parser instance.

freeParser()

Description

Frees a parser object.

Syntax

PROCEDURE freeParser( p Parser); 

Parameter IN / OUT Description

p

(IN)

Parser instance.

getReleaseVersion()

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

Syntax

PROCEDURE getReleaseVersion RETURN VARCHAR2;

Go to previous page Go to next page
Oracle
Copyright © 2001, 2002 Oracle Corporation.

All Rights Reserved.
Go To Documentation Library
Home
Go To Product List
Book List
Go To Table Of Contents
Contents
Go To Index
Index

Master Index

Feedback