14 XML Parser for C

Loading an XML Document with the C API

Once an xmlctx is obtained, a serialized XML document is loaded with the XmlLoadDom() or XmlLoadSax() functions. Given the Document node, all API DOM functions are available.

Data Encoding of XML Documents for the C API

XML data occurs in many encodings. You have control over the encoding in three 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 data is always in some encoding. Some encodings are entirely self-describing, such as UTF-16, which requires a specific BOM before the start of the actual data. A document's encoding may also be specified in the XMLDecl or MIME header. If the specific encoding cannot be determined, your default input encoding is applied. If no default is provided by you, UTF-8 is assumed on ASCII platforms and UTF-E on EBCDIC platforms.

A provision is made for cases when the encoding information of the input document is corrupt. For example, if an ASCII document which contains an XMLDecl saying encoding=ascii is blindly converted to EBCDIC, the new EBCDIC document contains (in EBCDIC), an XMLDecl which claims the document is ASCII, when it is not. The correct behavior for a program which is re-encoding XML data is to regenerate the XMLDecl, not to convert it. The XMLDecl is metadata, not data itself. However, this rule is often ignored, and then the corrupt documents result. To work around this problem, an additional flag is provided which allows the input encoding to be forcibly set, overcoming an incorrect XMLDecl.

The precedence rules for determining input encoding are as follows:

1. Forced encoding as specified by the user.

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

3. XMLDecl specification is used.

4. User's default input encoding.

5. The default: UTF-8 (ASCII platforms) or UTF-E (EBCDIC platforms).

Once the input encoding has been determined, the document can be parsed and the data presented. You are allowed to choose the presentation encoding; the data will be in that encoding regardless of the original input encoding.

When a DOM is written back out (serialized), you can choose at that time to re-encode the presentation data, and the final serialized document can be in any encoding.

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. However, Oracle XML DB data when stored in table form, is not NULL-terminated but length-encoded, so an additional set of length-encoded APIs are provided for the high-frequency cases to improve performance (if you deliberately choose to use them). Either set of functions works.

In particular, the following DOM functions are invoked frequently and have dual APIs:

Error Handling

The 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, error codes are stored and the last error can be retrieved with XmlDomGetLastError().

Error messages, by default, are output to stderr. However, you can register an error message callback at initialization time. When an error occurs, that callback will be invoked and no error printed.

Installing the C API

There are no special installation or first-use requirements. The XML DOM does not require an ORACLE_HOME. It can run out of a reduced root directory such as those provided on OTN releases.

However, since the XML DOM requires globalization support, the globalization support data files must be present (and found through the environment variables ORACLE_HOME or ORA_NLS10).

XML Context

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 as their prototypes:

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

void OCIXmlDbFreeXmlCtx (xmlctx *xctx);

Creating XMLType Instances on the Client

New XMLType instances on the client can be constructed using the XmlLoadDom() calls. You first have to initialize the xmlctx, as in the example in Using DOM for XDK. The XML data itself can be constructed from a user buffer, local file, or URI. The return value from these is an (xmldocnode *) which can be used in the rest of the common C API. Finally, the (xmldocnode *) can be cast to a (void *) and directly provided as the bind value if required.

Empty XMLType instances can be constructed using the XmlCreateDocument() call. This would be equivalent to an OCIObjectNew() for other types. You can operate on the (xmldocnode *) returned by the above call and finally cast it to a (void *) if it needs to be provided as a bind value.

XML Data on the Server

XML data on the server can be operated on by means of OCI statement calls. You can bind and define XMLType values using xmldocnode, as with other object instances. OCI statements are used to select XML data from the server. This data can be used in the C DOM functions directly. Similarly, the values can be bound back to SQL statements directly.

XMLType Functions and Descriptions

The following table describes a few of the functions for XML operations.

OCI Examples

Here is an example of how to construct a schema-based document using 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;
}

Here is an example of how to get a document from the database and modify it using 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;
}

Memory Allocation

The memory callback functions XML_ALLOC_F and XML_FREE_F can be used if you want to use your own memory allocation. If they are used, both of the functions should be specified.

The memory allocated for parameters passed to the SAX callbacks or for nodes and data stored with the DOM parse tree are not freed until one of the following is done:

• XmlFreeDocument() is called.

• XmlDestroy() is called.

Thread Safety

If threads are forked off somewhere in the init-parse-term sequence of calls, you get unpredictable behavior and results.

Data Types Index

Table 14-3 lists the datatypes used in XML Parser for C.

Error Message Files

Error messages files are in the $ORACLE_HOME/xdk/mesg directory. You may set the environment variable ORA_XML_MESG to point to the absolute path of the mesg subdirectory, although this not required.

Parser Calling Sequence

The sequence of calls to the parser can be any of the following:

• XmlCreate() - XmlLoadDom() - XmlDestroy()

• XmlCreate() - XmlLoadDom() - XmlFreeDocument() -

  XmlLoadDom() - XmlFreeDocument() - ... - XmlDestroy()

• XmlCreate() - XmlLoadDom() -... - XmlDestroy()

Figure 14-1 XML Parser for C Calling Sequence

Description of the illustration adxdk096.gif

Using the SAX API

To use SAX, an xmlsaxcb structure is initialized with function pointers and passed to the XmlLoadSax() call. A pointer to a user-defined context structure can also be included. That context pointer will be passed to each SAX function.

Command Line Usage

The XML Parser and XSLT Processor can be called as an executable by invoking bin/xml:

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

Table 14-4 lists the command line options.

-B BaseUri

-c

-e encoding

-E encoding

-f

-G xptrexprs

-h

-hh

-i n

-l language

-n

-o XSLoutfile

-p

-P

-PE encoding

-PP

-PX

-r

-s stylesheet

-v

-V var value

-w

-W

Writing C Code to Use Supplied APIs

XML Parser for C can also be invoked by writing code to use the supplied APIs. The code must be compiled using the headers in the include/ subdirectory and linked against the libraries in the lib/ subdirectory. Please see the Makefile in the demo/c/ subdirectory for full details of how to build your program.