All Packages Previous Next 

Parser APIs

Extensible Markup Language, abbreviated XML, describes a class of data objects called XML documents and partially describes the behavior of computer programs which process them. XML is an application profile or restricted form of SGML, the Standard Generalized Markup Language [ISO 8879]. 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 PLSQL 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 PLSQL XML parser:

The types and methods described in this document are made available by the PLSQL package xmlparser.


Types

Parser interface type

 o Parser

Functions

 o parse(VARCHAR2)
Parses xml stored in the given url/file and returns the built DOM Document
 o newParser
Returns a new parser instance
 o parse(Parser, VARCHAR2)
Parses xml stored in the given url/file
 o parseBuffer(Parser, VARCHAR2)
Parses xml stored in the given buffer
 o parseClob(Parser, CLOB)
Parses xml stored in the given clob
 o parseDTD(Parser, VARCHAR2, VARCHAR2)
Parses xml stored in the given url/file
 o parseDTDBuffer(Parser, VARCHAR2, VARCHAR2)
Parses xml stored in the given buffer
 o parseDTDClob(Parser, CLOB, VARCHAR2)
Parses xml stored in the given clob
 o setBaseDir(Parser, VARCHAR2)
Sets base directory used to resolve relative urls
 o showWarnings(Parser, BOOLEAN)
Turn warnings on or off
 o setErrorLog(Parser, VARCHAR2)
Sets errors to be sent to the specified file
 o setPreserveWhitespace(Parser, BOOLEAN)
Sets white space preserve mode
 o setValidationMode(Parser, BOOLEAN)
Sets validation mode
 o getValidationMode(Parser)
Gets validation mode
 o setDoctype(Parser, DOMDocumentType)
Sets DTD
 o getDoctype(Parser)
Gets DTD
 o getDocument(Parser)
Gets DOM document
 o freeParser(Parser)
Free a Parser object

Parser interface type description

 o TYPE Parser IS RECORD ( ID VARCHAR2(5) );

Function Prototypes

 o parse

PURPOSE

Parses xml stored in the given url/file and returns the built DOM Document.

SYNTAX

 FUNCTION parse(url VARCHAR2) RETURN DOMDocument; 

PARAMETERS

 url      (IN)-  complete path of the url/file to be parsed 

RETURNS

Nothing

COMMENTS

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

An application error is raised if parsing failed, for some reason.


 o newParser

PURPOSE

Returns a new parser instance

SYNTAX

 FUNCTION newParser RETURN Parser; 

PARAMETERS

None

RETURNS

A new parser instance

COMMENTS

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


 o parse

PURPOSE

Parses xml stored in the given url/file

SYNTAX

 PROCEDURE parse(p Parser, url VARCHAR2); 

PARAMETERS

 p        (IN)-  parser instance
 url      (IN)-  complete path of the url/file to be parsed 

RETURNS

Nothing

COMMENTS

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

An application error is raised if parsing failed, for some reason.


 o parseBuffer

PURPOSE

Parses xml stored in the given buffer

SYNTAX

 PROCEDURE parseBuffer(p Parser, doc VARCHAR2); 

PARAMETERS

 p        (IN)-  parser instance
 doc      (IN)-  xml document buffer to parse

RETURNS

Nothing

COMMENTS

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

An application error is raised if parsing failed, for some reason.


 o parseClob

PURPOSE

Parses xml stored in the given clob

SYNTAX

 PROCEDURE parseClob(p Parser, doc CLOB); 

PARAMETERS

 p        (IN)-  parser instance
 doc      (IN)-  xml document clob to parse

RETURNS

Nothing

COMMENTS

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

An application error is raised if parsing failed, for some reason.


 o parseDTD

PURPOSE

Parses the DTD stored in the given url/file

SYNTAX

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

PARAMETERS

 p        (IN)-  parser instance
 url      (IN)-  complete path of the url/file to be parsed 
 root     (IN)-  name of the root element

