20
XML SQL Utility (XSU) for PL/SQL

XML SQL Utility (XSU) for PL/SQL consists of two packages:

• DBMS_XMLQuery Package
• DBMS_XMLSave Package

  See Also: Oracle9i XML Developer's Kits Guide - XDK Oracle9i Supplied PL/SQL Packages and Types Reference

---

DBMS_XMLQuery Package

---

Description of DBMS_XMLQuery

This API provides DB_to_XML type functionality.

---

Types of DBMS_XMLQuery

Table 20-1 Types of DBMS_XMLQuery

Type	Description
ctxType	The type of the query context handle. This is the return type of newContext().

---

Constants of DBMS_XMLQuery

Table 20-2 Constants of DBMS_XMLQuery

Constant	Description
DB_ENCODING	Used to signal that the DB character encoding is to be used.
DEFAULT_ROWSETTAG	The tag name for the element enclosing the XML generated from the result set (that is, for most cases the root node tag name) -- ROWSET.
DEFAULT_ERRORTAG	The default tag to enclose raised errors -- ERROR.
DEFAULT_ROWIDATTR	The default name for the cardinality attribute of XML elements corresponding to db. records. -- NUM
DEFAULT_ROWTAG	The default tag name for the element corresponding to db. records. -- ROW
DEFAULT_DATE_FORMAT	Default date mask. -- 'MM/dd/yyyy HH:mm:ss'
ALL_ROWS	The ALL_ROWS parameter is to indicate that all rows are needed in the output.
NONE	Used to specifies that the output should not contain any XML metadata (for example, no DTD or Schema).
DTD	Used to specify that the generation of the DTD is desired.
SCHEMA	Used to specify that the generation of the XML SCHEMA is desired.
LOWER_CASE	Use lower cased tag names.
UPPER_CASE	Use upper case tag names.

---

Functions and Procedures of DBMS_XMLQuery

Table 20-3 Summary of Functions and Procedures of DBMS_XMLQuery  

Functions/Procedures	Description
newContext()	Creates a query context and it returns the context handle.
closeContext()	Closes/deallocates a particular query context.
setRowsetTag()	Sets the tag to be used to enclose the XML dataset.
setRowTag()	Sets the tag to be used to enclose the XML element corresponding to a db.
setErrorTag()	Sets the tag to be used to enclose the XML error docs.
setRowIdAttrName()	Sets the name of the id attribute of the row enclosing tag.
setRowIdAttrValue()	Specifies the scalar column whose value is to be assigned to the id attribute of the row enclosing tag.
setCollIdAttrName()	Sets the name of the id attribute of the collection element's separator tag.
useNullAttributeIndicator()	Specifies weather to use an XML attribute to indicate NULLness.
useTypeForCollElemTag()	Tells the XSU to use the collection element's type name as the collection element tag name.
setTagCase()	Specified the case of the generated XML tags.
setDateFormat()	Sets the format of the generated dates in the XML doc.
setMaxRows()	Sets the max number of rows to be converted to XML.
setSkipRows()	Sets the number of rows to skip.
setStylesheetHeader()	Sets the stylesheet header.
setXSLT()	Registers a stylesheet to be applied to generated XML.
setXSLTParam()	Sets the value of a top-level stylesheet parameter.
removeXSLTParam()	Removes a particular top-level stylesheet parameter.
setBindValue()	Sets a value for a particular bind name.
setMetaHeader()	Sets the XML meta header.
setDataHeader()	Sets the XML data header.
setEncodingTag()	Sets the encoding processing instruction in the XML document.
setRaiseException()	Tells the XSU to throw the raised exceptions.
setRaiseNoRowsException()	Tells the XSU to throw or not to throw an OracleXMLNoRowsException in the case when for one reason or another, the XML doc generated is empty.
setSQLToXMLNameEscaping()	Turns on or off escaping of XML tags in the case that the SQL object name, which is mapped to a XML identifier, is not a valid XML identifier.
propagateOriginalException()	Tells the XSU that if an exception is raised, and is being thrown, the XSU should throw the very exception raised; rather then, wrapping it with an OracleXMLSQLException.
getExceptionContent()	Returns the thrown exception's error code and error message.
getDTD()	Generates the DTD.
getNumRowsProcessed()	Returns the number of rows processed for the query.
getVersion()	Prints the version of the XSU in use.
getXML()	Generates the XML document.

