Functions and Procedures of DBMS_XMLSave

Table 88-3: 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()	Via its arguments, this method returns the thrown exception's error code and error message.

newContext()

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

Closes/deallocates a particular save context

Syntax

PROCEDURE closeContext(ctxHdl IN ctxType);

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

setRowTag()

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

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

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

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

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

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

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

Clears the update column list.

Syntax

PROCEDURE clearUpdateColumnList( ctxHdl IN ctxType);

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

setPreserveWhitespace()

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

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

Clears the key column list.

Syntax

PROCEDURE clearKeyColumnList( ctxHdl IN ctxType);

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

setXSLT()

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

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

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

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

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

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

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

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.