13
XML Parser for C

This chapter contains the following sections:

• Accessing XML Parser for C
• XML Parser for C Features
• XML Parser for C Usage
• XML Parser for C Default Behavior
• DOM and SAX APIs
• Invoking XML Parser for C
• Using the Sample Files Included with Your Software
• Running the XML Parser for C Sample Programs

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: http://otn.oracle.com/tech/xml

It is located in $ORACLE_HOME/xdk/c/parser on Solaris^TM 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 http://otn.oracle.com/tech/xml.

Specifications

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:

• xmlclean() is called.
• xmlterm() is called.

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
oratext	String pointer
xmlctx	Master XML context
xmlmemcb	Memory callback structure (optional)
xmlsaxcb	SAX callback structure (SAX only)
ub4	32-bit (or larger) unsigned integer
uword	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

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:

• xmlinit() - xmlparse() or

  xmlparsebuf() - xmlterm()

• xmlinit() - xmlparse() or

  xmlparsebuf() - xmlclean() - xmlparse() or

  xmlparsebuf() - xmlclean() -... - xmlterm()

• xmlinit() - xmlparse() or

  xmlparsebuf() - xmlparse() or

  xmlparsebuf() -... - xmlterm()

Figure 13-1 XML Parser for C Calling Sequence

Text description of the illustration adxml096.gif

XML Parser for C Default Behavior

The following is the XML Parser for C default behavior:

• Character set encoding is UTF-8. If all your documents are ASCII, you are encouraged to set the encoding to US-ASCII for better performance.
• Messages are printed to stderr unless msghdlr is given.
• A parse tree which can be accessed by DOM APIs is built unless saxcb is set to use the SAX callback APIs. Note that any of the SAX callback functions can be set to NULL if not needed.
• The default behavior for the parser is to check that the input is well-formed but not to check whether it is valid. The flag XML_FLAG_VALIDATE can be set to validate the input. The default behavior for whitespace processing is to be fully conformant to the XML 1.0 spec, that is, all whitespace is reported back to the application but it is indicated which whitespace is ignorable. However, some applications may prefer to set the XML_FLAG_DISCARD_WHITESPACE which will discard all whitespace between an end-element tag and the following start-element tag.

  Note: It is recommended that you set the default encoding explicitly if using only single byte character sets (such as US-ASCII or any of the ISO-8859 character sets) for performance up to 25% faster than with multibyte character sets, such as UTF-8.

DOM and SAX APIs

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:

• DOM interface
• Serially through a SAX interface

These two XML APIs:

• DOM: Tree-based APIs. A tree-based API compiles an XML document into an internal tree structure, then allows an application to navigate that tree using the Document Object Model (DOM), a standard tree-based API for XML and HTML documents.
• SAX: Event-based APIs. An event-based API, on the other hand, reports parsing events (such as the start and end of elements) directly to the application through callbacks, and does not usually build an internal tree. The application implements handlers to deal with the different events, much like handling events in a graphical user interface.

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:

• By invoking the executable on the command line
• By writing C code and using the supplied APIs

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
-c	Conformance check only, no validation
-e encoding	Specify input file encoding
-h	Help - show this usage help
-n	Number - DOM traverse and report number of elements
-p	Print document and DTD structures after parse
-x	Exercise SAX interface and print document
-v	Version - display parser version then exit
-w	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
DOMNamespace.c	Source for DOMNamespace program
DOMNamespace.std	Expected output from DOMNamespace
DOMSample.c	Source for DOMSample program
DOMSample.std	Expected output from DOMSample
FullDOM.c	Sample usage of DOM interface
FullDOM.std	Expected output from FullDOM
Make.bat	Batch file for building sample programs
NSExample.xml	Sample XML file using namespaces
SAXNamespace.c	Source for SAXNamespace program
SAXNamespace.std	Expected output from SAXNamespace
SAXSample.c	Source for SAXSample program
SAXSample.std	Expected output from SAXSample
XSLSample.c	Source for XSLSample program
XSLSample.std	Expected output from XSLSample
class.xml	XML file that may be used with XSLSample
iden.xsl	Stylesheet that may be used with XSLSample
cleo.xml	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 Solaris^TM 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
DOMSample	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.
DOMNamespace	Same as SAXNamespace except using DOM interface.
SAXNamespace	A sample application using Namespace extensions to SAX API; prints out all elements and attributes of NSExample.xml along with full namespace information.
FullDOM	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

---