newContext()

Description

Creates a query context and it returns the context handle. The options are described in the following table.

Syntax	Description
FUNCTION newContext( sqlQuery IN VARCHAR2) RETURN ctxType	Creates a query context from a string.
FUNCTION newContext( sqlQuery IN CLOB) RETURN ctxType	Creates a query context from a CLOB.

Parameter	IN / OUT	Description
sqlQuery	(IN)	SQL query, the results of which to convert to XML.

closeContext()

Description

Closes/deallocates a particular query context

Syntax

PROCEDURE closeContext( ctxHdl IN ctxType);

Parameter	IN / OUT	Description
ctxHdl	(IN)	Context handle.

setRowsetTag()

Description

Sets the tag to be used to enclose the XML dataset.

Syntax

PROCEDURE setRowsetTag(ctxHdl IN ctxType, tag IN VARCHAR2)

Parameter	IN / OUT	Description
ctxHdl	(IN)	Context handle.
tag	(IN)	Tag name.

setRowTag()

Description

Sets the tag to be used to enclose the XML element corresponding to a db. record.

Syntax

PROCEDURE setRowTag(ctxHdl IN ctxType, tag IN VARCHAR2)

Parameter	IN / OUT	Description
ctxHdl	(IN)	Context handle.
tag	(IN)	Tag name.

setErrorTag()

Description

Sets the tag to be used to enclose the XML error docs.

Syntax

PROCEDURE setErrorTag( ctxHdl IN ctxType,
                       tag IN VARCHAR2);

Parameter	IN / OUT	Description
ctxHdl	(IN)	Context handle.
tag	(IN)	Tag name.

setRowIdAttrName()

Description

Sets the name of the id attribute of the row enclosing tag. Passing null or an empty string for the tag results the row id attribute to be omitted.

Syntax

PROCEDURE setRowIdAttrName( ctxHdl IN ctxType,
                            attrName IN VARCHAR2);

Parameter	IN / OUT	Description
ctxHdl	(IN)	Context handle.
tag	(IN)	Tag name.

setRowIdAttrValue()

Description

Specifies the scalar column whose value is to be assigned to the id attribute of the row enclosing tag. Passing null or an empty string for the colName results the row id attribute being assigned the row count value (that is, 0, 1, 2 and so on).

Syntax

PROCEDURE setRowIdAttrValue( ctxHdl IN ctxType,
                             colName IN VARCHAR2);

Parameter	IN / OUT	Description
ctxHdl	(IN)	Context handle.
colName	(IN)	Column whose value is to be assigned to the row id attribute.

setCollIdAttrName()

Description

Sets the name of the id attribute of the collection element's separator tag.

Syntax

PROCEDURE setCollIdAttrName( ctxHdl IN ctxType,
                             attrName IN VARCHAR2);

Parameter	IN / OUT	Description
ctxHdl	(IN)	Context handle.
attrName	(IN)	AttributeName.

useNullAttributeIndicator()

Description

Specified weather to use an XML attribute to indicate NULLness, or to do it by omitting the inclusion of the particular entity in the XML document.

Syntax

PROCEDURE useNullAttributeIndicator( ctxHdl IN ctxType,
                                     flag IN BOOLEAN);

Parameter	IN / OUT	Description
ctxHdl	(IN)	Context handle.
flag	(IN)	Use attribute to indicate NULL?

useTypeForCollElemTag()

Description

By default the tag name for elements of a collection is the collection's tag name followed by "_item". This method, when called with argument of TRUE, tells the XSU to use the collection element's type name as the collection element tag name.

