20 Using the XML Parser for C

Prerequisites

The Oracle XML parser for C reads an XML document and uses DOM or SAX application programming interfaces (APIs) to provide programmatic access to its content and structure. You can use the parser in validating or nonvalidating mode. A pull parser is also available.

This chapter assumes that you are familiar with these technologies:

• Document Object Model (DOM). DOM is an in-memory tree representation of the structure of an XML document.

• Simple API for XML (SAX). SAX is a standard for event-based XML parsing.

• Using the XML Pull Parser for C. Pull Parser uses XML events.

• document type definition (DTD). An XML DTD defines the legal structure of an XML document.

• XML Schema. Like a DTD, an XML schema defines the legal structure of an XML document.

• XML Namespaces. Namespaces are a mechanism for differentiating element and attribute names.

If you require a general introduction to the preceding technologies, consult the XML resources listed in "Related Documents."

Standards and Specifications

XML 1.0 is a W3C Recommendation. The Oracle XML Developer's Kit (XDK) for C API provides full support for XML 1.0 (Second Edition). You can find the specification for the Second Edition here:

http://www.w3.org/TR/2000/REC-xml-20001006

The DOM Level 1, Level 2, and Level 3 specifications are World Wide Web Consortium (W3C) Recommendations. The XDK for C API provides full support for DOM Level 1 and 2, but no support for Level 3. You can find links to the specifications for all three levels here:

http://www.w3.org/DOM/DOMTR

SAX is available in version 1.0, which is deprecated, and 2.0. SAX is not a W3C specification. The XDK for C API provides full support for both SAX 1.0 and 2.0. You can find the documentation for SAX here:

http://www.saxproject.org

XML Namespaces are a W3C Recommendation. You can find the specification here:

http://www.w3.org/TR/REC-xml-names

Overview of the Parser API for C

The core of the XML parsing API are the XML, DOM, and SAX APIs. Table 20-1 describes the interfaces for these APIs. See Oracle Database XML C API Reference for the complete API documentation.

XML Parser for C Calling Sequence

Figure 20-1 shows the calling sequence for the XML parser for C.

Figure 20-1 XML Parser for C Calling Sequence

Description of "Figure 20-1 XML Parser for C Calling Sequence"

Using the XML Parser for C: Basic Process

Perform these steps in your application:

1. Initialize the parsing process with the XmlCreate() function. The following sample code fragment is from DOMNamespace.c:

   xmlctx     *xctx;
   ...
   xctx = XmlCreate(&ecode, (oratext *) "namespace_xctx", NULL);
   

2. Parse the input item, which can be an XML document or string buffer.

   If you are parsing with DOM, invoke the XmlLoadDom() function. The following sample code fragment is from DOMNamespace.c:

   xmldocnode *doc;
   ...
   doc = XmlLoadDom(xctx, &ecode, "file", DOCUMENT,
                    "validate", TRUE, "discard_whitespace", TRUE, NULL);
   

   If you are parsing with SAX, invoke the XmlLoadSax() function. The following sample code fragment is from SAXNamespace.c:

   xmlerr      ecode;
   ...
   ecode = XmlLoadSax(xctx, &sax_callback, &sc, "file", DOCUMENT,
                      "validate", TRUE, "discard_whitespace", TRUE, NULL);
   

   If you are using the pull parser, then include these steps to create the event context and load the document to parse:

   evctx = XmlEvCreatePPCtx(xctx, &xerr, NULL);
   XmlEvLoadPPDoc(xctx, evctx, "File", input_filenames[i], 0, NULL);
   

3. If you are using the DOM interface, then include these steps:

   • Use the XmlLoadDom() function to invoke XmlDomGetDocElem(). This step invokes other DOM functions, which are typically node or print functions that output the DOM document, as required. The following sample code fragment is from DOMNamespace.c:

     printElements(xctx, XmlDomGetDocElem(xctx, doc));
     

   • Invoke the XmlFreeDocument() function to clean up any data structures created during the parse process. The following sample code fragment is from DOMNamespace.c:

     XmlFreeDocument(xctx, doc);
     

   If you are using the SAX interface, then include these steps:

   • Process the results of the invocation of XmlLoadSax() with a callback function, such as:

     xmlsaxcb saxcb = {
      UserStartDocument,  /* user's own callback functions */
      UserEndDocument,
      /* ... */
     }; 
     
     if (XmlLoadSax(xctx, &saxcb, NULL, "file", "some_file.xml", NULL) != 0)
       /* an error occured */
     

   • Register the callback functions. You can set any of the SAX callback functions to NULL if not needed.

   If you are using the pull parser, iterate over the events using:

   cur_event = XmlEvNext(evctx);
   

   Use the Get APIs to get information about that event.

