121
DBMS_XSLPROCESSOR

With DBMS_XSLPROCESSOR, you can access the contents and structure of XML documents. The Extensible Stylesheet Language Transformation (XSLT) describes rules for transforming a source tree into a result tree. A transformation expressed in XSLT is called a stylesheet. The transformation specified is achieved by associating patterns with templates defined in the stylesheet. A template is instantiated to create part of the result tree. This PL/SQL implementation of the XSL processor followed the W3C XSLT working draft rev WD-xslt-19990813 and included the required behavior of an XSL processor in terms of how it must read XSLT stylesheets and the transformation it must effect.

The following is the default behavior for this PL/SQL XSL Processor:

A result tree which can be accessed by DOM APIs is built
Errors are not recorded unless an error log is specified; however, an application error will be raised if parsing fails

This chapter contains the following topics:

Summary of DBMS_XSLPROCESSOR Subprograms
See Also:

Oracle XML DB Developer's Guide

Summary of DBMS_XSLPROCESSOR Subprograms

Table 121-1 DBMS_XSLPROCESSOR Package Subprograms

Method	Description
`CLOB2FILE`	Writes content of a `CLOB` into a file.
`FREEPROCESSOR`	Frees a processor object.
`FREESTYLESHEET`	Frees a stylesheet object.
`NEWPROCESSOR`	Returns a new processor instance.
`NEWSTYLESHEET`	Creates a new stylesheet from input and reference URLs.
`PROCESSXSL`	Transforms an input XML document.
`READ2CLOB`	Reads content of the file into a `CLOB`.
`REMOVEPARAM`	Removes a top-level stylesheet parameter
`RESETPARAMS`	Resets the top-level stylesheet parameters
`SELECTNODES`	Selects nodes from a DOM tree that match apattern.
`SELECTSINGLENODE`	Selects the first node from the tree that matches a pattern.
`SETERRORLOG`	Sets errors to be sent to the specified file.
`SETPARAM`	Sets a top-level parameter in the stylesheet.
`SHOWWARNINGS`	Turns warnings on or off.
`TRANSFORMNODE`	Transforms a node in a DOM tree using a stylesheet.
`VALUEOF`	Gets the value of the first node that matches a pattern.

CLOB2FILE

Write content of a CLOB into a file.

Syntax

PROCEDURE clob2file(
   cl CLOB;
   flocation VARCHAR2,
   fname VARCHAR2,
   csid IN NUMBER:=0);

Parameter	IN / OUT	Description
clob	-	File directory
flocation	-	File directory
fname	-	File name
csid	(IN)	Character set id of the file Must be a valid Oracle id; otherwise returns an error If `0`, content of the output file will be in the database character set.

FREEPROCESSOR

Frees a Processor object.

Syntax

PROCEDURE freeProccessor(
   p Processor);

Parameter	IN / OUT	Description
p	(IN)	Processor.

FREESTYLESHEET

Frees a Stylesheet object.

Syntax

PROCEDURE freeStylesheet(
   ss Stylesheet);

Parameter	IN / OUT	Description
ss	(IN)	Stylesheet.

NEWPROCESSOR

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

Syntax

FUNCTION newProcessor
RETURN Processor;

NEWSTYLESHEET

Creates and returns a new Stylesheet instance. The options are described in the following table.

Syntax	Description
FUNCTION newStylesheet( xmldoc DOMDocument, ref VARCHAR2) RETURN Stylesheet;	Creates and returns a new stylesheet instance using the given `DOMDocument` and reference URLs.
FUNCTION newStylesheet( inp VARCHAR2, ref VARCHAR2) RETURN Stylesheet;	Creates and returns a new `Stylesheet` instance using the given input and reference URLs.

Parameter	IN / OUT	Description
xmldoc	(IN)	`DOMDocument` to use for construction.
inp	(IN)	Input URL to use for construction.
ref	(IN)	Reference URL

PROCESSXSL