Syntax

PROCEDURE useTypeForCollElemTag( ctxHdl IN ctxType,
                                 flag IN BOOLEAN := true);

Parameter	IN / OUT	Description
ctxHdl	(IN)	Context handle.
colName	(IN)	Turn on use of the type name?.

setTagCase()

Description

Specified the case of the generated XML tags.

Syntax

PROCEDURE setTagCase( ctxHdl IN ctxType,
                      tCase IN NUMBER);

Parameter	IN / OUT	Description
ctxHdl	(IN)	Context handle.
tCase	(IN)	The tag's case; 0=asAre, 1=lower, 2=upper.

setDateFormat()

Description

Sets the format of the generated dates in the XML doc. The syntax of the date format pattern (that is, the date mask), should conform to the requirements of the java.text.SimpleDateFormat class. Setting the mask to null or an empty string, results the use of the default mask -- DEFAULT_DATE_FORMAT.

Syntax

PROCEDURE setDateFormat( ctxHdl IN ctxType,
                         mask IN VARCHAR2);

Parameter	IN / OUT	Description
ctxHdl	(IN)	Context handle.
mask	(IN)	The date mask.

setMaxRows()

Description

Sets the max number of rows to be converted to XML. By default there is no max set.

Syntax

PROCEDURE setMaxRows ( ctxHdl IN ctxType,
                       rows IN NUMBER);

Parameter	IN / OUT	Description
ctxHdl	(IN)	Context handle.
rows	(IN)	Maximum number of rows to generate.

setSkipRows()

Description

Sets the number of rows to skip. By default 0 rows are skipped.

Syntax

PROCEDURE setSkipRows( ctxHdl IN ctxType,
                       rows IN NUMBER);

Parameter	IN / OUT	Description
ctxHdl	(IN)	Context handle.
rows	(IN)	Maximum number of rows to skip.

setStylesheetHeader()

Description

Sets the stylesheet header (that is, stylesheet processing instructions) in the generated XML doc. Note: Passing null for the uri argument will unset the stylesheet header and the stylesheet type.

Syntax

PROCEDURE setStylesheetHeader( ctxHdl IN ctxType,
                               uri IN VARCHAR2,
                               type IN VARCHAR2 := 'text/xsl');

Parameter	IN / OUT	Description
ctxHdl	(IN)	Context handle.
uri	(IN)	Stylesheet URI.
type	(IN)	Stylesheet type; defaults to "text/xsl".

setXSLT()

Description

Registers a stylesheet to be applied to generated XML. If a stylesheet was already registered, it gets replaced by the new one. The options are described in the following table.

Syntax	Description
PROCEDURE setXSLT( ctxHdl IN ctxType, uri IN VARCHAR2, ref IN VARCHAR2 := null);	To un-register the stylesheet pass in a null for the uri.
PROCEDURE setXSLT( ctxHdl IN ctxType, stylesheet CLOB, ref IN VARCHAR2 := null);	To un-register the stylesheet pass in a null or an empty string for the stylesheet.

Parameter	IN / OUT	Description
ctxHdl	(IN)	Context handle.
uri	(IN)	Stylesheet URI.
stylesheet	(IN)	Stylesheet.
ref	(IN)	URL to include, import and external entities.

setXSLTParam()

Description

Sets the value of a top-level stylesheet parameter. The parameter value is expected to be a valid XPath expression (note that string literal values would therefore have to be explicitly quoted). NOTE: if no stylesheet is registered, this method is a no op.

Syntax

PROCEDURE setXSLTParam( ctxHdl IN ctxType,
                        name IN VARCHAR2,
                        value IN VARCHAR2);

Parameter	IN / OUT	Description
ctxHdl	(IN)	Context handle.
name	(IN)	Name of the top level stylesheet parameter.
value	(IN)	Value to be assigned to the stylesheet parameter.

removeXSLTParam()

Description