4. Use XmlFreeDocument() to clean up the memory and structures used during a parse. The program does not free memory allocated for parameters passed to the SAX callbacks or for nodes and data stored with the DOM parse tree until you invoke XMLFreeDocument() or XMLDestroy(). The following sample code fragment is from DOMNamespace.c:

   XmlFreeDocument(xctx, doc);
   

   Either return to Step 2 or proceed to the next step.

   For the pull parser invoke XmlEvCleanPPCtx() to release memory and structures used during the parse. The application can invoke XmlEvLoadPPDoc() again to parse another document. Or, it can invoke XMLEvDestroyPPCtx() after which the pull parser context cannot be used again.

   XmlEvCleanPPCtx(xctx, evctx);
   ...
   XmlEvDestroyPPCtx(xctx, evctx);
   

5. Terminate the parsing process with XmlDestroy(). The following sample code fragment is from DOMNamespace.c:

   (void) XmlDestroy(xctx);
   

   If threads fork off somewhere in the sequence of invocations between initialization and termination, the application produces unpredictable behavior and results.

You can use the memory callback functions XML_ALLOC_F and XML_FREE_F for your own memory allocation. If you do, then specify both functions.

Running the XML Parser for C Demo Programs

The $ORACLE_HOME/xdk/demo/c/ (UNIX) and %ORACLE_HOME%\xdk\demo\c (Windows) directories include several XML applications that show how to use the XML parser for C with the DOM and SAX interfaces. Table 20-3 describes the demos.

The make utility compiles the source file fileName.c to produce the demo program fileName and the output file fileName.out . The fileName.std is the expected output.

DOMNamespace.c
DOMSample.c
FullDom.c
FullDom.xml
NSExample.xml
Traverse.c
XPointer.c
class.xml
cleo.xml
pantry.xml

NSExample.xml
SAXNamespace.c
SAXSample.c
cleo.xml

You can find documentation that describes how to compile and run the sample programs in the README in the same directory. The basic steps are:

1. Change into the $ORACLE_HOME/xdk/demo/c directory (UNIX) or %ORACLE_HOME%\xdk\demo\c directory (Windows).

2. Make sure that your environment variables are set as described in "Setting XDK for C Environment Variables on UNIX" and "Setting XDK for C Environment Variables on Windows."

3. Run make (UNIX) or Make.bat (Windows) at the system prompt. The make utility changes into each demo subdirectory and runs make to do this:

   1. Compiles the C source files with the cc utility. For example, the Makefile in the $ORACLE_HOME/xdk/demo/c/dom directory includes these line:

      $(CC) -o DOMSample $(INCLUDE) $@.c $(LIB)
      

   2. Runs each demo program and redirects the output to a file. For example, the Makefile in the $ORACLE_HOME/xdk/demo/c/dom directory includes this line:

      ./DOMSample > DOMSample.out
      

4. Compare the *.std files to the *.out files for each program. The *.std file contains the expected output for each program. For example, DOMSample.std contains the expected output from running DOMSample.

Using the C XML Parser Command-Line Utility

The xml utility, which is located in $ORACLE_HOME/bin (UNIX) or %ORACLE_HOME%\bin (Windows), is a command-line interface that parses XML documents. It checks for both well-formedness and validity.

To use xml ensure that your environment is set up as described in "Setting XDK for C Environment Variables on UNIX" and "Setting XDK for C Environment Variables on Windows."

Use this syntax on the command line to invoke xml. Use xml.exe for Windows:

xml [options] [document URI]
xml -f [options] [document filespec]

Table 20-4 describes the command-line options.

ELEMENT       1
 PCDATA       1
    DOC       1
  TOTAL       3 * 60 = 180

+---ELEMENT greeting 
    +---PCDATA "hello"

<greeting>hello</greeting>

StartDocument
XMLDECL version='1.0' encoding=FALSE
<greeting>
    "hello"
</greeting>
EndDocument