RETURNS

Nothing

COMMENTS

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

An application error is raised if parsing failed, for some reason.


 o parseDTDBuffer

PURPOSE

Parses the DTD stored in the given buffer

SYNTAX

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

PARAMETERS

 p        (IN)-  parser instance
 dtd      (IN)-  dtd buffer to parse
 root     (IN)-  name of the root element

RETURNS

Nothing

COMMENTS

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

An application error is raised if parsing failed, for some reason.


 o parseDTDClob

PURPOSE

Parses the DTD stored in the given clob

SYNTAX

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

PARAMETERS

 p        (IN)-  parser instance
 dtd      (IN)-  dtd clob to parse
 root     (IN)-  name of the root element

RETURNS

Nothing

COMMENTS

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

An application error is raised if parsing failed, for some reason.


 o setBaseDir

PURPOSE

Sets base directory used to resolve relative urls

SYNTAX

 PROCEDURE setBaseDir(p Parser, dir VARCHAR2); 

PARAMETERS

 p        (IN)-  parser instance
 dir      (IN)-  directory to use as base directory

RETURNS

Nothing

COMMENTS

An application error is raised if parsing failed, for some reason.


 o showWarnings

PURPOSE

Turn warnings on or off

SYNTAX

 PROCEDURE showWarnings(p Parser, yes BOOLEAN); 

PARAMETERS

 p        (IN)-  parser instance
 yes      (IN)-  mode to set: TRUE - show warnings, FALSE - don't show warnings

RETURNS

Nothing

 o setErrorLog

PURPOSE

Sets errors to be sent to the specified file

SYNTAX

 PROCEDURE setErrorLog(p Parser, fileName VARCHAR2); 

PARAMETERS

 p        (IN)-  parser instance
 fileName (IN)-  complete path of the file to use as the error log

RETURNS

Nothing

 o setPreserveWhitespace

PURPOSE

Sets whitespace preserving mode

SYNTAX

 PROCEDURE setPreserveWhitespace(p Parser, yes BOOLEAN); 

PARAMETERS

 p        (IN)-  parser instance
 yes      (IN)-  mode to set: TRUE - preserve, FALSE - don't preserve

RETURNS

Nothing

 o setValidationMode

PURPOSE

Sets validation mode

SYNTAX

 PROCEDURE setValidationMode(p Parser, yes BOOLEAN); 

PARAMETERS

 p        (IN)-  parser instance
 yes      (IN)-  mode to set: TRUE - validating, FALSE - non valid

RETURNS

Nothing

 o getValidationMode

PURPOSE

Gets validation mode

SYNTAX

 FUNCTION getValidationMode(p Parser) RETURN BOOLEAN; 

PARAMETERS

 p        (IN)-  parser instance

RETURNS

The validation mode: TRUE - validating, FALSE - non valid

 o setDoctype

PURPOSE

Sets a DTD to be used by the parser for validation

SYNTAX

 PROCEDURE setDoctype(p Parser, dtd DOMDocumentType); 

PARAMETERS

 p        (IN)-  parser instance
 dtd      (IN)-  DTD to set

RETURNS

Nothing

 o getDoctype

PURPOSE

Gets DTD - MUST be called only after a DTD is parsed

SYNTAX

 FUNCTION getDoctype(p Parser) RETURN DOMDocumentType; 

PARAMETERS

 p        (IN)-  parser instance

RETURNS

The parsed DTD

 o getDocument

PURPOSE

Gets DOM Document built by the parser - MUST be called only after a document is parsed

SYNTAX

 FUNCTION getDocument(p Parser) RETURN DOMDocument; 

PARAMETERS

 p        (IN)-  parser instance

RETURNS

The root of the DOM tree

 o freeParser

PURPOSE

Free a parser object

SYNTAX

 PROCEDURE freeParser(p Parser) 

PARAMETERS

 p        (IN)-  parser instance