Removes the value of a top-level stylesheet parameter. NOTE: if no stylesheet is registered, this method is a no op.

Syntax

PROCEDURE removeXSLTParam( ctxHdl IN ctxType,
                           name IN VARCHAR2);

Parameter	IN / OUT	Description
ctxHdl	(IN)	Context handle.
name	(IN)	Name of the top level stylesheet parameter.

setBindValue()

Description

Sets a value for a particular bind name.

Syntax

PROCEDURE setBindValue( ctxHdl IN ctxType,
                        bindName IN VARCHAR2,
                        bindValue IN VARCHAR2);

Parameter	IN / OUT	Description
ctxHdl	(IN)	Context handle.
bindName	(IN)	Bind name.
bindValue	(IN)	Bind value.

setMetaHeader()

Description

Sets the XML meta header. When set, the header is inserted at the beginning of the metadata part (DTD or XMLSchema) of each XML document generated by this object. Note that the last meta header specified is the one that is used; furthermore, passing in null for the header, parameter unsets the meta header.

Syntax

PROCEDURE setMetaHeader( ctxHdl IN ctxType, 
                         header IN CLOB := null);

Parameter	IN / OUT	Description
ctxHdl	(IN)	Context handle.
Header	(IN)	Header.

setDataHeader()

Description

Sets the XML data header. The data header is an XML entity which is appended at the beginning of the query-generated XML entity, the rowset. The two entities are enclosed by the tag specified through the docTag argument. Note that the last data header specified is the one that is used; furthermore, passing in null for the header, parameter unsets the data header.

Syntax

PROCEDURE setDataHeader( ctxHdl IN ctxType,
                   header IN CLOB := null,
                   tag IN VARCHAR2 := null);

Parameter	IN / OUT	Description
ctxHdl	(IN)	Context handle.
header	(IN)	Header.
tag	(IN)	Tag used to enclose the data header and the rowset.

setEncodingTag()

Description

Sets the encoding processing instruction in the XML document.

Syntax

PROCEDURE setEncodingTag( ctxHdl IN ctxType,
                          enc IN VARCHAR2 := DB_ENCODING);

Parameter	IN / OUT	Description
ctxHdl	(IN)	Context handle.
enc	(IN)	The encoding to use.

setRaiseException()

Description

Tells the XSU to throw the raised exceptions. If this call isn't made or if false is passed to the flag argument, the XSU catches the SQL exceptions and generates an XML doc out of the exception's message.

Syntax

PROCEDURE setRaiseException( ctxHdl IN ctxType,
                             flag IN BOOLEAN);

Parameter	IN / OUT	Description
ctxHdl	(IN)	Context handle.
flag	(IN)	Throw raised exceptions? TRUE for yes, otherwise FALSE.

setRaiseNoRowsException()

Description

Tells the XSU whether to throw an OracleXMLNoRowsException in the case when for one reason or another, the XML doc generated is empty. By default, the exception is not thrown.

Syntax

PROCEDURE setRaiseNoRowsException( ctxHdl IN ctxType,
                                   flag IN BOOLEAN);

Parameter	IN / OUT	Description
ctxHdl	(IN)	Context handle.
flag	(IN)	Throw OracleXMLNoRowsException if no data? TRUE for yes, otherwise FALSE.

setSQLToXMLNameEscaping()

Description

This turns on or off escaping of XML tags in the case that the SQL object name, which is mapped to a XML identifier, is not a valid XML identifier.

Syntax

PROCEDURE setSQLToXMLNameEscaping( ctxHdl IN ctxType,
                                   flag IN BOOLEAN := true);

Parameter	IN / OUT	Description
ctxHdl	(IN)	Context handle.
flag	(IN)	Turn on escaping? TRUE for yes, otherwise FALSE.

propagateOriginalException()

Description

Tells the XSU that if an exception is raised, and is being thrown, the XSU should throw the very exception raised; rather then, wrapping it with an OracleXMLSQLException.

Syntax

