Thus, if you installed your binaries under $HOME/fastxmlparser, you need to point your library path to that directory.

export LIBPATH=$LIBPATH:$HOME/fastxmlparser/lib # (AIX)
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$HOME/fastxmlparser/lib
# (Solaris, Linux)
export SHLIB_PATH=$SHLIB_PATH:$HOME/fastxmlparser/lib # (HP-UX)

If you are using the enhanced version of this parser from IBM, you will need to put in two additional DLLs. In the Windows build these are icuuc.dll and icudata.dll which must be available from your PATH settings. On UNIX, these libraries are called libicu-uc.so and libicudata.so (or .sl for HP-UX or .a for AIX) which must be available from your library search path.

I just built my own application using the Xerces-C parser. Why does it crash?

In order to work with the Xerces-C parser, you have to first initialize the XML subsystem. The most common mistake is to forget this initialization. Before you make any calls to Xerces-C APIs, you must call:

XMLPlatformUtils::Initialize():
try {
   XMLPlatformUtils::Initialize();
}
catch (const XMLException& toCatch) {
   // Do your failure processing here
}

This initializes the Xerces system and sets its internal variables. Note that you must the include util/PlatformUtils.hpp file for this to work.

Is Xerces-C thread-safe?

This is not a question that has a simple yes/no answer. Here are the rules for using Xerces-C in a multi-threaded environment:

Within an address space, an instance of the parser may be used without restriction from a single thread, or an instance of the parser can be accessed from multiple threads, provided the application guarantees that only one thread has entered a method of the parser at any one time.

When two or more parser instances exist in a process, the instances can be used concurrently, without external synchronization. That is, in an application containing two parsers and two threads, one parser can be running within the first thread concurrently with the second parser running within the second thread.

The same rules apply to Xerces-C DOM documents. Multiple document instances may be concurrently accessed from different threads, but any given document instance can only be accessed by one thread at a time.

DOMStrings allow multiple concurrent readers. All DOMString const methods are thread safe, and can be concurrently entered by multiple threads. Non-const DOMString methods, such as appendData(), are not thread safe and the application must guarantee that no other methods (including const methods) are executed concurrently with them.

The libs/dll's I downloaded keep me from using the debugger in VC6.0. I am using the 'D', debug versions of them. "no symbolic information found" is what it says. Do I have to compile everything from source to make it work?

Unless you have the .pdb files, all you are getting with the debug library is that it uses the debug heap manager, so that you can compile your stuff in debug mode and not be dangerous. If you want full symbolic info for the Xerces-C library, you'll need the .pdb files, and to get those, you'll need to rebuild the Xerces-C library.

"First-chance exception in DOMPrint.exe (KERNEL32.DLL): 0xE06D7363: Microsoft C++ Exception." I am always getting this message when I am using the parser. My programs are terminating abnormally. Even the samples are giving this exception. I am using Visual C++ 6.0 with latest service pack installed.

Xerces-C uses C++ exceptions internally, as part of its normal operation. By default, the MSVC debugger will stop on each of these with the "First-chance exception ..." message.

To stop this from happening do this:

• start debugging (so the debug menu appears)
• from the debug menu select "Exceptions"
• from the box that opens select "Microsoft C++ Exception" and set it to "Stop if not handled" instead of "stop always".

You'll still land in the debugger if your program is terminating abnormally, but it will be at your problem, not from the internal Xerces-C exceptions.

I am seeing memory leaks in Xerces-C. Are they real?

The Xerces-C library allocates and caches some commonly reused items. The storage for these may be reported as memory leaks by some heap analysis tools; to avoid the problem, call the function XMLPlatformUtils::Terminate() before your application exits. This will free all memory that was being held by the library.

For most applications, the use of Terminate() is optional. The system will recover all memory when the application process shuts down. The exception to this is the use of Xerces-C from DLLs that will be repeatedly loaded and unloaded from within the same process. To avoid memory leaks with this kind of use, Terminate() must be called before unloading the xerces-c library

Is there a facility in Xerces-C to validate the data contained in a DOM tree? That is, without saving and re-parsing the source document?

No. This is a frequently requested feature, but at this time it is not possible to feed XML data from the DOM directly back to the DTD validator. The best option for now is to generate XML source from the DOM and feed that back into the parser.

