Oracle XML Parser 9.2.0.6.0 (C)

General description

Revision history

The XML parser will check if an XML document is well-formed, and optionally validate it against a DTD. The parser will construct an object tree which can be accessed via a DOM interface or operate serially via a SAX interface. An XSLT processor which provides the ability to format an XML document according to a stylesheet is bundled with the parser.

You may post questions, comments, or bug reports to the XML Forum on the Oracle Technology Network. Oracle customers may also call Oracle Worldwide Support for assistance.

The parser conforms to the following standards:

The W3C recommendation for Extensible Markup Language (XML) 1.0
The W3C recommendation for Document Object Model Level 1 1.0
The W3C recommendation for Namespaces in XML
The Simple API for XML (SAX) 1.0
The W3C recommendation for XSL Transformations (XSLT)
The W3C recommendation for XML Path Language (XPath)

The following files and directories are found in this release:

`license.html`	Licensing agreement
`readme.html`	This README file
`bin/`	Standalone parser/processor executable "`xml`"
`demo/`	Example usage of the XML parser
`doc/`	API documentation
`include/`	Header files
`lib/`	Parser/processor and support libraries
`mesg/`	Error message files

The following libraries are included:

`libxml9.a`	XML Parser/XSL Processor
`libcore9.a`	CORE functions
`libnls9.a`	National Language Support

The parser may be called as an executable by invoking bin/xml which has the following options:

`-c`	Conformance check only, no validation
`-e encoding`	Specify default input file encoding ("incoding")
`-E encoding`	Specify DOM/SAX encoding ("outcoding")
`-f`	File - Interpret as filespec, not URI
`-h`	Help - show usage help and full list of flags
`-i n`	Number of times to iterate the XSLT processing
`-l language`	Language for error reporting
`-n`	Number - DOM traverse and report number of elements
`-o XSLoutfile`	Specify output file of XSLT processor
`-p`	Print document after parse
-`r`	Do not ignore <xsl:output> instruction in XSLT processing
`-s stylesheet`	Style sheet - specifies the XSL style sheet
`-v`	Version - display parser version then exit
`-V var value`	To test top level variables in CXSLT
`-w`	Whitespace - preserve all whitespace
`-W`	Warning - stop parsing after a warning
`-x`	SAX - exercise SAX interface and print document

The parser may 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. See Makefile in the demo/ subdirectory for full details of how to build your program.

Error message files are provided in the mesg/ subdirectory. Files ended in .msb are machine-readable and needed at runtime; files ending .msg are human-readable and include cause and action descriptions for each error. 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 is not required.

The parser supports over 300 IANA character sets. These character sets include the following:

UTF-8, UTF-16, UTF16-BE, UTF16-LE, US-ASCII, ISO-10646-UCS-2, ISO-8859-{1-9, 13-15}, EUC-JP, SHIFT_JIS, BIG5, GB2312, GB_2312-80, HZ-GB-2312, KOI8-R, KSC5601, EUC-KR, ISO-2022-CN, ISO-2022-JP, ISO-2022-KR, WINDOWS-{1250-1258}, EBCDIC-CP-{US,CA,NL,WT,DK,NO,FI,SE,IT,ES,GB,FR,HE,BE,CH,ROECE,YU,IS,AR1}, IBM{037,273,277,278,280,284,285,297,420,424,437,500,775,850,852,855,857,00858, 860,861,863,865,866,869,870,871,1026,01140,01141,01142,01143,01144,01145,01146, 01147,01148}

Any alias of the above character sets that is found here may also be used. In addition, any character set specified in Appendix A, Character Sets, of the Oracle National Language Support Guide may be used with the exception of IW7IS960. However, it is recommended that you use IANA character set names for interoperability with other XML parsers. Also note that XML parsers are only required to support UTF-8 and UTF-16 so those character sets should be preferred.

In order to be able to use these encodings, you should have the ORACLE_HOME environment variable set and pointing to the location of your Oracle installation. This will enable the use of the NLS data files which contain data for all supported encodings. On Unix systems, they are usually in $ORACLE_HOME/ocommon/nls/admin/data. On Windows NT, they are usually in $ORACLE_HOME/nlsrtl/admin/nlsdata. Starting with version 9.0.1, C and C++ XDK releases that are downloaded from OTN contain an nlsdata/ subdirectory. You must set the environment variable ORA_NLS33 to the absolute path of the nlsdata/ subdirectory if you don't have an Oracle installation.

Using this XDK with an Oracle 8i installation is not supported. If you wish to try it on Windows anyway, you should copy the CORE and NLS DLLs and the NLSDATA files that are supplied with this XDK to your Oracle 8i home. In addition, you should set the environment variable NLS_TIME_TZ_FORMAT to HH.MI.SSXFF AM TZH:TZM and the enviroment variable NLS_TIMESTAMP_TZ_FORMAT to DD-MON-RR HH.MI.SSXFF AM TZH:TZM.

The default input encoding ("incoding") is UTF-8. That is, if an input document's encoding is not self-evident (by HTTP charset, Byte Order Mark, XMLDecl, etc), then the default input encoding will be assumed. 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) since single-byte performance is by far the fastest. The flag XML_FLAG_FORCE_INCODING says that the default input encoding should always be applied to input documents, ignoring any BOM or XMLDecl. However, a protocol declaration (such as HTTP charset) is always honored.

The data encoding for DOM and SAX ("outcoding") should be chosen carefully. Single-byte encodings are the fastest, but can represent only a very limited set of characters. Next fastest is Unicode (UTF-16), and slowest are the multibyte encodings such as UTF-8. If input data cannot be converted to the outcoding without loss, an error will occur. So for maximum utility, a Unicode-based outoding should be used, since Unicode can represent any character. If outcoding is not specified, it defaults to the incoding of the first document parsed.

The following features of the XSLT recommendation are not currently supported but may be available in future releases: extension elements, extension functions, and xsl:fallback.