Skip Headers

Oracle9i XML Developer's Kits Guide - XDK
Release 2 (9.2)

Part Number A96621-01
Go To Documentation Library
Go To Product List
Book List
Go To Table Of Contents
Go To Index

Master Index


Go to previous page Go to next page

XML Parser for C

This chapter contains the following sections:

Accessing XML Parser for C

The XML Parser for C is provided with Oracle9i and Oracle9i Application Server. It is also available for download from the OTN site:

It is located in $ORACLE_HOME/xdk/c/parser on SolarisTM Operating Environment systems.

XML Parser for C Features

readme.html in the root directory of the software archive contains release specific information including bug fixes and API additions.

XML Parser for C will check if an XML document is well-formed, and optionally validate it against a DTD. The parser constructs an object tree which can be accessed through a DOM interface or operate serially through a SAX interface.

You can post questions, comments, or bug reports to the XML Discussion Forum at


See Also:

Memory Allocation

The memory callback functions memcb may be used if you wish to use your own memory allocation. If they are used, all 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 will not be freed until one of the following is done:

Thread Safety

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

Data Types Index

Table 13-1 lists the datatypes used in XML Parser for C.

Table 13-1 Datatypes Used in XML Parser for C
DataType Description


String pointer


Master XML context


Memory callback structure (optional)


SAX callback structure (SAX only)


32-bit (or larger) unsigned integer


Native unsigned integer

Error Message Files

Error message files are provided in the mesg/ subdirectory. The messages files also exist 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.

Validation Modes

See Also:

Available validation modes are described in "Oracle XML Parsers Validation Modes".

XML Parser for C Usage

Figure 13-1 describes XML Parser for C calling sequence as follows:

  1. xmlinit() function initializes the parsing process.
  2. The parsed item can be an XML document (file) or string buffer. If the input is an XML document or file, it is parsed using the xmlparser() function. If the input is a string buffer, it is parsed using the xmlparserbuf() function.
  3. DOM or SAX API:

    DOM: If you are using the DOM interface, include the following steps:

    • The xmlparse() or xmlparseBuffer() function calls .getDocumentElement(). If no other DOM functions are being applied, you can invoke xmlterm().
    • This optionally calls other DOM functions if required. These are typically Node or print functions. It outputs the DOM document.
    • If complete, the process invokes xmlterm()
    • You can first invoke xmlclean() to clean up any data structures created during the parse process. You would then call xmlterm()

    SAX: If you are using the SAX interface, include the following steps:

    • Process the results of the parser from xmlparse() or xmlparseBuf() using callback functions.
    • Register the callback functions.
  4. Use xmlclean() to clean up the memory and structures used during a parse, and go to Step 5. or return to Step 2.
  5. Terminate the parsing process with xmlterm()
XML Parser for C usage is further explained in Figure 13-1.

Parser Calling Sequence

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

Figure 13-1 XML Parser for C Calling Sequence

Text description of adxml096.gif follows
Text description of the illustration adxml096.gif

XML Parser for C Default Behavior

The following is the XML Parser for C default behavior:


Oracle XML parser for C checks if an XML document is well-formed, and optionally validates it against a DTD. The parser constructs an object tree which can be accessed through one of the following interfaces:

These two XML APIs:

Tree-based APIs are useful for a wide range of applications, but they often put a great strain on system resources, especially if the document is large (under very controlled circumstances, it is possible to construct the tree in a lazy fashion to avoid some of this problem). Furthermore, some applications need to build their own, different data trees, and it is very inefficient to build a tree of parse nodes, only to map it onto a new tree.

In both of these cases, an event-based API provides a simpler, lower-level access to an XML document: you can parse documents much larger than your available system memory, and you can construct your own data structures using your callback event handlers.

Using the SAX API

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

SAX Callback Structure

The SAX callback structure:

typedef struct
 sword (*startDocument)(void *ctx);
 sword (*endDocument)(void *ctx);
 sword (*startElement)(void *ctx, const oratext *name, 
             const struct xmlarray *attrs);
 sword (*endElement)(void *ctx, const oratext *name);
 sword (*characters)(void *ctx, const oratext *ch, size_t len);
 sword (*ignorableWhitespace)(void *ctx, const oratext *ch, size_t len);
 sword (*processingInstruction)(void *ctx, const oratext *target,
             const oratext *data);
 sword (*notationDecl)(void *ctx, const oratext *name,
             const oratext *publicId, const oratext *systemId);
 sword (*unparsedEntityDecl)(void *ctx, const oratext *name, 
             const oratext *publicId,
             const oratext *systemId, const oratext *notationName);
 sword (*nsStartElement)(void *ctx, const oratext *qname,
             const oratext *local, const oratext *nsp,
             const struct xmlnodes *attrs);
} xmlsaxcb;

Invoking XML Parser for C

XML Parser for C can be invoked in two ways:

Command Line Usage

The XML Parser for C can be called as an executable by invoking bin/xml

Table 13-2 lists the command line options.

Table 13-2 XML Parser for C: Command Line Options
Option Description


Conformance check only, no validation

-e encoding

Specify input file encoding


Help - show this usage help


Number - DOM traverse and report number of elements


Print document and DTD structures after parse


Exercise SAX interface and print document


Version - display parser version then exit


Whitespace - preserve all whitespace

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 sample/ subdirectory for full details of how to build your program.

Using the Sample Files Included with Your Software

$ORACLE_HOME/xdk/c/parser/sample/ directory contains several XML applications to illustrate how to use the XML Parser for C with the DOM and SAX interfaces.

Table 13-3 lists the sample files in sample/ directory.

Table 13-3 XML Parser for C sample/ Files  
sample/ File Name Description


Source for DOMNamespace program


Expected output from DOMNamespace


Source for DOMSample program


Expected output from DOMSample


Sample usage of DOM interface


Expected output from FullDOM


Batch file for building sample programs


Sample XML file using namespaces


Source for SAXNamespace program


Expected output from SAXNamespace


Source for SAXSample program


Expected output from SAXSample


Source for XSLSample program


Expected output from XSLSample


XML file that may be used with XSLSample


Stylesheet that may be used with XSLSample


The Tragedy of Antony and Cleopatra

XML version of Shakespeare's play


Running the XML Parser for C Sample Programs

Building the Sample Programs

Change directories to the sample directory ($ORACLE_HOME/xdk/demo/c/parser on SolarisTM Operating Environment) and read the README file. This will explain how to build the sample programs according to your platform.

Sample Programs

Table 13-4 lists the programs built by the sample files in the sample directory.

Table 13-4 XML Parser for C: Sample Built Programs in sample/ 
Built Program Description


A sample application using DOM APIs (shows an outline of Cleopatra, that is, the XML elements ACT and SCENE).

SAXSample [word]

A sample application using SAX APIs. Given a word, shows all lines in the play Cleopatra containing that word. If no word is specified, 'death' is used.


Same as SAXNamespace except using DOM interface.


A sample application using Namespace extensions to SAX API; prints out all elements and attributes of NSExample.xml along with full namespace information.


Sample usage of full DOM interface. Exercises all the calls, but does nothing too exciting.

XSLSample <xmlfile> <xsl ss>

Sample usage of XSL processor. It takes two filenames as input, the XML file and XSL stylesheet

Go to previous page Go to next page
Copyright © 2001, 2002 Oracle Corporation.

All Rights Reserved.
Go To Documentation Library
Go To Product List
Book List
Go To Table Of Contents
Go To Index

Master Index