Can I use Xerces to perform "write validation" (which is having an appropriate DTD and being able to add elements to the DOM whilst validating against the DTD)? Is there a function that I have totally missed that creates an XML file from a DTD, (obviously with the values missing, a skeleton, as it were.)

The answers are: "No" and "No." Write Validation is a commonly requested feature, but Xerces-C does not have it yet.

The best you can do for now is to create the DOM document, write it back as XML and re-parse it.

Why does my multi-threaded application crash on Solaris?

The problem appears because the throw call on Solaris 2.6 is not multi-thread safe. Sun Microsystems provides a patch to solve this problem. To get the latest patch for solving this problem, go to SunSolve.sun.com and get the appropriate patch for your operating system. For Intel machines running Solaris, you need to get Patch ID 104678. For SPARC machines you need to get Patch ID #105591.

Why does my application gives unresolved linking errors on Solaris?

On Solaris there are a few things that need to be done before you execute your application using Xerces-C / XML4C. In case you're using the binary build of Xerces-C / XML4C make sure that the OS and compiler are the same version as the ones used to build the binary. Different OS and compiler versions might cause unresolved linking problems or compilation errors. If the versions are different, rebuild the Xerces-C library on your system before building your application. If you're using ICU (which is packaged with XML4C) you need to rebuild the compatible version of ICU first.

Also check that the library path is set properly and that the correct versions of gmake and autoconf are on your system.

How do I determine the version of Xerces-C I am using?

The version string for Xerces-C is in one of the header files. Look inside the file src/util/XercesDefs.hpp or, in the binary distribution, look in include/utils/XercesDefs.hpp. Search for the static variable gXercesFullVersionStr and look at its definition. (It is usually a string like "1_4_0" or something similar). This is the version of Xerces-C you are using.

If you don't have the header files, you have to find the version information from the shared library name. On Windows NT/95/98 right click on the DLL name xerces-c_1.dll in the bin directory and look up properties. The version information may be found on the Version tab.

On AIX, just look for the library name libxerces-c1_4.a (or libxerces-c1_4.so on Solaris/Linux and libxerces-c1_4.sl on HP-UX). The version number is coded in the name of the library.

How do I uninstall Xerces-C?

Xerces-C only installs itself in a single directory and does not set any registry entries. Thus, to uninstall, you only need to remove the directory where you installed it, and all Xerces-C related files will be removed.

How are entity reference nodes handled in DOM?

If you are using the native DOM classes, the function setExpandEntityReferences controls how entities appear in the DOM tree. When setExpandEntityReferences is set to false (the default), an occurrence of an entity reference in the XML document will be represented by a subtree with an EntityReference node at the root whose children represent the entity expansion. Entity expansion will be a DOM tree representing the structure of the entity expansion, not a text node containing the entity expansion as text.

If setExpandEntityReferences is true, an entity reference in the XML document is represented by only the nodes that represent the entity expansion. The DOM tree will not contain any entityReference nodes.

What kinds of URLs are currently supported in Xerces-C?

The XMLURL class provides for limited URL support. It understands the file://, http://, and ftp:// URL types, and is capable or parsing them into their constituent components, and normalizing them. It also supports the commonly required action of conglomerating a base and relative URL into a single URL. In other words, it performs the limited set of functions required by an XML parser.

Another thing that URLs commonly do are to create an input stream that provides access to the entity referenced. The parser, as shipped, only supports this functionality on URLs in the form file:/// and file://localhost/, i.e. only when the URL refers to a local file.

You may enable support for HTTP and FTP URLs by implementing and installing a NetAccessor object. When a NetAccessor object is installed, the URL class will use it to create input streams for the remote entities referred to by such URLs.

How can I add support for URLs with HTTP/FTP protocols?

Support for the http: protocol is now included by default on all platforms.

To address the need to make remote connections to resources specified using additional protocols, ftp for example, Xerces-C provides the NetAccessor interface. The header file is src/util/XMLNetAccessor.hpp. This interface allows you to plug in your own implementation of URL networking code into the Xerces-C parser.

Can I use Xerces-C to parse HTML?

Yes, but only if the HTML follows the rules given in the XML specification. Most HTML, however, does not follow the XML rules, and will generate XML well-formedness errors.

I keep getting an error: "invalid UTF-8 character". What's wrong?

