| <?xml version="1.0" encoding = "iso-8859-1" standalone="no"?> |
| <!DOCTYPE faqs SYSTEM "./dtd/faqs.dtd"> |
| |
| <faqs title="Parsing with &XercesCName;"> |
| |
| <faq title="Does &XercesCName; support Schema?"> |
| |
| <q> Does &XercesCName; support Schema?</q> |
| |
| <a> |
| |
| <p>The &XercesCName; &XercesCVersion; contains an implementation |
| of a subset of the W3C XML Schema Language as specified |
| in the 2 May 2001 Recommendation for <jump |
| href="http://www.w3.org/TR/xmlschema-1/">Structures</jump> |
| and <jump href="http://www.w3.org/TR/xmlschema-2/"> |
| Datatypes</jump>. See <jump href="schema.html">the Schema |
| page</jump> for details.</p> |
| |
| </a> |
| </faq> |
| |
| <faq title="Why &XercesCName; does not support this particular Schema feature?"> |
| |
| <q> Why &XercesCName; does not support this particular Schema feature?</q> |
| |
| <a> |
| |
| <p>The &XercesCName; &XercesCVersion; contains an implementation |
| of a subset of the W3C XML Schema Language as specified |
| in the 2 May 2001 Recommendation for <jump |
| href="http://www.w3.org/TR/xmlschema-1/">Structures</jump> |
| and <jump href="http://www.w3.org/TR/xmlschema-2/"> |
| Datatypes</jump>. You should not consider this implementation |
| complete or correct. Please refer to <jump href="schema.html#limitation"> |
| the Schema Limitations </jump>for further details.</p> |
| |
| </a> |
| </faq> |
| |
| <faq title="Why does my application crash on AIX when I run it under a |
| multi-threaded environment?"> |
| |
| <q>Why does my application crash on AIX when I run it under a |
| multi-threaded environment?</q> |
| |
| <a> |
| |
| <p>AIX maintains two kinds of libraries on the system, thread-safe and |
| non-thread safe. Multi-threaded libraries on AIX follow a different naming |
| convention, Usually the multi-threaded library names are followed with "_r". |
| For example, libc.a is single threaded whereas libc_r.a is multi-threaded.</p> |
| |
| <p>To make your multi-threaded application run on AIX, you <em>must</em> |
| ensure that you do not have a "system library path" in your <code>LIBPATH</code> |
| environment variable when you run the application. The appropriate |
| libraries (threaded or non-threaded) are automatically picked up at runtime. An |
| application usually crashes when you build your application for multi-threaded |
| operation but don't point to the thread-safe version of the system libraries. |
| For example, LIBPATH can be simply set as:</p> |
| |
| <source>LIBPATH=$HOME/<&XercesCProjectName;>/lib</source> |
| |
| <p>Where <&XercesCProjectName;> points to the directory where the |
| &XercesCProjectName; application resides.</p> |
| |
| <p>If, for any reason unrelated to &XercesCProjectName;, you need to keep a |
| "system library path" in your LIBPATH environment variable, you must make sure |
| that you have placed the thread-safe path before you specify the normal system |
| path. For example, you must place <ref>/lib/threads</ref> before |
| <ref>/lib</ref> in your LIBPATH variable. That is to say your LIBPATH may look |
| like this:</p> |
| |
| <source>export LIBPATH=$HOME/<&XercesCProjectName;>/lib:/usr/lib/threads:/usr/lib</source> |
| |
| <p>Where /usr/lib is where your system libraries are.</p> |
| |
| </a> |
| </faq> |
| |
| <faq title="I cannot run the sample applications. What is wrong?"> |
| |
| <q>I cannot run the sample applications. What is wrong?</q> |
| |
| <a> |
| |
| <p>In order to run an application built using &XercesCProjectName; you must |
| set up your path and library search path properly. In the stand-alone version |
| from Apache, you must have the &XercesCName; runtime library available from |
| your path settings. On Windows this library is called <code>&XercesCWindowsDLL;.dll</code> which must be available from your <code>PATH</code> settings. (Note that now there are separate debug and release dlls for |
| Windows. If the release dll is named <code>&XercesCWindowsDLL;.dll</code> then the debug dll is named <code>&XercesCWindowsDLL;d.dll)</code>. On UNIX platforms the library is called <code>&XercesCUnixLib;.so</code> (or <code>.a</code> or <code>.sl</code>) which must be available from your <code>LD_LIBRARY_PATH</code> (or <code>LIBPATH</code> or <code>SHLIB_PATH</code>) environment variable.</p> |
| |
| <p>Thus, if you installed your binaries under <code>$HOME/fastxmlparser</code>, you need to point your library path to that directory.</p> |
| |
| <source>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)</source> |
| |
| <p>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 <code>icuuc.dll</code> and <code>icudata.dll</code> which must be available from your PATH settings. On UNIX, these |
| libraries are called <code>libicuuc.so</code> and <code>libicudata.so</code> (or <code>.sl</code> for HP-UX or <code>.a</code> for AIX) which must be available from your library search path.</p> |
| |
| </a> |
| </faq> |
| |
| <faq title="I just built my own application using the &XercesCName; parser. Why does it crash?"> |
| |
| <q>I just built my own application using the &XercesCName; parser. Why does |
| it crash?</q> |
| |
| <a> |
| |
| <p>In order to work with the &XercesCName; parser, you have to first |
| initialize the XML subsystem. The most common mistake is to forget this |
| initialization. Before you make any calls to &XercesCName; APIs, you must |
| call XMLPlatformUtils::Initialize(): </p> |
| |
| <source> |
| try { |
| XMLPlatformUtils::Initialize(); |
| } |
| catch (const XMLException& toCatch) { |
| // Do your failure processing here |
| }</source> |
| |
| <p>This initializes the &XercesCProjectName; system and sets its internal |
| variables. Note that you must the include <code>util/PlatformUtils.hpp</code> file for this to work.</p> |
| |
| </a> |
| </faq> |
| |
| <faq title="Is &XercesCName; thread-safe?"> |
| |
| <q>Is &XercesCName; thread-safe?</q> |
| |
| <a> |
| |
| <p>This is not a question that has a simple yes/no answer. Here are the |
| rules for using &XercesCName; in a multi-threaded environment:</p> |
| |
| <p>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.</p> |
| |
| <p>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.</p> |
| |
| <p>The same rules apply to &XercesCName; 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.</p> |
| |
| <p>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 <code>appendData()</code>, are not thread safe and the application must guarantee that no other |
| methods (including const methods) are executed concurrently with them.</p> |
| |
| <p>The application also needs to guarantee that only one thread has entered the |
| method XMLPlatformUtils::Initialize() at any one time. And similarly only one |
| thread has entered the method XMLPlatformUtils::Terminate() at any one time.</p> |
| |
| </a> |
| </faq> |
| |
| <faq title="Can't debug into the &XercesCName; DLL with the MSVC debugger"> |
| |
| <q> 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?</q> |
| |
| <a> |
| |
| <p>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 &XercesCName; library, you'll need the .pdb files, and to get those, you'll |
| need to rebuild the &XercesCName; library.</p> |
| |
| </a> |
| </faq> |
| |
| <faq title="First-chance exception in Microsoft debugger"> |
| |
| <q>"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.</q> |
| |
| <a> |
| |
| <p>&XercesCName; 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.</p> |
| |
| <p>To stop this from happening do this:</p> |
| |
| <ul> |
| <li>start debugging (so the debug menu appears)</li> |
| <li>from the debug menu select "Exceptions"</li> |
| <li>from the box that opens select "Microsoft C++ Exception" and set it |
| to "Stop if not handled" instead of "stop always".</li> |
| </ul> |
| |
| <p>You'll still land in the debugger if your program is terminating |
| abnormally, but it will be at your problem, not from the internal &XercesCName; |
| exceptions.</p> |
| |
| </a> |
| </faq> |
| |
| <faq title="I am seeing memory leaks in &XercesCName;. Are they real?"> |
| |
| <q>I am seeing memory leaks in &XercesCName;. Are they real?</q> |
| |
| <a> |
| |
| <p>The &XercesCName; 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 <code>XMLPlatformUtils::Terminate()</code> before your application exits. This will free all memory that was being |
| held by the library.</p> |
| |
| <p>For most applications, the use of <code>Terminate()</code> is optional. The system will recover all memory when the application |
| process shuts down. The exception to this is the use of &XercesCName; from DLLs |
| that will be repeatedly loaded and unloaded from within the same process. To |
| avoid memory leaks with this kind of use, <code>Terminate()</code> must be called before unloading the &XercesCName; library</p> |
| |
| <p>To ensure all the memory held by the parser are freed, the number of XMLPlatformUtils::Terminate() calls |
| should match the number of XMLPlatformUtils::Initialize() calls. |
| </p> |
| </a> |
| </faq> |
| |
| <faq title="Can I validate the data contained in a DOM tree?"> |
| |
| <q>Is there a facility in &XercesCName; to validate the data contained in a |
| DOM tree? That is, without saving and re-parsing the source document?</q> |
| |
| <a> |
| |
| <p>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.</p> |
| |
| </a> |
| </faq> |
| |
| <faq title="Can I use Xerces to perform write validation"> |
| |
| <q>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.)</q> |
| |
| <a> |
| |
| <p>The answers are: "No" and "No." Write Validation is a commonly requested |
| feature, but &XercesCName; does not have it yet.</p> |
| |
| <p>The best you can do for now is to create the DOM document, write it back |
| as XML and re-parse it.</p> |
| |
| </a> |
| </faq> |
| |
| <faq title="Why does my multi-threaded application crash on Solaris?"> |
| |
| <q>Why does my multi-threaded application crash on Solaris?</q> |
| |
| <a> |
| |
| <p>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 |
| <jump href="http://sunsolve.sun.com">SunSolve.sun.com</jump> 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.</p> |
| |
| </a> |
| </faq> |
| |
| <faq title="Why does my application gives unresolved linking errors on Solaris?"> |
| |
| <q>Why does my application gives unresolved linking errors on Solaris?</q> |
| |
| <a> |
| |
| <p>On Solaris there are a few things that need to be done before you |
| execute your application using &XercesCName;. In case you're using the |
| binary build of &XercesCName; 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 &XercesCName; 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.</p> |
| |
| <p>Also check that the library path is set properly and that the correct |
| versions of <code>gmake</code> and <code>autoconf</code> are on your system.</p> |
| |
| </a> |
| </faq> |
| |
| <faq title="Why do I get Internal Compiler Error when compiling &XercesCName; for a 64bit target with gcc?"> |
| <q>Why do I get Internal Compiler Error when compiling &XercesCName; for a 64bit target with gcc?</q> |
| <a> |
| <p>This is a compiler problem. Try turning off optimization to bypass the problem.</p> |
| </a> |
| </faq> |
| |
| |
| <faq title="How are entity reference nodes handled in DOM?"> |
| |
| <q>How are entity reference nodes handled in DOM?</q> |
| |
| <a> |
| |
| <p>If you are using the native DOM classes, the function <code>setExpandEntityReferences</code> 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.</p> |
| |
| <p>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.</p> |
| |
| </a> |
| </faq> |
| |
| <faq title="What kinds of URLs are currently supported in &XercesCName;?"> |
| |
| <q>What kinds of URLs are currently supported in &XercesCName;?</q> |
| |
| <a> |
| |
| <p>The <code>XMLURL</code> class provides for limited URL support. It understands the <code>file://, http://</code>, and <code>ftp://</code> 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.</p> |
| |
| <p>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 <code>file:///</code> and <code>file://localhost/</code>, i.e. only when the URL refers to a local file.</p> |
| |
| <p>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.</p> |
| |
| </a> |
| </faq> |
| |
| <faq title="How can I add support for URLs with HTTP/FTP protocols?"> |
| |
| <q>How can I add support for URLs with HTTP/FTP protocols?</q> |
| |
| <a> |
| |
| <p>Support for the http: protocol is now included by default on all |
| platforms.</p> |
| |
| <p>To address the need to make remote connections to resources specified |
| using additional protocols, ftp for example, &XercesCName; provides the <code>NetAccessor</code> interface. The header file is <code>src/util/XMLNetAccessor.hpp</code>. This interface allows you to plug in your own implementation of URL |
| networking code into the &XercesCName; parser.</p> |
| |
| </a> |
| </faq> |
| |
| <faq title="Can I use &XercesCName; to parse HTML?"> |
| |
| <q>Can I use &XercesCName; to parse HTML?</q> |
| |
| <a> |
| |
| <p>Yes, but only if the HTML follows the rules given in the |
| <jump href="http://www.w3.org/TR/REC-xml">XML specification</jump>. Most HTML, |
| however, does not follow the XML rules, and will generate XML well-formedness |
| errors.</p> |
| |
| </a> |
| </faq> |
| |
| <faq title="I keep getting an error: "invalid UTF-8 character". What's wrong?"> |
| |
| <q>I keep getting an error: "invalid UTF-8 character". What's wrong?</q> |
| |
| <a> |
| |
| <p>Most commonly, the XML <code>encoding =</code> 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.</p> |
| |
| <p>The XML declaration should look something like this:</p> |
| |
| <p><code><?xml version="1.0" encoding="iso-8859-1"?></code></p> |
| |
| <p>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.</p> |
| |
| <p>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 <jump href="http://www.w3.org/TR/REC-xml#charsets">XML |
| spec</jump>, sections 2.2 and 4.1 for details. If the parser is generating an <code>Invalid character (Unicode: 0x???)</code> 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.</p> |
| |
| </a> |
| </faq> |
| |
| <faq title="What encodings are supported by Xerces-C / XML4C?"> |
| |
| <q>What encodings are supported by Xerces-C / XML4C?</q> |
| |
| <a> |
| |
| <p>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.</p> |
| |
| <p>XML4C -- the version of Xerces-C available from IBM -- extends this |
| set to include the encodings listed in the table below.</p> |
| |
| <table> |
| <tr> |
| <td><em>Common Name</em></td> |
| <td><em>Use this name in XML</em></td> |
| </tr> |
| <tr> |
| <td>8 bit Unicode</td> |
| <td>UTF-8</td> |
| </tr> |
| <tr> |
| <td>ISO Latin 1</td> |
| <td>ISO-8859-1</td> |
| </tr> |
| <tr> |
| <td>ISO Latin 2</td> |
| <td>ISO-8859-2</td> |
| </tr> |
| <tr> |
| <td>ISO Latin 3</td> |
| <td>ISO-8859-3</td> |
| </tr> |
| <tr> |
| <td>ISO Latin 4</td> |
| <td>ISO-8859-4</td> |
| </tr> |
| <tr> |
| <td>ISO Latin Cyrillic</td> |
| <td>ISO-8859-5</td> |
| </tr> |
| <tr> |
| <td>ISO Latin Arabic</td> |
| <td>ISO-8859-6</td> |
| </tr> |
| <tr> |
| <td>ISO Latin Greek</td> |
| <td>ISO-8859-7</td> |
| </tr> |
| <tr> |
| <td>ISO Latin Hebrew</td> |
| <td>ISO-8859-8</td> |
| </tr> |
| <tr> |
| <td>ISO Latin 5</td> |
| <td>ISO-8859-9</td> |
| </tr> |
| <tr> |
| <td>EBCDIC US</td> |
| <td>ebcdic-cp-us</td> |
| </tr> |
| <tr> |
| <td>EBCDIC with Euro symbol</td> |
| <td>ibm1140</td> |
| </tr> |
| <tr> |
| <td>Chinese, PRC</td> |
| <td>gb2312</td> |
| </tr> |
| <tr> |
| <td>Chinese, Big5</td> |
| <td>Big5</td> |
| </tr> |
| <tr> |
| <td>Cyrillic</td> |
| <td>koi8-r</td> |
| </tr> |
| <tr> |
| <td>Japanese, Shift JIS</td> |
| <td>Shift_JIS</td> |
| </tr> |
| <tr> |
| <td>Korean, Extended UNIX code</td> |
| <td>euc-kr</td> |
| </tr> |
| </table> |
| |
| <p>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.</p> |
| |
| </a> |
| </faq> |
| |
| <faq |
| title="What character encoding should I use when creating XML documents?"> |
| |
| <q>What character encoding should I use when creating XML documents?</q> |
| |
| <a> |
| |
| <p>The best choice in most cases is either utf-8 or utf-16. Advantages of |
| these encodings include:</p> |
| |
| <ul> |
| <li>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.</li> |
| <li>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.</li> |
| <li>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.</li> |
| </ul> |
| |
| <p>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.</p> |
| |
| <p>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.</p> |
| |
| <p>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.</p> |
| |
| <p>A word of caution for Windows users: The default character set on |
| Windows systems is windows-1252, not iso-8859-1. While &XercesCName; 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 <code>encoding="..."</code> declaration.</p> |
| |
| </a> |
| </faq> |
| |
| <faq |
| title="I find memory leaks in &XercesCName;. How do I eliminate it?"> |
| |
| <q>I find memory leaks in &XercesCName;. How do I eliminate it?</q> |
| |
| <a> |
| |
| <p>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.</p> |
| |
| <p>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 <code>XMLPlatformUtil::terminate()</code> to release all the lazily allocated variables before you exit your |
| program.</p> |
| |
| <p>To ensure all the memory held by the parser are freed, the number of XMLPlatformUtils::Terminate() calls |
| should match the number of XMLPlatformUtils::Initialize() calls. |
| </p> |
| </a> |
| </faq> |
| |
| <faq title="Is EBCDIC supported?"> |
| |
| <q>Is EBCDIC supported?</q> |
| |
| <a> |
| |
| <p>Yes, &XercesCName; 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.</p> |
| |
| <p>These two encodings, ibm1140 and ibm037, are available on both |
| Xerces-C and IBM XML4C, on all platforms.</p> |
| |
| <p>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.</p> |
| |
| <p>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.</p> |
| |
| </a> |
| </faq> |
| |
| <faq title="How to write out a DOM tree into an XML file?"> |
| <q>How to write out a DOM tree into an XML file?</q> |
| <a> |
| <p>This feature is not yet availabe in the parser. Take a look at the DOMPrint sample |
| for an example on parsing XML file, then writing it out back to the screen. You |
| can use that code.</p> |
| </a> |
| </faq> |
| |
| <faq title="Is it OK to call the XMLPlatformUtils::Initialize/Terminate pair of routines multiple times in one program?"> |
| <q>Is it OK to call the XMLPlatformUtils::Initialize/Terminate pair of routines multiple times in one program?</q> |
| <a> |
| <p>Yes. The code has been enhanced so that calling XMLPlatformUtils::Initialize/Terminate pair of routines |
| multiple times in one process is now allowed. |
| </p> |
| |
| <p>But the application needs to guarantee that only one thread has entered the |
| method XMLPlatformUtils::Initialize() at any one time. And similarly only one |
| thread has entered the method XMLPlatformUtils::Terminate() at any one time. |
| </p> |
| |
| <p>If you are calling XMLPlatformUtils::Initialize() a number of times, and then follow with |
| XMLPlatformUtils::Terminate() the same number of times, only the first XMLPlatformUtils::Initialize() |
| will do the initialization, and only the last XMLPlatformUtils::Terminate() will clean up |
| the memory. The other calls are ignored. |
| </p> |
| <p>To ensure all the memory held by the parser are freed, the number of XMLPlatformUtils::Terminate() calls |
| should match the number of XMLPlatformUtils::Initialize() calls. |
| </p> |
| <p> |
| Consider the following code snippets (for illustration simplicity the following |
| sample code is not coded in try/catch clause): |
| </p> |
| |
| <source> |
| // The XMLPlatformUtils::Initialize/Terminate calls are paired. |
| { |
| // Initialize the parser |
| XMLPlatformUtils::Initialize(); |
| |
| SAXParser parser; |
| parser.parse(xmlFile); |
| |
| // Free all memory that was being held by the parser |
| XMLPlatformUtils::Terminate(); |
| |
| // Initialize the parser |
| XMLPlatformUtils::Initialize(); |
| |
| SAXParser parser; |
| parser.parse(xmlFile); |
| |
| // Free all memory that was being held by the parser |
| XMLPlatformUtils::Terminate(); |
| } |
| </source> |
| |
| <source> |
| // calls XMLPlatformUtils::Initialize() three times |
| // then calls XMLPlatformUtils::Terminate() numerous times |
| { |
| // Initialize the parser |
| XMLPlatformUtils::Initialize(); |
| |
| // The next two calls are no-op |
| XMLPlatformUtils::Initialize(); |
| XMLPlatformUtils::Initialize(); |
| |
| SAXParser parser; |
| parser.parse(xmlFile); |
| |
| // The first two XMLPlatformUtils::Terminate() calls are no-op |
| XMLPlatformUtils::Terminate(); |
| XMLPlatformUtils::Terminate(); |
| |
| // This third XMLPlatformUtils::Terminate() will free all memory that was being held by the parser |
| XMLPlatformUtils::Terminate(); |
| |
| // This extra fourth XMLPlatformUtils::Terminate() call is no-op. |
| // However calling XMLPlatformUtils::Terminate() without a matching XMLPlatformUtils::Initialize() |
| // is dangerous and should be avoided. |
| XMLPlatformUtils::Terminate(); |
| } |
| </source> |
| </a> |
| </faq> |
| |
| <faq title="Why does deleting a transcoded string result in assertion on windows?"> |
| <q>Why does deleting a transcoded string result in assertion on windows?</q> |
| <a> |
| <p>Both your application program and the Xerces DLL must use the same *DLL* version of the |
| runtime library. If either statically links to the runtime library, the |
| problem will still occur. |
| |
| For example, for a Win32/VC6 build, the runtime library build setting MUST |
| be "Multithreaded DLL" for release builds and "Debug Multithreaded DLL" for |
| debug builds.</p> |
| </a> |
| </faq> |
| |
| <faq title="How do I transcode to/from something besides the local code page?"> |
| <q>How do I transcode to/from something besides the local code page?</q> |
| <a> |
| <p>XMLString::transcode() will transcode from XMLCh to the local code page, and |
| other APIs which take a char* assume that the source text is in the local |
| code page. If this is not true, you must transcode the text yourself. You |
| can do this using local transcoding support on your OS, such as Iconv on |
| Unix or or IBM's ICU package. However, if your transcoding needs are simple, |
| you can achieve some better portability by using the Xerces parser's |
| transcoder wrappers. You get a transcoder like this: |
| </p> |
| <ul> |
| <li> |
| 1. Call XMLPlatformUtils::fgTransServer->MakeNewTranscoderFor() and provide |
| the name of the encoding you wish to create a transcoder for. This will |
| return a transcoder to you, which you own and must delete when you are |
| through with it. |
| |
| NOTE: You must provide a maximum block size that you will pass to the transcoder |
| at one time, and you must blocks of characters of this count or smaller when |
| you do your transcoding. The reason for this is that this is really an |
| internal API and is used by the parser itself to do transcoding. The parser |
| always does transcoding in known block sizes, and this allows transcoders to |
| be much more efficient for internal use since it knows the max size it will |
| ever have to deal with and can set itself up for that internally. In |
| general, you should stick to block sizes in the 4 to 64K range. |
| </li> |
| <li> |
| 2. The returned transcoder is something derived from XMLTranscoder, so they |
| are all returned to you via that interface. |
| </li> |
| <li> |
| 3. This object is really just a wrapper around the underlying transcoding |
| system actually in use by your version of Xerces, and does whatever is |
| necessary to handle differences between the XMLCh representation and the |
| representation uesd by that underying transocding system. |
| </li> |
| <li> |
| 4. The transcoder object has two primary APIs, transcodeFrom() and |
| transcodeTo(). These transcode between the XMLCh format and the encoding you |
| indicated. |
| </li> |
| <li> |
| 5. These APIs will transcode as much of the source data as will fit into the |
| outgoing buffer you provide. They will tell you how much of the source they |
| ate and how much of the target they filled. You can use this information to |
| continue the process until all source is consumed. |
| </li> |
| <li> |
| 6. char* data is always dealt with in terms of bytes, and XMLCh data is |
| always dealt with in terms of characters. Don't mix up which you are dealing |
| with or you will not get the correct results, since many encodings don't |
| have a one to one relationship of characters to bytes. |
| </li> |
| <li> |
| 7. When transcoding from XMLCh to the target encoding, the transcodeTo() |
| method provides an 'unrepresentable flag' parameter, which tells the |
| transcoder how to deal with an XMLCh code point that cannot be converted |
| legally to the target encoding, which can easily happen since XMLCh is |
| Unicode and can represent thousands of code points. The options are to use a |
| default replacement character (which the underlying transcoding service will |
| choose, and which is guaranteed to be legal for the target encoding), or to |
| throw an exception. |
| </li> |
| </ul> |
| </a> |
| </faq> |
| |
| <faq title="Why DOM_Node::cloneNode() does not clone the pointer assigned to a DOM_Node via DOM_Node::setUserData()?"> |
| <q>Why DOM_Node::cloneNode() does not clone the pointer assigned to a DOM_Node via DOM_Node::setUserData()?</q> |
| <a> |
| <p>There are several possible options for how cloneNode should handle userData: |
| </p> |
| <ul> |
| <li> |
| 1) Copy the pointer. May be a Very Bad Idea if you really wanted the data |
| associated with a particular node object. |
| </li> |
| <li> |
| 2) Clone the object being pointed at. Maybe a Very Bad Idea if that object, |
| in turn, wasn't designed to be cloned at this time. |
| </li> |
| <li> |
| 3) A complex call-back API has been proposed which would allow the userData |
| object to tell the DOM which of these three options should be taken, but |
| that would require that only objects implementing that API be registered as |
| userData. That doesn't seem to be a good option. |
| </li> |
| <li> |
| 4) Do nothing. This is by far the lowest-overhead and safest choice. And |
| since cloneNode is a DOM operation, and userData is _not_ defined by the |
| standard DOM API, one can make a very strong case for this being the "most |
| correct" option. |
| </li> |
| </ul> |
| <p> |
| We chose (4), very deliberately. If you want one of the others, you can |
| implement it by creating your own wrapper operation for cloneNode() and |
| calling that. |
| </p> |
| <p> |
| NOTE that userData should be considered a nonportable, experimental feature |
| of the Xerces DOM. It may evaporate entirely in favor of a scheme based on |
| the DOM Level 3 "node key" mechanism, when that becomes officially |
| available. |
| </p> |
| </a> |
| </faq> |
| |
| </faqs> |