Transforms input XMLDocument. Any changes to the default processor behavior should be effected before calling this procedure. An application error is raised if processing fails. The options are described in the following table.

Syntax	Description
FUNCTION processXSL( p Processor, ss Stylesheet, xmldoc DOMDocument), RETURN DOMDocumentFragment;	Transforms input `XMLDocument` using given `DOMDocument` and stylesheet, and returns the resultant document fragment.
FUNCTION processXSL( p Processor, ss Stylesheet, url VARCHAR2, RETURN DOMDocumentFragment;	Transforms input `XMLDocument` using given document as URL and the `Stylesheet`, and returns the resultant document fragment.
FUNCTION processXSL( p Processor, ss Stylesheet, clb CLOB) RETURN DOMDocumentFragment;	Transforms input `XMLDocument` using given document as `CLOB` and the `Stylesheet`, and returns the resultant document fragment.
PROCEDURE processXSL( p Processor, ss Stylesheet, xmldoc DOMDocument, dir VARCHAR2, fileName VARCHAR2);	Transforms input `XMLDocument` using given `DOMDocument` and the stylesheet, and writes the output to the specified file.
PROCEDURE processXSL( p Processor, ss Stylesheet, url VARCHAR2, dir VARCHAR2, fileName VARCHAR2);	Transforms input `XMLDocument` using given URL and the stylesheet, and writes the output to the specified file in a specified directory.
PROCEDURE processXSL( p Processor, ss Stylesheet, xmldoc DOMDocument, cl IN OUT CLOB);	Transforms input `XMLDocument` using given `DOMDocument` and the stylesheet, and writes the output to a `CLOB`.
FUNCTION processXSL( p Processor, ss Stylesheet, xmldf DOMDocumentFragment) RETURN DOMDocumentFragment;	Transforms input `XMLDocumentFragment` using given `DOMDocumentFragment` and the stylesheet, and returns the resultant document fragment.
PROCEDURE processXSL( p Processor, ss Stylesheet, xmldf DOMDocumentFragment, dir VARCHAR2, fileName VARCHAR2);	Transforms input `XMLDocumentFragment` using given `DOMDocumentFragment` and the stylesheet, and writes the output to the specified file in a specified directory.
PROCEDURE processXSL( p Processor, ss Stylesheet, xmldf DOMDocumentFragment, buf IN OUT VARCHAR2);	Transforms input `XMLDocumentFragment` using given `DOMDocumentFragment` and the stylesheet, and writes the output to a buffer.
PROCEDURE processXSL( p Processor, ss Stylesheet, xmldf DOMDocumentFragment, cl IN OUT CLOB);	Transforms input `XMLDocumentFragment` using given `DOMDocumentFragment` and the stylesheet, and writes the output to a `CLOB`.

Parameter	IN / OUT	Description
p	(IN)	`Processor` instance.
ss	(IN)	`Stylesheet` instance.
xmldoc	(IN)	XML document being transformed.
url	(IN)	URL for the information being transformed.
clb	(IN)	`CLOB` containing information to be transformed.
dir	(IN)	Directory where processing output file is saved.
fileName	(IN)	Processing output file.
cl	(IN/OUT)	`CLOB` to which the processing output is saved.
xmldf	(IN)	`XMLDocumentFragment` being transformed.

READ2CLOB

Read content of a file into a CLOB.

Syntax

FUJNCTION read2clob(
   flocation VARCHAR2,
   fname VARCHAR2,
   csid IN NUMBER:=0)
RETURN CLOB;

Parameter IN / OUT Description

Parameter	IN / OUT	Description
flocation	-	File directory
fname	-	File name
csid	(IN)	Character set id of the file Must be a valid Oracle id; otherwise returns an error If `0`, input file is assumed to be in the database character set.

flocation

File directory

fname

File name

csid

(IN)

Character set id of the file

Must be a valid Oracle id; otherwise returns an error
If 0, input file is assumed to be in the database character set.

REMOVEPARAM

Removes a top level stylesheet parameter.

Syntax

PROCEDURE removeParam(
   ss Stylesheet,
   name VARCHAR2);

Parameter	IN / OUT	Description
ss	(IN)	`Stylesheet` instance.
name	(IN)	Name of the parameter.

RESETPARAMS

Resets the top-level stylesheet parameters.

Syntax

PROCEDURE resetParams(
   ss Stylesheet);

Parameter	IN / OUT	Description
ss	(IN)	`Stylesheet` instance.

SELECTNODES

Selects nodes which match the given pattern from a DOM tree, and returns the result of the selection.

Syntax

FUNCTION selectNodes( 
   n DOMNode,
   pattern VARCHAR2)
RETURN DOMNodeList;

Parameter	IN / OUT	Description
n	(IN)	Root `DOMNode` of the tree.
pattern	(IN)	Pattern to use.

SELECTSINGLENODE

Selects the first node from the tree that matches the given pattern, and returns that node.

Syntax

FUNCTION selectSingleNode(
   n DOMNode,
   pattern VARCHAR2)
RETURN DOMNode;

Parameter	IN / OUT	Description
n	(IN)	Root `DOMNode` of the tree.
pattern	(IN)	Pattern to use.

SETERRORLOG

Sets errors to be sent to the specified file.

Syntax

PROCEDURE setErrorLog(
   p Processor,
   fileName VARCHAR2);

Parameter	IN / OUT	Description
p	(IN)	`Processor` instance.
fileName	(IN)	complete path of the file to use as the error log.

SETPARAM

Sets a top level parameter in the stylesheet. The parameter value must be a valid XPath expression. Literal string values must be quoted.

Syntax

PROCEDURE setParam(
   ss Stylesheet,
   name VARCHAR2,
   value VARCHAR2);

Parameter	IN / OUT	Description
ss	(IN)	`Stylesheet` instance.
name	(IN)	Name of the parameter.
value	(IN)	Value of the parameter.

SHOWWARNINGS

Turns warnings on (TRUE) or off (FALSE).

Syntax

PROCEDURE showWarnings(
   p Processor,
   yes BOOLEAN);

Parameter	IN / OUT	Description
p	(IN)	`Processor` instance.
yes	(IN)	Mode to set: `TRUE` to show warnings, `FALSE` otherwise

TRANSFORMNODE

Transforms a node in a DOM tree using the given stylesheet, and returns the result of the transformation as a DOMDocumentFragment.

Syntax

FUNCTION transformNode(
   n DOMNode,
   ss Stylesheet)
RETURN DOMDocumentFragment;

Parameter	IN / OUT	Description
n	(IN)	`DOMNode` to transform.
ss	(IN)	Stylesheet to use.

VALUEOF

Retrieves the value of the first node from the tree that matches the given pattern.

Syntax

PROCEDURE valueOf(
   n DOMNode,
   pattern VARCHAR2,
   val OUT VARCHAR2);

Parameter	IN / OUT	Description
n	(IN)	Node whose value is being retrieved.
pattern	(IN)	Pattern to use.
val	(OUT)	Retrieved value.

121 DBMS_XSLPROCESSOR

Summary of DBMS_XSLPROCESSOR Subprograms

Table 121-1 DBMS_XSLPROCESSOR Package Subprograms

CLOB2FILE

Syntax

FREEPROCESSOR

Syntax

FREESTYLESHEET

Syntax

NEWPROCESSOR

Syntax

NEWSTYLESHEET

PROCESSXSL

READ2CLOB

Syntax

REMOVEPARAM

Syntax

RESETPARAMS

Syntax

SELECTNODES

Syntax

SELECTSINGLENODE

Syntax

SETERRORLOG

Syntax

SETPARAM

Syntax

SHOWWARNINGS

Syntax

TRANSFORMNODE

Syntax

VALUEOF

Syntax

121
DBMS_XSLPROCESSOR