C/C++ OCI XML support examples

Question

Hi all,
I'm trying to find some simple C/C++ examples of accessing XMLType columns from OCI. I'm interested in examples that show the basics like querying an XMLType column and inserting values into an XMLType column. I'm mainly interested in examples that deal with the XMLType column when the data is stored in the database as a CLOB though I'm not sure if the client side really cares about that.
My application is based on the 9i OCI client since we still need to support that so I think that some of the newer OCI XML calls will not be available. I'm already quite familiar with programming in OCI, and I'm in the process of adding support for XML to our applicaiton so I just need some sample code that shows the basics and then hopefully I can figure things out from there.
Any help would be much appreciated.
Thanks,
Nick

Answer 1

It's possible to get XMLTYPE column in OCI without converting them to string or clob. I was able to do it by taking just the XDK headers and using only those functions declared there which are exposed by oci.dll directly. Here's the comment from my code:
<tt>
// Only calls which are defined in xmlproc.h (in xdb/include) as
// #define XmlXYZ which take an xctx as first param, and cast back
// xctx into xmlctxhead, then access the struct of function pointers,
// are accessible to a pure OCI / Instance Client app.
</tt>
Crystal clear, no? ;-)
The code below could be compiled with Instant Client augmented with xdk/include/*.h. It depends on a few classes and methods not listed (it's part of a bigger file), but if you program with OCI you should be able to replace them with something that works. It's quite rough, my own experimentation, before moving on to wrap all this messy C-code into nicer looking C++, but it shows that it can be done. Notice you need to init on Object mode, and given that it uses undocumented functions for the parsing, probably not supported at all by Oracle.
Anyways, I hope its useful to someone. --DD
PS: Sorry, looks like the forum garbles the code a little in HTML. don't know how to fix that. Maybe look at the source for the HTML.
<tt>
#include <xmlotn.h>
* \brief Replacement for official XmlSaveDom not accessible to Instant-Clients
* This method wraps calls to the unofficial XmlSaveDomVA method exposed by
* Oracle contexts, to work around the fact that XmlSaveDom is not accessible
* to applications deployed against Oracle's Instant Client runtime.
* The real XmlSaveDom may be taking advantage of more undocumented key/value
* pairs supported by underlying XmlSaveDomVA methods, to do proper error
* handling possibly, which may explain why XmlSaveDomVA does not return the
* number of bytes written, as advertised by XmlSaveDom's documentation.
static xmldocnode* myXmlLoadDom(xmlctx* xctx, xmlerr* err, ...) {
va_list v;
va_start(v, err);
xmldocnode*const rc = XmlLoadDomVA(xctx, err, v);
va_end(v);
return rc;
static xmldocnode* load_dom_from_string(
xmlctx* xctx, const char* doc_string, ub4 string_len
SystemTimer timer;
xmlerr err = XMLERR_OK;
xmldocnode*const doc = myXmlLoadDom(
xctx, &err,
"buffer", doc_string,
"buffer_length", string_len,
NULL // sentinel marking end of key/value pairs
if (err != XMLERR_OK || doc == NULL) {
cerr << "Error parsing XML string" << endl;
// throw?
cout << "loaded dom in " << timer << endl;
return doc;
static xmldocnode* load_dom_from_file(
xmlctx* xctx, const char* filename
SystemTimer timer;
xmlerr err = XMLERR_OK;
xmldocnode*const doc = myXmlLoadDom(
xctx, &err,
"file", filename,
NULL // sentinel marking end of key/value pairs
if (err != XMLERR_OK || doc == NULL) {
cerr << "Error parsing XML file " << filename << endl;
// throw?
cout << "loaded dom in " << timer << endl;
return doc;
static ubig_ora myXmlSaveDom(xmlctx* xctx, xmlerr* err, xmlnode* root, ...) {
SystemTimer timer;
va_list v;
va_start(v, root);
const ubig_ora rc = XmlSaveDomVA(xctx, err, root, v);
va_end(v);
cout << "saved dom in " << timer << endl;
return rc;
// TODO: On truncation, retry with increasingly larger heap buffer
// and re-attempt serialization.
static std::string save_dom_to_string(
xmlctx* xctx, xmlnode* root,
bool add_xmldecl = true,
ub4 indent_step = 2,
ub4 indent_level = 0,
bool prune_children = false,
const char* eol = "\n"
xmlerr err = XMLERR_OK;
const ub4 max_len = 2048;
oratext doc_string[max_len] = {0};
boolean xmldecl = add_xmldecl? TRUE: FALSE;
boolean prune = prune_children? TRUE: FALSE;
const ubig_ora byte_count = myXmlSaveDom(
xctx, &err, root,
"buffer", doc_string,
"buffer_length", max_len,
"xmldecl", xmldecl, // ignored
"prune", prune,
// Using UTF-16 yields an empty string.
// Using AL32UTF8 adds XML decl previously missing (with encoding="UTF-8")
// despite requesting no xmldecl explicitly (was ignored anyway...), but
// only if passing the doc node, not the root node.
"output_encoding", "AL32UTF8",
//"eol", eol, // LPX-00019: property "eol" unknown
"indent_step", indent_step,
"indent_level", indent_level, // ignored
NULL // sentinel marking end of key/value pairs
// Number of bytes written not returned, as advertised.
// So deduce silent truncation from the end of the string
// (nor is err set to XMLERR_SAVE_OVERFLOW...)
const bool was_truncated = doc_string[max_len - 1] == '\0'
&& doc_string[max_len - 2] != '\0';
const size_t actual_len = strlen((const char*)doc_string);
cout << "byte_count return = " << byte_count
<< "; actual length = " << actual_len
<< "; truncated = " << (was_truncated? "true": "false")
<< endl;
if (err == XMLERR_OK && actual_len > 0) {
if (was_truncated) {
cerr << "Truncation during XML serialization to a string" << endl;
return std::string((const char*)doc_string, actual_len);
return std::string();
static void xml_dom_basics_main(int argc, const char* argv[]) {
SystemTimer* disconnect_timer; // time "shutdown"
Environment env(OCI_OBJECT);
env.connect(zusername, zpassword, zdatabase);
SystemTimer timer; // don't time connecting to DB
OCIError*const errhp = env.errhp;
xmlctx*const xctx = OCIXmlDbInitXmlCtx(
env.envhp, env.svchp, errhp,
(ocixmldbparam *)0, 0
if (!xctx) {
checkerr(OCI_ERROR, errhp);
// TODO: Manipulate XML context???
// FIXME: Instant Client SDK does not ship with xml.h...
// Following call compiles (because include xmlotn.h) but doesn't link
// with Instant Client SDK, because oci.dll doesn't export this symbol.
//const boolean is_unicode = XmlIsUnicode(xctx);
** Same issue here, XmlLoadDom not available from oci.dll...
// Parse "dummy" document
xmlerr err = XMLERR_OK;
oratext doc_string[] = "<dummy/>";
xmldocnode* doc = XmlLoadDom(
xctx, &err,
"buffer", doc_string,
"buffer_length", sizeof(doc_string)-1,
"validate", TRUE,
NULL // sentinel indicating last key/value pair
if (!doc) {
cerr << "XML parsing failed: rc = " << err << endl;
// Only calls which are defined in xmlproc.h (in xdb/include) as
// #define XmlXYZ which take an xctx as first param, and cast back
// xctx into xmlctxhead, then access the struct of function pointers,
// are accessible to a pure OCI / Instance Client app.
oratext* dummy_root = 0;//[] = "dummy";
oratext* dummy_uri = 0;
xmldtdnode* dummy_dtd = 0;
xmlerr err = XMLERR_OK;
xmldocnode* doc = XmlCreateDocument(
xctx, dummy_uri, dummy_root, dummy_dtd, &err
if (!doc) {
cerr << "XML parsing failed: rc = " << err << endl;
} else {
oratext root_tag[] = "root";
xmlelemnode* root = XmlDomCreateElem(xctx, doc, root_tag);
XmlDomAppendChild(xctx, doc, root);
oratext child_tag[] = "child";
xmlelemnode* child = XmlDomCreateElem(xctx, doc, child_tag);
XmlDomAppendChild(xctx, root, child);
xmltextnode* text = XmlDomCreateText(xctx, doc, (oratext*)"foo");
XmlDomAppendChild(xctx, child, text);
// Add a second child, but without text
child = XmlDomCreateElem(xctx, doc, child_tag);
XmlDomAppendChild(xctx, root, child);
xmlelemnode* root2 = XmlDomGetDocElem(xctx, doc);
assert(root == root2);
xmlnodelist* children = XmlDomGetElemsByTag(
xctx, root, (oratext*)"child"
ub4 child_count = XmlDomGetNodeListLength(xctx, children);
if (child_count > 0) {
xmlnode* child0 = XmlDomGetNodeListItem(xctx, children, 0);
if (XmlDomHasChildNodes(xctx, child0)) {
// I assume it's text
xmlnode* text0 = XmlDomGetFirstChild(xctx, child0);
const oratext* value = XmlDomGetNodeValue(xctx, text0);
ub4 value2_length = 0;
const oratext* value2 = XmlDomGetNodeValueLen(xctx, text0, 0, 0, &value2_length);
cout << "value = " << value << "; #value2 = " << value2_length << endl;
XmlDomFreeNodeList(xctx, children);
oratext doc_string[2048];
const ubig_ora byte_count =
(*XML_CB(xctx)->XML_SAVE_DOM_VA_CB)(
//XmlSaveDomVA(
xctx, &err, root,
"buffer", doc_string,
"buffer_length", 2048,//sizeof(doc_string) - 1,
NULL
cout << "byte_count = " << byte_count << endl;
if (err == XMLERR_OK && byte_count > 0) {
doc_string[sizeof(doc_string) - 1] = '\0'; // just in case
cout << "doc = \n" << doc_string << endl;
const std::string root_string = save_dom_to_string(xctx, root);
cout << "root = \n" << root_string << endl;
const std::string doc_string = save_dom_to_string(xctx, doc, false, 2, 2, false, "\r\n");
cout << "doc = \n" << doc_string << endl;
xmldocnode* doc2 = load_dom_from_string(
xctx, doc_string.c_str(), (ub4)doc_string.size()
const std::string doc_string2 = save_dom_to_string(xctx, doc2);
cout << "doc2 = \n" << doc_string2 << endl;
XmlFreeDocument(xctx, doc);
XmlFreeDocument(xctx, doc2);
// Try accessing freed doc on purpose (Hmmm, works...)
//const std::string doc_string3 = save_dom_to_string(xctx, doc2);
//cout << "doc3 = \n" << doc_string3 << endl;
// 28 KB file. If file doesn't exist, simply prints out an error
cout << "\n\n===== Loading / parsing 28 KB XML file =====" << endl;
xmldocnode* xsd = load_dom_from_file(xctx, "georaster.xsd");
cout << "XSD = \n" << save_dom_to_string(xctx, xsd, false, 2, 2, true, "\r\n");
XmlFreeDocument(xctx, xsd);
// 1,870 KB
cout << "\n\n===== Loading / parsing 1,870 KB XML file =====" << endl;
xmldocnode* witsml1 = load_dom_from_file(
xctx, "medium.xml"
cout << "WITSML1 = \n" << save_dom_to_string(xctx, witsml1, false, 2, 2, true);
XmlFreeDocument(xctx, witsml1);
// 68,911 KB
cout << "\n\n===== Loading / parsing 68,911 KB XML file =====" << endl;
xmldocnode* witsml2 = load_dom_from_file(
xctx, "big.xml"
cout << "WITSML2 = \n" << save_dom_to_string(xctx, witsml2, false, 2, 2, true);
XmlFreeDocument(xctx, witsml2);
OCIXmlDbFreeXmlCtx(xctx);
cout << "xml_dom_basics_main: " << timer << endl;
// For some reason, disconnecting after reading a large XML file
// is very slow... Loading the 68 MB file above, in about 8 seconds,
// results in the shutdown to take around 28 seconds!!!
disconnect_timer = new SystemTimer; // time "shutdown"
cout << "\n\nDisconnecting from DB, terminating OCI environment... " << endl;
cout << "'shutdown' time: " << *disconnect_timer << endl;
delete disconnect_timer;
template <class T> T* checkxml(T* node, xmlerr err) {
xmlnode* xml_node = node;
if (!xml_node) {
throw std::runtime_error("null node");
if (err != XMLERR_OK) {
throw std::runtime_error("XML error code returned");
return node;
static void xml_dom_select_main(int argc, const char* argv[]) {
const oratext charset[] = "AL32UTF8";
Environment env(OCI_OBJECT, charset, charset);
env.connect(zusername, zpassword, zdatabase);
SystemTimer timer; // don't time connecting to DB
OCIError*const errhp = env.errhp;
xmlctx*const xctx = OCIXmlDbInitXmlCtx(
env.envhp, env.svchp, errhp,
(ocixmldbparam *)0, 0
if (!xctx) {
checkerr(OCI_ERROR, errhp);
throw std::runtime_error("Cannot initialize XML context");
// Allocate Statement Handle
OCIStmt* selecthp = 0;
checkerr(
OCIHandleAlloc(
(dvoid *) env.envhp, (dvoid **) &selecthp,
OCI_HTYPE_STMT, 0, 0
env.errhp
// Prepare Statement
const char *const sql = "SELECT id, doc FROM xml_tab";
checkerr(
OCIStmtPrepare(
selecthp, env.errhp,
(const OraText*)sql, (ub4) strlen(sql),
(ub4) OCI_NTV_SYNTAX, (ub4) OCI_DEFAULT
env.errhp
// Defines
ub4 id = 0;
OCIDefine* define_id = 0;
checkerr(
OCIDefineByPos(
selecthp, &define_id, env.errhp, 1, &id, sizeof(id), SQLT_UIN,
(dvoid *) 0, (ub2 *) 0, (ub2 *) 0, OCI_DEFAULT
env.errhp
OCIDefine* define_doc = 0;
checkerr(
OCIDefineByPos(
selecthp, &define_doc, env.errhp, 2, 0, sizeof(point_typ), SQLT_NTY,
(dvoid *) 0, (ub2 *) 0, (ub2 *) 0, OCI_DEFAULT
env.errhp
OCIType* xmltype_tdo = 0;
const oratext xmltype_name[] = "XMLTYPE";
checkerr(
OCITypeByName(
env.envhp, env.errhp, env.svchp,
0, 0, // schema name (default schema when 0)
xmltype_name, (ub4)strlen((const char*)xmltype_name),
0, 0, // version name (ignored)
OCI_DURATION_SESSION,
OCI_TYPEGET_ALL,
&xmltype_tdo // connection (service specific)
env.errhp
xmldocnode* doc = 0;
ub4 doc_size = 0;
OCIInd* p_doc_ind = 0;
ub4 doc_ind_size = 0;//(ub4)sizeof(point_ind);
checkerr(
OCIDefineObject(
define_doc, env.errhp, xmltype_tdo,
//(void**)&p_pt, &pt_size, (void**)&p_pt_ind, &pt_ind_size
(void**)&doc, 0, (void**)&p_doc_ind, 0
env.errhp
// Execute (scalar) Select Statement
checkerr(
OCIStmtExecute(
env.svchp, selecthp, env.errhp, (ub4) 0 /* specific to select... */, (ub4) 0,
(CONST OCISnapshot *) NULL, (OCISnapshot *) NULL,
OCI_DEFAULT
env.errhp,
OCI_NO_DATA // TODO: Test with a select that returns no rows,
// and specifying 0 iters, to see if it returns
// OCI_SUCCESS, or OCI_NO_DATA
// TODO: Describe the select-list.
// TODO: Fix this screwed up logic!
sword fetch_rc = OCI_NO_DATA;
size_t row_count = 0;
do {
checkerr(
fetch_rc = OCIStmtFetch2(
selecthp, env.errhp, (ub4)1,
(ub2)OCI_FETCH_NEXT, (sb4)0, (ub4)OCI_DEFAULT
env.errhp, OCI_NO_DATA
if (fetch_rc != OCI_NO_DATA) {
++row_count;
if (p_doc_ind && *p_doc_ind == OCI_IND_NULL) {
cerr << "\nXML doc#" << id << " is NULL" << endl;
continue;
cout << "\nXML doc#" << id << ":\n" << save_dom_to_string(xctx, doc) << endl;
while (fetch_rc != OCI_NO_DATA);
if (doc != NULL) {
// When last row contained no document (NULL in XMLTYPE column),
// the doc pointer is somehow reset to 0, and OCIObjectFree complains
// about it: OCI-21560: argument 3 is null, invalid, or out of range
checkerr(
OCIObjectFree(env.envhp, env.errhp, doc, 0),
env.errhp
// Necessary to free documents when selecting XMLTYPE,
// sinced used OCIObjectFree above?
//XmlFreeDocument(xctx, doc);
// Free Statement Handle
checkerr(
OCIHandleFree(selecthp, OCI_HTYPE_STMT),
env.errhp
OCIXmlDbFreeXmlCtx(xctx);
cout << "xml_dom_select_main: " << timer << endl;
static void xml_dom_insert_main(int argc, const char* argv[]) {
Environment env(OCI_OBJECT);
env.connect(zusername, zpassword, zdatabase);
SystemTimer timer; // don't time connecting to DB
OCIError*const errhp = env.errhp;
xmlctx*const xctx = OCIXmlDbInitXmlCtx(
env.envhp, env.svchp, errhp,
(ocixmldbparam *)0, 0
if (!xctx) {
checkerr(OCI_ERROR, errhp);
throw std::runtime_error("Cannot initialize XML context");
xmlerr err = XMLERR_OK;
xmldocnode* doc = checkxml(XmlCreateDocument(xctx, 0, 0, 0, &err), err);
xmlelemnode* root = checkxml(XmlDomCreateElem(xctx, doc, (oratext*)"root"), err);
XmlDomAppendChild(xctx, doc, root);
xmlattrnode* version = checkxml(XmlDomCreateAttr(xctx, doc, (oratext*)"version", (oratext*)"0.1"), err);
XmlDomAppendChild(xctx, root, version);
xmlelemnode* child = checkxml(XmlDomCreateElem(xctx, doc, (oratext*)"child"), err);
XmlDomAppendChild(xctx, root, child);
xmltextnode* text = checkxml(XmlDomCreateText(xctx, doc, (oratext*)"baz"), err);
XmlDomAppendChild(xctx, child, text);
// Add a second child, but without text
child = checkxml(XmlDomCreateElem(xctx, doc, (oratext*)"child"), err);
XmlDomAppendChild(xctx, root, child);
xmlattrnode* empty = checkxml(XmlDomCreateAttr(xctx, doc, (oratext*)"empty", (oratext*)"true"), err);
XmlDomAppendChild(xctx, child, empty);
const std::string doc_string = save_dom_to_string(xctx, doc);
cout << "doc = \n" << doc_string << endl;
// Insert this document into the DB
// Allocate Statement Handle
OCIStmt* selecthp = 0;
checkerr(
OCIHandleAlloc(
(dvoid *) env.envhp, (dvoid **) &selecthp,
OCI_HTYPE_STMT, 0, 0
env.errhp
// Prepare Statement
const char *const sql = "INSERT INTO xml_tab (id, doc) VALUES (:1, :2)";
checkerr(
OCIStmtPrepare(
selecthp, env.errhp,
(const OraText*)sql, (ub4) strlen(sql),
(ub4) OCI_NTV_SYNTAX, (ub4) OCI_DEFAULT
env.errhp
// Binds
ub4 id = 101;
OCIBind* bind_id = 0;
checkerr(
OCIBindByPos(
selecthp, &bind_id, env.errhp, 1, &id, sizeof(id), SQLT_UIN,
(dvoid *) 0, (ub2 *) 0, (ub2 *) 0, (ub4) 0, (ub4 *) 0, OCI_DEFAULT
env.errhp
OCIBind* bind_doc = 0;
checkerr(
OCIBindByPos(
selecthp, &bind_doc, env.errhp, 2, 0, sizeof(point_typ), SQLT_NTY,
(dvoid *) 0, (ub2 *) 0, (ub2 *) 0, (ub4) 0, (ub4 *) 0, OCI_DEFAULT
env.errhp
OCIType* xmltype_tdo = 0;
const oratext xmltype_name[] = "XMLTYPE";
checkerr(
OCITypeByName(
env.envhp, env.errhp, env.svchp,
0, 0, // schema name (default schema when 0)
xmltype_name, (ub4)strlen((const char*)xmltype_name),
0, 0, // version name (ignored)
OCI_DURATION_SESSION,
OCI_TYPEGET_ALL,
&xmltype_tdo // connection (service specific)
env.errhp
//xmldocnode* doc = 0;
ub4 doc_size = 0;
OCIInd doc_ind = OCI_IND_NOTNULL;
OCIInd* p_doc_ind = &doc_ind;
ub4 doc_ind_size = 0;//(ub4)sizeof(point_ind);
checkerr(
OCIBindObject(
bind_doc, env.errhp, xmltype_tdo,
//(void**)&p_pt, &pt_size, (void**)&p_pt_ind, &pt_ind_size
(void**)&doc, 0, (void**)&p_doc_ind, 0
env.errhp
// Execute (scalar) Select Statement
checkerr(
OCIStmtExecute(
env.svchp, selecthp, env.errhp, (ub4) 1, (ub4) 0,
(CONST OCISnapshot *) NULL, (OCISnapshot *) NULL,
OCI_DEFAULT
env.errhp,
OCI_NO_DATA // TODO: Test with a select that returns no rows,
// and specifying 0 iters, to see if it returns
// OCI_SUCCESS, or OCI_NO_DATA
// Commit transaction
checkerr(
OCITransCommit(env.svchp, env.errhp, 0),
env.errhp
XmlFreeDocument(xctx, doc);
OCIXmlDbFreeXmlCtx(xctx);
cout << "xml_dom_insert_main: " << timer << endl;
</tt>