Most commonly, the XML encoding = declaration is either incorrect or missing. Without a declaration, XML defaults to the use utf-8 character encoding, which is not compatible with the default text file encoding on most systems.

The XML declaration should look something like this:

<?xml version="1.0" encoding="iso-8859-1"?>

Make sure to specify the encoding that is actually used by file. The encoding for "plain" text files depends both on the operating system and the locale (country and language) in use.

Another common source of problems is that some characters are not allowed in XML documents, according to the XML spec. Typical disallowed characters are control characters, even if you escape them using the Character Reference form. See the XML spec, sections 2.2 and 4.1 for details. If the parser is generating an Invalid character (Unicode: 0x???) error, it is very likely that there's a character in there that you can't see. You can generally use a UNIX command like "od -hc" to find it.

What encodings are supported by Xerces-C / XML4C?

Xerces-C has intrinsic support for ASCII, UTF-8, UTF-16 (Big/Small Endian), UCS4 (Big/Small Endian), EBCDIC code pages IBM037 and IBM1140 encodings, ISO-8859-1 (aka Latin1) and Windows-1252. This means that it can parse input XML files in these above mentioned encodings.

XML4C -- the version of Xerces-C available from IBM -- extends this set to include the encodings listed in the table below.

Some implementations or ports of Xerces-C provide support for additional encodings. The exact set will depend on the supplier of the parser and on the character set transcoding services in use.

What character encoding should I use when creating XML documents?

The best choice in most cases is either utf-8 or utf-16. Advantages of these encodings include:

• The best portability. These encodings are more widely supported by XML processors than any others, meaning that your documents will have the best possible chance of being read correctly, no matter where they end up.
• Full international character support. Both utf-8 and utf-16 cover the full Unicode character set, which includes all of the characters from all major national, international and industry character sets.
• Efficient. utf-8 has the smaller storage requirements for documents that are primarily composed of of characters from the Latin alphabet. utf-16 is more efficient for encoding Asian languages. But both encodings cover all languages without loss.

The only drawback of utf-8 or utf-16 is that they are not the native text file format for most systems, meaning that common text file editors and viewers can not be directly used.

A second choice of encoding would be any of the others listed in the table above. This works best when the xml encoding is the same as the default system encoding on the machine where the XML document is being prepared, because the document will then display correctly as a plain text file. For UNIX systems in countries speaking Western European languages, the encoding will usually be iso-8859-1.

The versions of Xerces distributed by IBM, both C and Java (known respectively as XML4C and XML4J), include all of the encodings listed in the above table, on all platforms.

A word of caution for Windows users: The default character set on Windows systems is windows-1252, not iso-8859-1. While Xerces-C does recognize this Windows encoding, it is a poor choice for portable XML data because it is not widely recognized by other XML processing tools. If you are using a Windows-based editing tool to generate XML, check which character set it generates, and make sure that the resulting XML specifies the correct name in the encoding="..." declaration.

I find memory leaks in Xerces-C / XML4C. How do I eliminate it?

The "leaks" that are reported through a leak-detector or heap-analysis tools aren't really leaks in most application, in that the memory usage does not grow over time as the XML parser is used and re-used.

What you are seeing as leaks are actually lazily evaluated data allocated into static variables. This data gets released when the application ends. You can make a call to XMLPlatformUtil::terminate() to release all the lazily allocated variables before you exit your program.

Is EBCDIC supported?

Yes, Xerces-C supports EBCDIC. When creating EBCDIC encoded XML data, the preferred encoding is ibm1140. Also supported is ibm037 (and its alternate name, ebcdic-cp-us); this encoding is almost the same as ibm1140, but it lacks the Euro symbol.

These two encodings, ibm1140 and ibm037, are available on both Xerces-C and IBM XML4C, on all platforms.

On IBM System 390, XML4C also supports two alternative forms, ibm037-s390 and ibm1140-s390. These are similar to the base ibm037 and ibm1140 encodings, but with alternate mappings of the EBCDIC new-line character, which allows them to appear as normal text files on System 390s. These encodings are not supported on other platforms, and should not be used for portable data.

XML4C on System 390 and AS/400 also provides additional EBCDIC encodings, including those for the character sets of different countries. The exact set supported will be platform dependent, and these encodings are not recommended for portable XML data.