<!DOCTYPE doc [
<!ELEMENT doc (child*)>
<!ATTLIST doc xmlns:nsprefix CDATA #IMPLIED>
<!ATTLIST doc xmlns CDATA #IMPLIED>
<!ATTLIST doc nsprefix:a1 CDATA #IMPLIED>
<!ELEMENT child (#PCDATA)>
]>
<doc nsprefix:a1 = "v1" xmlns="http://www.w3c.org" 
     xmlns:nsprefix="http://www.oracle.com">
<child>
This element inherits the default Namespace of doc.
</child>
</doc>

xml -np NSEample.xml > xml.out

   ELEMENT       2
    PCDATA       1
       DOC       1
       DTD       1
  ELEMDECL       2
  ATTRDECL       3
     TOTAL      10 * 112 = 1120
+---ELEMENT doc [nsprefix:a1='v1'*, xmlns='http://www.w3c.org'*, xmlns:nsprefix=
'http://www.oracle.com'*]
    +---ELEMENT child
        +---PCDATA "
This element inherits the default Namespace of doc.
"

Controlling the Data Encoding of XML Documents for the C API

XML data occurs in many encodings. You can control the XML encoding in these ways:

• Specify a default encoding to assume for files that are not self-describing

• Specify the presentation encoding for DOM or SAX

• Re-encode when a DOM is serialized

Input XML data is always encoded. Some encodings are entirely self-describing, such as 16-bit encoding of Unicode (UTF-16), which requires a specific Byte Order Mark (BOM) before the start of the actual data. The XMLDecl or Multipurpose Internet Mail Extensions (MIME) header of the document can also specify an encoding. If the application cannot determine the specific encoding, then it applies the default input encoding. If you do not provide a default, then the application assumes UTF-8 on ASCII platforms and UTF-EBCDIC on EBCDIC platforms.

The API makes a provision for cases when the encoding data of the input document is corrupt. For example, suppose an ASCII document with an XMLDecl of encoding=ascii is blindly converted to EBCDIC. The new EBCDIC document contains (in EBCDIC) an XMLDecl that incorrectly claims the document is ASCII. The correct behavior for a program that is re-encoding XML data is to regenerate but not convert the XMLDecl. The XMLDecl is metadata, not data itself. This rule is often ignored, however, which causes corrupt documents. To work around this problem, the API provides an additional flag that enables you to forcibly set the input encoding, thereby overcoming an incorrect XMLDecl.

The precedence rules for determining input encoding are:

1. Forced encoding as specified by the user

   Caution:

   Forced encoding can cause a fatal error if there is a conflict. For example, the input document is UTF-16 and starts with a UTF-16 BOM, but the user specifies a forced UTF-8 encoding. In this case, the parser objects about the conflict.

2. Protocol specification (HTTP header, and so on)

3. XMLDecl specification

4. User's default input encoding

5. The default, which is UTF-8 on ASCII platforms or UTF-E on EBCDIC platforms

After the application has determined the input encoding, it can parse the document and present the data. You are allowed to choose the presentation encoding; the data is in that encoding regardless of the original input encoding.

When an application writes back a DOM in serialized form, it can choose at that time to re-encode the presentation data. Thus, you can place the serialized document in any encoding.

Using NULL-Terminated and Length-Encoded C API Functions

The native string representation in C is null-terminated. Thus, the primary DOM interface takes and returns null-terminated strings. When stored in table form, however, Oracle XML DB data is not null-terminated but length-encoded. Consequently, XDK provides an additional set of length-encoded APIs for the high-frequency cases to improve performance. In particular, the DOM functions in Table 20-5 have dual APIs.

Handling Errors with the C API

The C API functions typically either return a numeric error code (0 for success, nonzero on failure), or pass back an error code through a variable. In all cases, the API stores error codes. Your application can retrieve the most recent error by invoking the XmlDomGetLastError() function.

By default, the functions output error messages to stderr. However, you can register an error message callback at initialization time. When an error occurs, the application invokes the registered callback and does not print an error.

Using Basic XML Pull Parsing Capabilities

To use the XML Pull Parser, your application must do these steps:

1. Invoke XmlCreate to initialize the XML meta-context.

2. Initialize the Pull Parser context by invoking the XmlEvCreatePPCtx function, which creates and returns the event context.

   The XmlEvCreatePPCtx function supports all the properties supported by XmlLoadDom and XmlLoadSax, plus some additional ones.

   The XmlEvCreatePPCtx and XmlEvCreatePPCtxVA functions are fully implemented.

3. Ensure that the event context is passed to all subsequent invocations of the Pull Parser.

4. Terminate the Pull Parser context by invoking the XmlEvDestoryPPCtx function, to clean up memory.

5. Destroy the XML meta-context by invoking the XmlDestoryCtx function.

typedef  struct {
   void *ctx_xmlevctx;                   /* implementation specific context */
   xmlevdisp *disp_xmlevctx;             /* dispatch table */
   ub4 checkword_xmlevctx;               /* checkword for integrity check */
   ub4 flags_xmlevctx;                   /* mode; default: expand_entity */
   struct xmlevctx *input_xmlevctx;      /* input xmlevctx; chains the XML Event
                                            context */
} xmlevctx;

Parsing Multiple XML Documents

After creating and initializing the XML Event Context, the application can parse multiple documents with repeated invocations of XmlEvLoadPPDoc and XmlEvCleanPPCtx. These functions are fully implemented.

The properties defined by the application during the XML Event Context creation cannot be changed for each invocation of the XmlLoadPPDoc function. to change the properties, destroy the event context and then re-create it.

After XmlEvCleanPPCtx cleans up the internal structure of the current parser, the event context can be reused to parse another document.

ID Callback

You can provide a callback to convert text-based names to 8-byte identifiers (IDs).

Callback Function Signature

typedef  sb8 (*xmlev_id_cb_funcp)( void *ctx , ub1 type, ub1 *token, ub4 tok_len,
              sb8 nmspid, boolean isAttribute);

Return Value

sb8: an 8-byte ID.

Arguments

• *ctx: The implementation context.

• type: The type, which is indicated by this enumeration:

  typedef enum 
  {
    XML_EVENT_ID_URI,
    XML_EVENT_ID_QNAME,
  }xmlevidtype;
  

• *token and tok_len: The actual text to be converted.

• nmspid: The namespace ID.

• isAttribute: A Boolean value indicating an attribute.

Internally, the XmlEvGetTagId and XmlEvGetAttrID APIs invoke this callback twice, once to fetch the namespace ID and once to fetch the actual ID of the tag or the attribute Qname.

The XmlEvGetTagUriID and XmlEvGetAttrUriID functions invoke this callback once to get the ID of the corresponding Universal Resource Identifier (URI).

If a callback is not supplied, an error XML_ERR_EVENT_NOIDCBK is returned when these APIs are used.

Error Handling for the XML Pull Parser

The following sections describe error handling for the XML Pull Parser.

typedef  void (* xmlev_err_cb_funcp)(xmlctx *xctx, xmlevctx *evctx, 
        xmlevtype cur_event);

Sample Pull Parser Application

This section contains a sample pull parser application, a document to be parsed, and a list of the events that the application generates from the document.

Example 20-5 shows the sample application code.

# include "xml.h"
# include "xmlev.h"
...
xmlctx *xctx;
xmlevctx *evtcx;
if (!(xctx = XmlCreate(&xerr, (oratext *) "test")))
{
    printf("Failed to create XML context, error %u\n", (unsigned) xerr);
    return -1;
}
...
if(!(evctx = XmlEvCreatePPCtx(xctx, &xerr, NULL)))
{
   printf("Failed to create EVENT context, error %u\n", (unsigned) xerr);
   return -1;
 }
for(i = 0; i < numDocs; i++)
{
  if (xerr = XmlEvLoadPPDoc(xctx, evctx, "file", input_filenames[i], 0, NULL)
     {
       printf("Failed to load the document, error %u\n", (unsigned) xerr);
       return -1;
     }
...
  for(;;)
  {
    xmlevtype cur_event;
    cur_event = XmlEvNext(evctx);
    switch(cur_event)
         {
               case XML_EVENT_FATAL_ERROR:
                     XmlEvGetError(evctx, (oratext **)&errmsg);
                          printf("Error %s\n", errmsg);
               return;
               case XML_EVENT_START_ELEMENT:
                     printf("<%s>", XmlEvGetName0(evctx));
               break;
               case XML_EVENT_END_DOCUMENT:
                     printf("<%s>", XmlEvGetName0(evctx));
               return;
         }
  }
  XmlEvCleanPPCtx(xctx, evctx);
}
XmlEvDestroyPPCtx(xctx, evctx);
XmlDestroy(xctx);

Example 20-6 shows the sample document to be parsed.

<!DOCTYPE doc [
<!ENTITY ent SYSTEM "file:attendees.txt">
<!ELEMENT doc ANY>
<!ELEMENT meeting (topic, date, publishAttendees)>
<!ELEMENT publishAttendees (#PCDATA)>
<!ELEMENT topic (#PCDATA)>
<!ELEMENT date (#PCDATA)>
]>
<!-- Begin Document -->
<doc>
  <!-- Info about the meeting -->
  <meeting>
    <topic>Group meeting</topic>
    <date>April 25, 2005</date>
    <publishAttendees>&ent;</publishAttendees>
  </meeting>
</doc>
<!-- End Document -->

Example 20-7 shows the sequence of events generated when the attribute events property is FALSE and the expand entities properties is TRUE.

XML_EVENT_START_DOCUMENT
XML_EVENT_START_DTD
XML_EVENT_PE_DECLARATION
XML_EVENT_ELEMENT_DECLARATION
XML_EVENT_ELEMENT_DECLARATION
XML_EVENT_ELEMENT_DECLARATION
XML_EVENT_ELEMENT_DECLARATION
XML_EVENT_ELEMENT_DECLARATION
XML_EVENT_END_DTD 
XML_EVENT_COMMENT
XML_EVENT_START_ELEMENT
XML_EVENT_SPACE
XML_EVENT_COMMENT
XML_EVENT_SPACE
XML_EVENT_START_ELEMENT
XML_EVENT_START_ELEMENT
XML_EVENT_CHARACTERS
XML_EVENT_END_ELEMENT
XML_EVENT_START_ELEMENT
XML_EVENT_CHARACTERS
XML_EVENT_END_ELEMENT
XML_EVENT_START_ELEMENT
XML_EVENT_START_ENTITY
XML_EVENT_CHARACTERS
XML_EVENT_END_ENTITY
XML_EVENT_END_ELEMENT
XML_EVENT_END_ELEMENT
XML_EVENT_SPACE
XML_EVENT_END_ELEMENT
XML_EVENT_COMMENT
XML_EVENT_END_DOCUMENT

Using XMLType Functions and Descriptions

You can use the C API for XML with XMLType columns in the database. An Oracle Call Interface (OCI) program can access XML data stored in a table by initializing the values of OCI handles such as:

• Environment handle

• Service handle

• Error handle

• Optional parameters

The program can pass these input values to the function OCIXmlDbInitXmlCtx(), which returns an XML context. After the program invokes the C API, the function OCIXmlDbFreeXmlCtx() frees the context.

Table 20-6 describes a few of the functions for XML operations.

Initializing an XML Context for Oracle XML DB

An XML context is a required parameter in all the C DOM API functions. This opaque context encapsulates information pertaining to data encoding, error message language, and so on. The contents of this XML context are different for XDK applications and for Oracle XML DB applications.

For Oracle XML DB, the two OCI functions that initialize and free an XML context have these prototypes:

xmlctx *OCIXmlDbInitXmlCtx (OCIEnv *envhp, OCISvcCtx *svchp, OCIError *errhp,
       ocixmldbparam *params, ub4 num_params);

void OCIXmlDbFreeXmlCtx (xmlctx *xctx);

Creating XMLType Instances on the Client

You can construct new XMLType instances on the client by using the XmlLoadDom() invocations. Follow these basic steps:

1. You must initialize the xmlctx, as showd in the example in "Using the DOM API for C."

2. You can construct the XML data itself from these sources:

   • User buffer

   • Local file

   • URI

   The return value from these is an (xmldocnode *), which you can use in the rest of the common C API.

3. You can cast the (xmldocnode *) to a (void *) and directly provide it as the bind value if required.

You can construct empty XMLType instances by invoking XmlCreateDocument(). This function would be equivalent to an OCIObjectNew() for other types. You can operate on the (xmldocnode *) returned by the preceding invocation and finally cast it to a (void *) if it must be provided as a bind value.

Operating on XML Data in the Database Server

You can operate on XML data in Oracle Database with OCI statement invocations. You can bind and define XMLType values using xmldocnode and use OCI statements to select XML data from the database. You can use this data directly in the C DOM functions. Similarly, you can bind the values directly to SQL statements.

Using OCI and the XDK for C API: Examples

Example 20-8 shows how to construct a schema-based document with the DOM API and save it to the database. You must include the header files xml.h and ocixmldb.h.

#include <xml.h>
#include <ocixmldb.h>
static oratext tlpxml_test_sch[] = "<TOP xmlns='example1.xsd'\n\
xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance' \n\
xsi:schemaLocation='example1.xsd example1.xsd'/>";

void example1()
{
    OCIEnv *envhp;
    OCIError *errhp;
    OCISvcCtx *svchp;
    OCIStmt *stmthp;
    OCIDuration dur;
    OCIType *xmltdo;

    xmldocnode  *doc;
    ocixmldbparam params[1];
    xmlnode *quux, *foo, *foo_data;
    xmlerr       err;

    /* Initialize envhp, svchp, errhp, dur, stmthp */
    /* ........ */

    /* Get an xml context */
    params[0].name_ocixmldbparam = XCTXINIT_OCIDUR;
    params[0].value_ocixmldbparam = &dur;
    xctx = OCIXmlDbInitXmlCtx(envhp, svchp, errhp, params, 1);

    /* Start processing */ 
    printf("Supports XML 1.0: %s\n",
       XmlHasFeature(xctx, (oratext *) "xml", (oratext *) "1.0") ? "YES" : "NO");

    /* Parsing a schema-based document */
    if (!(doc = XmlLoadDom(xctx, &err, "buffer", tlpxml_test_sch,
                          "buffer_length", sizeof(tlpxml_test_sch)-1,
                          "validate", TRUE, NULL)))
    {
       printf("Parse failed, code %d\n");
       return;
    }

    /* Create some elements and add them to the document */
    top = XmlDomGetDocElem(xctx, doc);
    quux = (xmlnode *) XmlDomCreateElem(xctx ,doc, (oratext *) "QUUX");
    foo = (xmlnode *) XmlDomCreateElem(xctx, doc, (oratext *) "FOO");
    foo_data = (xmlnode *) XmlDomCreateText(xctx, doc, (oratext *)"foo's data");
    foo_data = XmlDomAppendChild(xctx, (xmlnode *) foo, (xmlnode *) foo_data);
    foo = XmlDomAppendChild(xctx, quux, foo);
    quux = XmlDomAppendChild(xctx, top, quux);

    XmlSaveDom(xctx, &err, top, "stdio", stdout, NULL);
    XmlSaveDom(xctx, &err, doc, "stdio", stdout, NULL);

    /* Insert the document to my_table */
    ins_stmt = "insert into my_table values (:1)";

    status = OCITypeByName(envhp, errhp, svchp, (const text *) "SYS",
                   (ub4) strlen((char *)"SYS"), (const text *) "XMLTYPE",
                   (ub4) strlen((char *)"XMLTYPE"), (CONST text *) 0,
                   (ub4) 0, dur, OCI_TYPEGET_HEADER,
                   (OCIType **) &xmltdo)) ;

    if (status == OCI_SUCCESS)
    {
       exec_bind_xml(svchp, errhp, stmthp, (void *)doc, xmltdo, ins_stmt));
    }

   /* free xml ctx */
   OCIXmlDbFreeXmlCtx(xctx);
}

/*--------------------------------------------------------*/
/* execute a sql statement which binds xml data */
/*--------------------------------------------------------*/
sword exec_bind_xml(svchp, errhp, stmthp, xml, xmltdo, sqlstmt)
OCISvcCtx *svchp;
OCIError *errhp;
OCIStmt *stmthp;
void *xml;
OCIType *xmltdo;
OraText *sqlstmt;
{
   OCIBind *bndhp1 = (OCIBind *) 0;
   OCIBind *bndhp2 = (OCIBind *) 0;
   sword  status = 0;
   OCIInd ind = OCI_IND_NOTNULL;
   OCIInd *indp = &ind;

   if(status = OCIStmtPrepare(stmthp, errhp, (OraText *)sqlstmt,
                    (ub4)strlen((char *)sqlstmt),
                    (ub4) OCI_NTV_SYNTAX, (ub4) OCI_DEFAULT)) {
     return OCI_ERROR;
   }

   if(status = OCIBindByPos(stmthp, &bndhp1, errhp, (ub4) 1, (dvoid *) 0,
                   (sb4) 0, SQLT_NTY, (dvoid *) 0, (ub2 *)0,
                   (ub2 *)0, (ub4) 0, (ub4 *) 0, (ub4) OCI_DEFAULT)) {
     return OCI_ERROR;
   }

   if(status = OCIBindObject(bndhp1, errhp, (CONST OCIType *) xmltdo,
               (dvoid **) &xml, (ub4 *) 0, (dvoid **) &indp, (ub4 *) 0)) {
     return OCI_ERROR;
   }

   if(status = OCIStmtExecute(svchp, stmthp, errhp, (ub4) 1, (ub4) 0,
                (CONST OCISnapshot*) 0, (OCISnapshot*) 0, (ub4) OCI_DEFAULT)) {
     return OCI_ERROR;
  }

   return OCI_SUCCESS;
}

Example 20-9 shows how to get a document from the database and modify it with the DOM API.

#include <xml.h>
#include <ocixmldb.h>
sword example2()
{
    OCIEnv *envhp;
    OCIError *errhp;
    OCISvcCtx *svchp;
    OCIStmt *stmthp;
    OCIDuration dur;
    OCIType *xmltdo;
  
    xmldocnode  *doc;
    xmlnodelist *item_list; ub4 ilist_l;
    ocixmldbparam params[1];
    text *sel_xml_stmt = (text *)"SELECT xml_col FROM my_table";
    ub4    xmlsize = 0;
    sword  status = 0;
    OCIDefine *defnp = (OCIDefine *) 0;

    /* Initialize envhp, svchp, errhp, dur, stmthp */
    /* ... */

    /* Get an xml context */
    params[0].name_ocixmldbparam = XCTXINIT_OCIDUR;
    params[0].value_ocixmldbparam = &dur;
    xctx = OCIXmlDbInitXmlCtx(envhp, svchp, errhp, params, 1);

    /* Start processing */
    if(status = OCITypeByName(envhp, errhp, svchp, (const text *) "SYS",
                   (ub4) strlen((char *)"SYS"), (const text *) "XMLTYPE",
                   (ub4) strlen((char *)"XMLTYPE"), (CONST text *) 0,
                   (ub4) 0, dur, OCI_TYPEGET_HEADER,
                   (OCIType **) xmltdo_p)) {
       return OCI_ERROR;
    }

    if(!(*xmltdo_p)) {
       printf("NULL tdo returned\n");
       return OCI_ERROR;
    }

    if(status = OCIStmtPrepare(stmthp, errhp, (OraText *)selstmt,
                    (ub4)strlen((char *)selstmt),
                    (ub4) OCI_NTV_SYNTAX, (ub4) OCI_DEFAULT)) {
      return OCI_ERROR;
    }

    if(status = OCIDefineByPos(stmthp, &defnp, errhp, (ub4) 1, (dvoid *) 0,
                   (sb4) 0, SQLT_NTY, (dvoid *) 0, (ub2 *)0,
                   (ub2 *)0, (ub4) OCI_DEFAULT)) {
       return OCI_ERROR;
    }

    if(status = OCIDefineObject(defnp, errhp, (OCIType *) *xmltdo_p,
                            (dvoid **) &doc,
                            &xmlsize, (dvoid **) 0, (ub4 *) 0)) {
      return OCI_ERROR;
    }

    if(status = OCIStmtExecute(svchp, stmthp, errhp, (ub4) 1, (ub4) 0,
                 (CONST OCISnapshot*) 0, (OCISnapshot*) 0, (ub4) OCI_DEFAULT)) {
      return OCI_ERROR;
    }

    /* We have the doc. Now we can operate on it */
    printf("Getting Item list...\n");

   item_list = XmlDomGetElemsByTag(xctx,(xmlelemnode *) elem,(oratext *)"Item"); 
    ilist_l   = XmlDomGetNodeListLength(xctx, item_list);
    printf(" Item list length = %d \n", ilist_l);

    for (i = 0; i < ilist_l; i++)
    {
      elem = XmlDomGetNodeListItem(xctx, item_list, i);
      printf("Elem Name:%s\n", XmlDomGetNodeName(xctx, fragelem));
      XmlDomRemoveChild(xctx, fragelem);
    }

    XmlSaveDom(xctx, &err, doc, "stdio", stdout, NULL);

   /* free xml ctx */
   OCIXmlDbFreeXmlCtx(xctx);

   return OCI_SUCCESS;
}