Release 1 (9.0.1)
Part Number A88899-01
 Home |
 Solution Area |
 Contents |
 Index |
| Oracle9i XML Reference Release 1 (9.0.1) Part Number A88899-01 |
|
XSU's PL/SQL API consists of two packages:
This API provides DB_to_XML type functionality.
The type of the query context handle. This the return type of "DBMS_ XMLQuery.newContext()".
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.
The default tag to enclose raised errors -- ERROR.
The default name for the cardinality attribute of XML elements coresponding to db. records. -- NUM
The default tag name for the element cooresponding to db. records. -- ROW
Default date mask. -- 'MM/dd/yyyy HH:mm:ss'
The ALL_ROWS parameter is to indicate that all rows are needed in the output.
Used to specifies that the output should not contain any XML metadata (for example, no DTD).
Used to specify that the generation of the DTD is desired.
Used to specify that the generation of the XML SCHEMAis desired.
Use lower cased tag names.
Use upper case tag names.
It closes/deallocates a particular query context
Generates the DTD based on the SQL query used to init.
Generates the DTD based on the SQL query used to init.
Via its arguments, this method returns the thrown exception's error code and error message (that is,
Generates the XML doc.
Generates the XML doc.
Generates the XML doc.
Generates the XML doc.
It creates a query context, and it returns the context handle.
It creates a query context, and it returns the context handle.
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.
Sets a value for a particular bind name.
Sets the name of the id attribute of the collection element's separator tag.
Sets the xml data header.
Sets the format of the generated dates in the XML doc.
Sets the tag to be used to enclose the xml error docs.
Sets the max number of rows to be converted to XML.
Sets the XML meta header.
Tells the XSU to throw the raised exceptions.
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.
Sets the name of the id attribute of the row enclosing tag.
Specifies the scalar column whose value is to be assigned to the id attribute of the row enclosing tag.
Sets the tag to be used to enclose the xml dataset.
Sets the tag to be used to enclose the xml element corresponding to a db.
Sets the number of rows to skip.
Sets the stylesheet header (that is,
Specified the case of the generated XML tags.
Registers a stylesheet to be applied to generated XML.
Registers a stylesheet to be applied to generated XML.
Sets the value of a top-level stylesheet parameter.
Removes a particular top-level stylesheet parameter.
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.
It creates a query context, and it returns the context handle.
FUNCTION newContext(sqlQuery IN VARCHAR2) RETURN ctxType
The context handle.
It creates a query context, and it returns the context handle.
FUNCTION newContext(sqlQuery IN CLOB) RETURN ctxType
The context handle.
It closes/deallocates a particular query context
PROCEDURE closeContext(ctxHdl IN ctxType)
Sets the tag to be used to enclose the xml dataset.
PROCEDURE setRowsetTag(ctxHdl IN ctxType, tag IN VARCHAR2)
Sets the tag to be used to enclose the xml element corresponding to a db. record.
PROCEDURE setRowTag(ctxHdl IN ctxType, tag IN VARCHAR2)
Sets the tag to be used to enclose the xml error docs.
PROCEDURE setErrorTag(ctxHdl IN ctxType, tag IN VARCHAR2)
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.
PROCEDURE setRowIdAttrName(ctxHdl IN ctxType, attrName IN VARCHAR2)
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).
PROCEDURE setRowIdAttrValue(ctxHdl IN ctxType, colName IN VARCHAR2)
PROCEDURE setCollIdAttrName(ctxHdl IN ctxType, attrName IN VARCHAR2)
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.
PROCEDURE useNullAttributeIndicator(ctxHdl IN ctxType, flag IN BOOLEAN)
Specified the case of the generated XML tags.
PROCEDURE setTagCase(ctxHdl IN ctxType, tCase IN NUMBER)
Sets the format of the generated dates in the XML doc. The syntax of the date format patern (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.
PROCEDURE setDateFormat(ctxHdl IN ctxType, mask IN VARCHAR2)
Sets the max number of rows to be converted to XML. By default there is no max set.
PROCEDURE setMaxRows (ctxHdl IN ctxType, rows IN NUMBER)
Sets the number of rows to skip. By default 0 rows are skipped.
PROCEDURE setSkipRows(ctxHdl IN ctxType, rows IN NUMBER)
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.
PROCEDURE setStylesheetHeader(ctxHdl IN ctxType, uri IN VARCHAR2, type IN VARCHAR2 := 'text/xsl')
Registers a stylesheet to be applied to generated XML. If a stylesheet was already registered, it gets replaced by the new one. To un-register the stylesheet pass in a null for the uri argument.
PROCEDURE setXSLT(ctxHdl IN ctxType, uri IN VARCHAR2, ref IN VARCHAR2 := null)
Registers a stylesheet to be applied to generated XML. If a stylesheet was already registered, it gets replaced by the new one. To un-register the stylesheet pass in a null or an empty string for the stylesheet argument.
PROCEDURE setXSLT(ctxHdl IN ctxType, stylesheet CLOB, ref IN VARCHAR2 := null)
ctxHdl: context handle
stylesheet: the stylesheet
ref: URL for include, import and external entities
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.
PROCEDURE setXSLTParam(ctxHdl IN ctxType, name IN VARCHAR2, value IN VARCHAR2)
ctxHdl: context handle
name: name of the top level stylesheet parameter
value: value to be assigned to the stylesheet parameter
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.
PROCEDURE removeXSLTParam(ctxHdl IN ctxType, name IN VARCHAR2, value IN VARCHAR2)
Sets a value for a particular bind name.
PROCEDURE setBindValue(ctxHdl IN ctxType, bindName IN VARCHAR2, bindValue IN VARCHAR2)
Sets the XML meta header. When set, the header is inserted at the begining 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.
PROCEDURE setMetaHeader(ctxHdl IN ctxType, header IN CLOB := null)
Sets the xml data header. The data header is an XML entity which is appended at the begining of the query-generated xml entity (ie. rowset). The two entities are enclosed by the tag specified via 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.
PROCEDURE setDataHeader(ctxHdl IN ctxType, header IN CLOB := null, tag IN VARCHAR2 := null)
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.
PROCEDURE setRaiseException(ctxHdl IN ctxType, flag IN BOOLEAN)
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. By default, the exception is not thrown.
PROCEDURE setRaiseNoRowsException(ctxHdl IN ctxType, flag IN BOOLEAN)
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.
PROCEDURE propagateOriginalException(ctxHdl IN ctxType, flag IN BOOLEAN)
Via 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.
PROCEDURE getExceptionContent(ctxHdl IN ctxType, errNo OUT NUMBER, errMsg OUT VARCHAR2)
Generates the DTD based on the SQL query used to init. the context.
FUNCTION getDTD(ctxHdl IN ctxType, withVer IN BOOLEAN := false) RETURN CLOB
The DTD.
Generates the DTD based on the SQL query used to init. the context.
PROCEDURE getDTD(ctx IN ctxType, xDoc IN CLOB, withVer IN BOOLEAN := false)
ctxHdl: context handle
xDoc: lob into which to write the generated XML doc
withVer: generate the version info?
This is a convenience function. One doesn't have to explicitly open a context and close the context. This function creates the new context, executes the query, gets the xml back and closes the context..
FUNCTION getXML(sqlQuery IN VARCHAR2, metaType IN NUMBER := NONE) RETURN CLOB
The XML document.
This is a convenience function. One doesn't have to explicitly open a context and close the context. This function creates the new context, executes the query, gets the xml back and closes the context..
FUNCTION getXML(sqlQuery IN CLOB, metaType IN NUMBER := NONE) RETURN CLOB
The XML document.
Generates the XML doc. based on the SQL query used to init. the context.
FUNCTION getXML(ctxHdl IN ctxType, metaType IN NUMBER := NONE) RETURN CLOB
The XML document.
Generates the XML doc. based on the SQL query used to init. the context.
PROCEDURE getXML(ctxHdl IN ctxType, xDoc IN CLOB, metaType IN NUMBER := NONE)
ctxHdl: context handle
xDoc: lob into which to write the generated XML doc
metaType: xml metadata type (that is, NONE, DTD, SCHEMA)
This API provides XML_to_DB type functionality.
The type of the query context handle. This the return type of "DBMS_ XMLSave.newContext()".
The default tag name for the element cooresponding to db. records. -- ROW
Default date mask. -- 'MM/dd/yyyy HH:mm:ss'
Used to specify that when mapping XML elements to DB. entities the XSU should be case sensitive.
Used to specify that when mapping XML elements to DB. entities the XSU should be case insensitive.
Clears the key column list.
Clears the update column list.
It closes/deallocates a particular save context
Deletes records specified by data from the XML document, from the table specified at the context creation time.
Deletes records specified by data from the XML document, from the table specified at the context creation time.
Via its arguments, this method returns the thrown exception's error code and error message.
Inserts the XML document into the table specified at the context creation time.
Inserts the XML document into the table specified at the context creation time.
It creates a save context, and it returns the context handle.
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.
Changes the batch size used during DML operations.
Sets the commit batch size.
Describes to the XSU the format of the dates in the XML document.
The XSU does mapping of XML elements to db.
This methods adds a column to the "key column list".
Names the tag used in the XML doc., to enclose the XML elements corresponding to db.
Adds a column to the "update column list".
Updates the table specified at the context creation time with data from the XML document.
Updates the table specified at the context creation time with data from the XML document.
It creates a save context, and it returns the context handle.
FUNCTION newContext(targetTable IN VARCHAR2) RETURN ctxType
The context handle.
It closes/deallocates a particular save context
PROCEDURE closeContext(ctxHdl IN ctxType)
Names the tag used in the XML doc., to enclose the XML elements corresponding to db. records.
PROCEDURE setRowTag(ctxHdl IN ctxType, tag IN VARCHAR2)
The XSU does mapping of XML elements to db. columns/attrs. based on the element names (xml tags). This function tells the XSU to do this match case insensitive.
PROCEDURE setIgnoreCase(ctxHdl IN ctxType, flag IN NUMBER)
Describes to the XSU the format of the dates in the XML document. The syntax of the date format patern (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.
PROCEDURE setDateFormat(ctxHdl IN ctxType, mask IN VARCHAR2)
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 behaviour is unaccepatable, then set the batch size to 1.
PROCEDURE setBatchSize(ctxHdl IN ctxType, batchSize IN NUMBER);
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.
PROCEDURE setCommitBatch(ctxHdl IN ctxType, batchSize IN NUMBER);
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.
PROCEDURE setUpdateColumn(ctxHdl IN ctxType, colName IN VARCHAR2);
Clears the update column list.
PROCEDURE clearUpdateColumnList(ctxHdl IN ctxType)
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.
PROCEDURE setKeyColumn(ctxHdl IN ctxType, colName IN VARCHAR2)
Clears the key column list.
PROCEDURE clearKeyColumnList(ctxHdl IN ctxType)
Inserts the XML document into the table specified at the context creation time.
FUNCTION insertXML(ctxHdl IN ctxType, xDoc IN VARCHAR2) RETURN NUMBER
The number of rows inserted.
Inserts the XML document into the table specified at the context creation time.
FUNCTION insertXML(ctxHdl IN ctxType, xDoc IN CLOB) RETURN NUMBER
The number of rows inserted.
Updates the table specified at the context creation time with data from the XML document.
FUNCTION updateXML(ctxHdl IN ctxType, xDoc IN VARCHAR2) RETURN NUMBER
The number of rows updated.
Updates the table specified at the context creation time with data from the XML document.
FUNCTION updateXML(ctxHdl IN ctxType, xDoc IN CLOB) RETURN NUMBER
The number of rows updated.
Deletes records specified by data from the XML document, from the table specified at the context creation time.
FUNCTION deleteXML(ctxHdl IN ctxPType, xDoc IN VARCHAR2) RETURN NUMBER
The number of rows deleted.
Deletes records specified by data from the XML document, from the table specified at the context creation time.
FUNCTION deleteXML(ctxHdl IN ctxType, xDoc IN CLOB) RETURN NUMBER
The number of rows deleted.
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.
PROCEDURE propagateOriginalException(ctxHdl IN ctxType, flag IN BOOLEAN)
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.
PROCEDURE getExceptionContent(ctxHdl IN ctxType, errNo OUT NUMBER, errMsg OUT VARCHAR2)
|
 Copyright © 2001 Oracle Corporation. All Rights Reserved. |
|