PROCEDURE propagateOriginalException( c txHdl IN ctxType,
                                      flag IN BOOLEAN);

Parameter	IN / OUT	Description
ctxHdl	(IN)	Context handle.
flag	(IN)	Propagate original exception? TRUE for yes, otherwise FALSE.

getExceptionContent()

Description

Returns the thrown exception's error code and error message through its arguments (that is, SQL error code). This is to get around the fact that the JVM throws an exception on top of whatever exception was raised; thus, rendering PL/SQL unable to access the original exception.

Syntax

PROCEDURE getExceptionContent( ctxHdl IN ctxType,
                               errNo OUT NUMBER,
                               errMsg OUT VARCHAR2);

Parameter	IN / OUT	Description
ctxHdl	(IN)	Context handle.
errNo	(IN)	Error number.
errMsg	(IN	Error message.

getDTD()

Description

Generates and returns the DTD based on the SQL query used to initialize the context. The options are described in the following table.

Syntax	Description
FUNCTION getDTD( ctxHdl IN ctxType, withVer IN BOOLEAN := false) RETURN CLOB;	Function that generates the DTD based on the SQL query used to initialize the context.
PROCEDURE getDTD( ctx IN ctxType, xDoc IN CLOB, withVer IN BOOLEAN := false);	Procedure that generates the DTD based on the SQL query used to initialize the context and xDOC in CLOB.

Parameter	IN / OUT	Description
ctxHdl	(IN)	Context handle.
withVer	(IN)	Generate the version info? TRUE for yes, otherwise FALSE.
xDoc	(IN)	Clob into which to write the generated XML doc.

getNumRowsProcessed()

Description

Return the number of rows processed for the query.

Syntax

FUNCTION getNumRowsProcessed( ctx IN ctxType) RETURN NUMBER;

Parameter	IN / OUT	Description
ctxHdl	(IN)	Context handle.

getVersion()

Description

Prints the version of the XSU in use.

Syntax

PROCEDURE getVersion();

getXML()

Description

Creates the new context, executes the query, gets the XML back and closes the context. This is a convenience function. The context doesn't have to be explicitly opened or closed. The options are described in the following table.

Syntax	Description
FUNCTION getXML( sqlQuery IN VARCHAR2, metaType IN NUMBER := NONE) RETURN CLOB;	This function uses the sqlQuery in string form.
FUNCTION getXML( sqlQuery IN CLOB, metaType IN NUMBER := NONE) RETURN CLOB;	This function uses the sqlQuery in clob form.
FUNCTION getXML( ctxHdl IN ctxType, metaType IN NUMBER := NONE); RETURN CLOB	This function generates the XML doc. based on the SQL query used to initialize the context.
PROCEDURE getXML( ctxHdl IN ctxType, xDoc IN CLOB, metaType IN NUMBER := NONE);	This procedure generates the XML doc. based on the SQL query used to initialize the context.

Parameter	IN / OUT	Description
ctxHdl	(IN)	Context handle.
sqlQuery	(IN)	SQLQuery.
metaType	(IN)	XML metadata type (NONE, DTD, or SCHEMA).
sDoc	(IN)	Clob into which to write the generated XML doc.

---

DBMS_XMLSave Package

---

Description of DBMS_XMLSave

This API provides XML_to_DB type functionality.

---

Types of DBMS_XMLSave

Table 20-4 Types of DBMS_XMLSave

Type	Description
ctxType	The type of the query context handle. The type of the query context handle. This the return type of newContext().

---

Constants of DBMS_XMLSave

Table 20-5 Constants of DBMS_XMLSave

Constant	Description
DEFAULT_ROWTAG	The default tag name for the element corresponding to db. records. -- ROW
DEFAULT_DATE_FORMAT	Default date mask. -- 'MM/dd/yyyy HH:mm:ss'
MATCH_CASE	Used to specify that when mapping XML elements to DB. entities the XSU should be case sensitive.
IGNORE_CASE	Used to specify that when mapping XML elements to DB. entities the XSU should be case insensitive.

---

Functions and Procedures of DBMS_XMLSave

Table 20-6 Summary of Functions and Procedures of DBMS_XMLSave

Functions/Procedures	Description
newContext()	Creates a save context, and returns the context handle.
closeContext()	It closes/deallocates a particular save context.
setRowTag()	Names the tag used in the XML doc., to enclose the XML elements corresponding to db.
setIgnoreCase()	The XSU does mapping of XML elements to db.
setDateFormat()	Describes to the XSU the format of the dates in the XML document.
setBatchSize()	Changes the batch size used during DML operations.
setCommitBatch()	Sets the commit batch size.
setSQLToXMLNameEscaping()	This turns on or off escaping of XML tags in the case that the SQL object name, which is mapped to a XML identifier, is not a valid XML identifier.
setUpdateColumn()	Adds a column to the "update column list".
clearUpdateColumnList()	Clears the update column list.
setPreserveWhitespace()	Tells the XSU whether to preserve whitespace or not.
setKeyColumn()	This methods adds a column to the "key column list".
clearKeyColumnList()	Clears the key column list.
setXSLT()	Registers a XSL transform to be applied to the XML to be saved.
setXSLTParam()	Sets the value of a top-level stylesheet parameter.
removeXSLTParam()	Removes the value of a top-level stylesheet parameter
insertXML()	Inserts the XML document into the table specified at the context creation time.
updateXML()	Updates the table given the XML document.
deleteXML()	Deletes records specified by data from the XML document, from the table specified at the context creation time.
propagateOriginalException()	Tells the XSU that if an exception is raised, and is being thrown, the XSU should throw the very exception raised; rather then, wrapping it with an OracleXMLSQLException.
getExceptionContent()	Returns the thrown exception's error code and error message through its arguments.

newContext()

Description

Creates a save context, and returns the context handle.

Syntax

FUNCTION newContext(t argetTable IN VARCHAR2) RETURN ctxType;

Parameter	IN / OUT	Description
targetTable	(IN)	The target table into which to load the XML doc.

closeContext()

Description

Closes/deallocates a particular save context

Syntax

PROCEDURE closeContext(ctxHdl IN ctxType);

Parameter	IN / OUT	Description
ctxHdl	(IN)	Context handle.

setRowTag()

Description

Names the tag used in the XML doc., to enclose the XML elements corresponding to db. records.

Syntax

PROCEDURE setRowTag( ctxHdl IN ctxType,
                     tag IN VARCHAR2);

Parameter	IN / OUT	Description
ctxHdl	(IN)	Context handle.
tag	(IN)	Tag name.

setIgnoreCase()

Description

The XSU does mapping of XML elements to db columns/attributes based on the element names (XML tags). This function tells the XSU to do this match case insensitive.

Syntax

PROCEDURE setIgnoreCase( ctxHdl IN ctxType,
                         flag IN NUMBER);

Parameter	IN / OUT	Description
ctxHdl	(IN)	Context handle.
flag	(IN)	Ignore tag case in the XML doc? 0=FALSE, 1=TRUE.

setDateFormat()

Description

Describes to the XSU the format of the dates in the XML document. The syntax of the date format pattern (that is, the date mask), should conform to the requirements of the java.text.SimpleDateFormat class. Setting the mask to null or an empty string, results the use of the default mask -- OracleXMLCore.DATE_FORMAT.

Syntax

PROCEDURE setDateFormat( ctxHdl IN ctxType,
                         mask IN VARCHAR2);

Parameter	IN / OUT	Description
ctxHdl	(IN)	Context handle.
mask	(IN)	The date mask.

setBatchSize()

Description

Changes the batch size used during DML operations. When performing inserts, updates or deletes, it is better to batch the operations so that they get executed in one shot rather than as separate statements. The flip side is that more memory is needed to buffer all the bind values. Note that when batching is used, a commit occurs only after a batch is executed. So if one of the statement inside a batch fails, the whole batch is rolled back. This is a small price to pay considering the performance gain; nevertheless, if this behavior is unacceptable, then set the batch size to 1.

Syntax

PROCEDURE setBatchSize( ctxHdl IN ctxType,
                        batchSize IN NUMBER);

Parameter	IN / OUT	Description
ctxHdl	(IN)	Context handle.
batchSize	(IN)	Batch size.

setCommitBatch()

Description

Sets the commit batch size. The commit batch size refers to the number or records inserted after which a commit should follow. Note that if commitBatch is < 1 or the session is in "auto-commit" mode then the XSU does not make any explicit commit's. By default the commit-batch size is 0.

Syntax

PROCEDURE setCommitBatch( ctxHdl IN ctxType,
                          batchSize IN NUMBER);

Parameter	IN / OUT	Description
ctxHdl	(IN)	Context handle.
batchSize	(IN)	Commit batch size.

setSQLToXMLNameEscaping()

Description

Turns on or off escaping of XML tags in the case that the SQL object name, which is mapped to a XML identifier, is not a valid XML identifier.

Syntax

PROCEDURE setSQLToXMLNameEscaping( ctxHdl IN ctxType,
                                   flag IN BOOLEAN := true);

Parameter	IN / OUT	Description
ctxHdl	(IN)	Context handle.
flag	(IN)	Turn on escaping?

setUpdateColumn()

Description

Adds a column to the "update column list". In case of insert, the default is to insert values to all the columns in the table; on the other hand, in case of updates, the default is to only update the columns corresponding to the tags present in the ROW element of the XML document. When the update column list is specified, the columns making up this list alone will get updated or inserted into.

Syntax

PROCEDURE setUpdateColumn( ctxHdl IN ctxType,
                           colName IN VARCHAR2);

Parameter	IN / OUT	Description
ctxHdl	(IN)	Context handle.
colName	(IN)	Column to be added to the update column list.

clearUpdateColumnList()

Description

Clears the update column list.

Syntax

PROCEDURE clearUpdateColumnList( ctxHdl IN ctxType);

Parameter	IN / OUT	Description
ctxHdl	(IN)	Context handle.

setPreserveWhitespace()

Description

Tells the XSU whether or not to preserve whitespace.

Syntax

PROCEDURE setPreserveWhitespace( ctxHdl IN ctxType,
                                 flag IN BOOLEAN := true);

Parameter	IN / OUT	Description
ctxHdl	(IN)	Context handle.
flag	(IN)	Should XSU preserve whitespace?

setKeyColumn()

Description

This methods adds a column to the "key column list". In case of update or delete, it is the columns in the key column list that make up the where clause of the update/delete statement. The key columns list must be specified before updates can be done; yet, it is only optional for delete operations.

Syntax

PROCEDURE setKeyColumn( ctxHdl IN ctxType,
                        colName IN VARCHAR2);

Parameter	IN / OUT	Description
ctxHdl	(IN)	Context handle.
colName	(IN)	Column to be added to the key column list.

clearKeyColumnList()

Description

Clears the key column list.

Syntax

PROCEDURE clearKeyColumnList( ctxHdl IN ctxType);

Parameter	IN / OUT	Description
ctxHdl	(IN)	Context handle.

setXSLT()

Description

Registers an XSL transform to be applied to the XML to be saved. If a stylesheet was already registered, it gets replaced by the new one. To un-register the stylesheet, pass in null for the URI. The options are described in the following table.

Syntax	Description
PROCEDURE setXSLT( ctxHdl IN ctxType, uri IN VARCHAR2, ref IN VARCHAR2 := null);	Passes in the stylesheet through a URI.
PROCEDURE setXSLT( ctxHdl IN ctxType, stylesheet IN CLOB, ref IN VARCHAR2 := null);	Passes in the stylesheet through a CLOB.

Parameter	IN / OUT	Description
ctxHdl	(IN)	Context handle.
uri	(IN)	URI to the stylesheet to register.
ref	(IN)	URL for include, import, and external entities.
stylesheet	(IN)	CLOB containing the stylesheet to register.

setXSLTParam()

Description

Sets the value of a top-level stylesheet parameter. The parameter is expected to be a valid XPath expression (not that string literal values would therefore have to be explicitly quoted).

Syntax

PROCEDURE setXSLTParam( ctxHdl IN ctxType,
                        name IN VARCHAR2,
                        value IN VARCHAR2);

Parameter	IN / OUT	Description
ctxHdl	(IN)	Context handle.
name	(IN)	Parameter name.
value	(IN)	Parameter value as an XPath expression

removeXSLTParam()

Description

Removes the value of a top-level stylesheet parameter.

Syntax

PROCEDURE removeXSLTParam( ctxHdl IN ctxType, 
                           name IN VARCHAR2);

Parameter	IN / OUT	Description
ctxHdl	(IN)	Context handle.
name	(IN)	Parameter name.

insertXML()

Description

Inserts the XML document into the table specified at the context creation time, and returns the number of rows inserted. The options are described in the following table.

Syntax	Description
FUNCTION insertXML( ctxHdl IN ctxType, xDoc IN VARCHAR2) RETURN NUMBER;	Passes in the xDoc parameter as a VARCHAR2.
FUNCTION insertXML( ctxHdl IN ctxType, xDoc IN CLOB) RETURN NUMBER;	Passes in the xDoc parameter as a CLOB.

Parameter	IN / OUT	Description
ctxHdl	(IN)	Context handle.
xDoc	(IN)	String containing the XML document.

updateXML()

Description

Updates the table specified at the context creation time with data from the XML document, and returns the number of rows updated. The options are described in the following table.

Syntax	Description
FUNCTION updateXML( ctxHdl IN ctxType, xDoc IN VARCHAR2) RETURN NUMBER;	Passes in the xDoc parameter as a VARCHAR2.
FUNCTION updateXML( ctxHdl IN ctxType, xDoc IN CLOB) RETURN NUMBER;	Passes in the xDoc parameter as a CLOB.

Parameter	IN / OUT	Description
ctxHdl	(IN)	Context handle.
xDoc	(IN)	String containing the XML document.

deleteXML()

Description

Deletes records specified by data from the XML document from the table specified at the context creation time, and returns the number of rows deleted. The options are described in the following table.

Syntax	Description
FUNCTION deleteXML( ctxHdl IN ctxPType, xDoc IN VARCHAR2) RETURN NUMBER;	Uses a VARCHAR2 type for the xDoc parameter.
FUNCTION deleteXML( ctxHdl IN ctxType, xDoc IN CLOB) RETURN NUMBER;	Uses a CLOB type for the xDoc parameter.

Parameter	IN / OUT	Description
ctxHdl	(IN)	Context handle.
xDoc	(IN)	String containing the XML document.

propagateOriginalException()

Description

Tells the XSU that if an exception is raised, and is being thrown, the XSU should throw the very exception raised; rather then, wrapping it with an OracleXMLSQLException.

Syntax

PROCEDURE propagateOriginalException( ctxHdl IN ctxType,
                                      flag IN BOOLEAN);

Parameter	IN / OUT	Description
ctxHdl	(IN)	Context handle.
flag	(IN)	Propagate the original exception? 0=FALSE, 1=TRUE.

getExceptionContent()

Description

Through its arguments, this method returns the thrown exception's error code and error message (that is, SQL error code) This is to get around the fact that the JVM throws an exception on top of whatever exception was raised; thus, rendering PL/SQL unable to access the original exception.

Syntax

PROCEDURE getExceptionContent( ctxHdl IN ctxType,
                               errNo OUT NUMBER,
                               errMsg OUT VARCHAR2);

Parameter	IN / OUT	Description
ctxHdl	(IN)	Context handle.
errNo	(IN)	Error number.
errMsg	(IN)	Error message.