BUILDINSTRUCTIONS.TXT
=====================

****************************************************************************

WARNING: This is not the best place to look for build instructions. You
should go to http://xml.apache.org/xerces-c/build.html to see the
latest stuff. The web-page is maintained more regularly than this text
file.

However, if you insist, here is a text dump of the same web-page from
ancient times.

End of warning!

****************************************************************************

This page has sections on the following topics:

* Building Xerces-C++ on Windows NT/98
* Building Xerces-C++ on Windows using Visual Age C++
* Building Xerces-C++ on Windows using Borland C++Builder
* Building Xerces-C++ on UNIX platforms
* Building Xerces-C++ as a single-threaded library on Unix platforms
* Building on iSeries (AS/400)
* Building Xerces-C++ on OS/2 using Visual Age C++
* Building Xerces-C++ on Macintosh
* Building Xerces-C++ with ICU using bundled Perl scripts on Windows
* Building Xerces-C++ COM Wrapper on Windows
* Building User Documentation
* I wish to port Xerces to my favourite platform. Do you have any
* suggestions?
* What should I define XMLCh to be?
* Where can I look for more help?

Building Xerces-C++ on Windows NT/98
====================================

    Xerces-C++ comes with Microsoft Visual C++ projects and
    workspaces to help you build Xerces-C++. The following describes the
    steps you need to build Xerces-C++.

    Building Xerces-C++ library
    ----------------------------

        To build Xerces-C++ from it source (using MSVC), you will need to open the
        workspace containing the project. If you are building your application, you may
        want to add the Xerces-C++ project inside your applications's workspace.

        The workspace containing the Xerces-C++ project file and all other samples is:

           xerces-c-src1_7_0\Projects\Win32\VC6\xerces-all\xerces-all.dsw

        Once you are inside MSVC, you need to build the project marked XercesLib.

        If you want to include the Xerces-C++ project separately, you need to pick up:

           xerces-c-src1_7_0\Projects\Win32\VC6\xerces-all\XercesLib\XercesLib.dsp

        You must make sure that you are linking your application with the xerces-c_1.lib
        library and also make sure that the associated DLL is somewhere in your path.


           If you are working on the AlphaWorks version which uses ICU, you must have
           the ICU data DLL named icudata.dll available from your path setting. For
           finding out where you can get ICU from and build it, look at the How to Build
           ICU.

    Building samples
    ----------------

        If you are using the source package, inside the same workspace (xerces-all.dsw),
        you'll find several other projects. These are for the samples. Select all the samples
        and right click on the selection. Then choose "Build (selection only)" to build all the
        samples in one shot.

        If you are using the binary package, load the
        xerces-c1_7_0-win32\samples\Projects\Win32\VC6\samples.dsw Microsoft Visual
        C++ workspace inside your MSVC IDE. Then select all the samples and right click
        on the selection. Then choose "Build (selection only)" to build all the samples in
        one shot.


Building Xerces-C++ on Windows using Visual Age C++
===================================================

    A few unsupported projects are also packaged with Xerces-C++. Due
    to origins of Xerces-C++ inside IBM labs, we do have projects for IBM's
    Visual Age C++ compiler on Windows. The following describes the
    steps you need to build Xerces-C++ using Visual Age C++.

    Building Xerces-C++ library
    ---------------------------

        Requirements:

           * VisualAge C++ Version 4.0 with Fixpak 1:
             Download the Fixpak from the IBM VisualAge C++ Corrective Services web
             page.

        To include the ICU library:

           * ICU Build:
             You should have the ICU Library in the same directory as the Xerces-C++
             library. For example if Xerces-C++ is at the top level of the d drive, put the
             ICU library at the top level of d e.g. d:/xerces-c1_7_0 d:/icu.

        Instructions:

           1.Change the directory to d:\xerces-c1_7_0\Projects\Win32
           2.If a d:\xerces-c1_7_0\Project\Win32\VACPP40 directory does not exist,
             create it.
           3.Copy the IBM VisualAge project file, XML4C2X.icc, to the VACPP40
             directory.
           4.From the VisualAge main menu enter the project file name and path.
           5.When the build finishes the status bar displays this message: Last Compile
             completed Successfully with warnings on date.


           These instructions assume that you install in drive d:\. Replace d with the
           appropriate drive letter.

Building Xerces-C++ on Windows using Borland C++Builder
=======================================================

    Xerces-C++ comes with Borland C++Builder projects to help you build
    Xerces-C++. The following describes the steps you need to build
    Xerces-C++.

    Building Xerces-C++ library
    ---------------------------

        The library and demo projects are all contained in the Xerces-all project group:

           * xerces-c-src1_7_0\Projects\Win32\BCB6\Xerces-all\Xerces-all.bpg

        Each project in the group refers a directory belog \Xerces-all. For example, the
        XercesLib project files are contained in the directory

           * xerces-c-src1_7_0\Projects\Win32\BCB6\Xerces-all\XercesLib

        To build any project, open the project manager. Double click on the project name.
        Then select "Project|Build" from the menu. For example, double click on
        XercesLib.dll in the manager. Then select "Project|Build XercesLib" from the menu.
        Once the library has been built, include XercesLib.lib with in application's project
        and place XercesLib.dll somewhere in your path.

Building Xerces-C++ on UNIX platforms
=====================================

    Xerces-C++ uses GNU tools like Autoconf and GNU Make to build the system. You must first make sure you have these tools installed on your system before
    proceeding. If you don not have required tools, ask your system administrator to get them for you. These tools are free under the GNU Public Licence and
    may be obtained from the Free Software Foundation.

    Do not jump into the build directly before reading this.

    Spending some time reading the following instructions will save you a lot of wasted time and support-related e-mail communication. The Xerces-C++ build
    instructions are a little different from normal product builds. Specifically, there are some wrapper-scripts that have been written to make life easier for you. You
    are free not to use these scripts and use Autoconf and GNU Make directly, but we want to make sure you know what you are by-passing and what risks you
    are taking. So read the following instructions carefully before attempting to build it yourself.

    Besides having all necessary build tools, you also need to know what compilers we have tested Xerces-C++ on. The following table lists the relevant
    platforms and compilers.

        Operating System                      C++, C Compilers
        ----------------                      ----------------
        Redhat Linux 7.2                      g++, gcc (egcs)
        AIX 4.3                               xlC_r, xlc_r
        Solaris 2.6                           CC, cc
        HP-UX 11                              aCC, cc

    If you are not using any of these compilers, you are taking a calculated risk by exploring new grounds. Your effort in making Xerces-C++ work on this new
    compiler is greatly appreciated and any problems you face can be addressed on the Xerces-C mailing list.

    Differences between the UNIX platforms: The description below is generic, but as every programmer is aware, there are minor differences within the
    various UNIX flavors the world has been bestowed with. The one difference that you need to watch out in the discussion below, pertains to the system
    environment variable for finding libraries. On Linux and Solaris, the environment variable name is called LD_LIBRARY_PATH, on AIX it is LIBPATH, while on
    HP-UX it is SHLIB_PATH. The following discussion assumes you are working on Linux, but it is with subtle understanding that you know how to interpret it for
    the other UNIX flavors.

    If you wish to build Xerces-C++ with ICU, look at the Building ICU. It tells you where you can get ICU and how to build Xerces-C++ with it.

    Setting build environment variables
    -----------------------------------

        Before doing the build, you must first set your environment variables to pick-up the
        compiler and also specify where you extracted Xerces-C++ on your machine.
        While the first one is probably set for you by the system administrator, just make
        sure you can invoke the compiler. You may do so by typing the compiler invocation
        command without any parameters (e.g. xlc_r, or g++, or cc) and check if you get a
        proper response back.

        Next set your Xerces-C++ root path as follows:

           export XERCESCROOT=<full path to xerces-c-src1_7_0>

        This should be the full path of the directory where you extracted Xerces-C++.

    Building Xerces-C++ library
    ---------------------------

        As mentioned earlier, you must be ready with the GNU tools like autoconf and gmake before you attempt the build.

        The autoconf tool is required on only one platform and produces a set of portable scripts (configure) that you can run on all other platforms without actually having the autoconf tool
        installed everywhere. In all probability the autoconf-generated script (called configure) is already in your src directory. If not, type:

           cd $XERCESCROOT/src
           autoconf

        This generates a shell-script called configure. It is tempting to run this script directly as is normally the case, but wait a minute. If you are using the default compilers like gcc and g++
        you do not have a problem. But if you are not on the standard GNU compilers, you need to export a few more environment variables before you can invoke configure.

        Rather than make you to figure out what strange environment variables you need to use, we have provided you with a wrapper script that does the job for you. All you need to tell the script
        is what your compiler is, and what options you are going to use inside your build, and the script does everything for you. Here is what the script takes as input:

           runConfigure: Helper script to run "configure" for one of the supported platforms
           Usage: runConfigure "options"
                where options may be any of the following:
                -p <platform> (accepts 'aix', 'linux', 'solaris',
                     'hp-10', 'hp-11', 'unixware', 'os400', 'irix', 'ptx', 'tru64', 'macosx' )
                -c <C compiler name> (e.g. gcc, cc, xlc_r, icc)
                -x <C++ compiler name> (e.g. g++, CC, xlC_r, icc, c++)
                -d (specifies that you want to build debug version)
                -m <message loader> can be 'inmem', 'icu', 'MsgFile' or 'iconv'
                -n <net accessor> can be 'fileonly', 'libwww', 'socket' or 'native'
                -t <transcoder> can be 'icu', 'Iconv400', 'Iconv390' or 'native'
                -r <thread option> can be 'pthread' or 'dce' (only used on aix, HP-11 and solaris) or 'sproc' (only on IRIX) or 'none'
                -l <extra linker options>
                -z <extra compiler options>
                -P <install-prefix>
                -C <any one extra configure options>
                -h (to get help on the above commands)

        Xerces-C++ can be built as either a standalone library or as a library dependent on International Components for Unicode (ICU). For simplicity, the following discussion only explains
        standalone builds.

        One of the common ways to build Xerces-C++ is as follows:

           runConfigure -plinux -cgcc -xg++ -minmem -nsocket -tnative -rpthread

        The response will be something like this:

           Generating makefiles with the following options ...
           Platform: linux
           C Compiler: gcc
           C++ Compiler: g++
           Extra compile options:
           Extra link options:
           Message Loader: inmem
           Net Accessor: socket
           Transcoder: native
           Thread option: pthread
           Extra configure options:
           Debug is OFF

           creating cache ./config.cache
           checking for gcc... gcc
           checking whether the C compiler (gcc  -O -DXML_USE_NATIVE_TRANSCODER -DXML_USE_INMEM_MESSAGELOADER -DXML_USE_PTHREADS -DXML_USE_NETACCESSOR_SOCKET ) works... yes
           checking whether the C compiler (gcc  -O -DXML_USE_NATIVE_TRANSCODER -DXML_USE_INMEM_MESSAGELOADER -DXML_USE_PTHREADS -DXML_USE_NETACCESSOR_SOCKET ) is a cross-compiler... no
           checking whether we are using GNU C... yes
           checking whether gcc accepts -g... yes
           checking for c++... g++
           checking whether the C++ compiler (g++  -O -DXML_USE_NATIVE_TRANSCODER -DXML_USE_INMEM_MESSAGELOADER -DXML_USE_PTHREADS -DXML_USE_NETACCESSOR_SOCKET ) works... yes
           checking whether the C++ compiler (g++  -O -DXML_USE_NATIVE_TRANSCODER -DXML_USE_INMEM_MESSAGELOADER -DXML_USE_PTHREADS -DXML_USE_NETACCESSOR_SOCKET ) is a cross-compiler... no
           checking whether we are using GNU C++... yes
           checking whether g++ accepts -g... yes
           checking for a BSD compatible install... /usr/bin/install -c
           checking for autoconf... autoconf
           checking how to run the C preprocessor... gcc -E
           checking for ANSI C header files... yes
           checking for XMLByte... no
           checking host system type... i686-pc-linux-gnu
           updating cache ./config.cache
           creating ./config.status
           creating Makefile
           creating util/Makefile
           creating util/Transcoders/ICU/Makefile
           creating util/Transcoders/Iconv/Makefile
           creating util/Transcoders/Iconv390/Makefile
           creating util/Transcoders/Iconv400/Makefile
           creating util/Transcoders/MacOSUnicodeConverter/Makefile
           creating util/Platforms/Makefile
           creating util/Platforms/Solaris/Makefile
           creating util/Platforms/AIX/Makefile
           creating util/Platforms/Linux/Makefile
           creating util/Platforms/HPUX/Makefile
           creating util/Platforms/OS390/Makefile
           creating util/Platforms/OS400/Makefile
           creating util/Platforms/IRIX/Makefile
           creating util/Platforms/PTX/Makefile
           creating util/Platforms/UnixWare/Makefile
           creating util/Platforms/Tru64/Makefile
           creating util/Platforms/MacOS/Makefile
           creating util/Compilers/Makefile
           creating util/MsgLoaders/InMemory/Makefile
           creating util/MsgLoaders/ICU/Makefile
           creating util/MsgLoaders/MsgCatalog/Makefile
           creating util/MsgLoaders/MsgFile/Makefile
           creating util/NetAccessors/Socket/Makefile
           creating util/NetAccessors/libWWW/Makefile
           creating util/NetAccessors/MacOSURLAccess/Makefile
           creating util/regx/Makefile
           creating validators/Makefile
           creating validators/common/Makefile
           creating validators/datatype/Makefile
           creating validators/DTD/Makefile
           creating validators/schema/Makefile
           creating framework/Makefile
           creating dom/Makefile
           creating idom/Makefile
           creating parsers/Makefile
           creating internal/Makefile
           creating sax/Makefile
           creating sax2/Makefile
           creating ../obj/Makefile

           Having build problems? Read instructions at http://xml.apache.org/xerces-c/build.html
           Still cannot resolve it? Find out if someone else had the same problem before.
           Go to http://marc.theaimsgroup.com/?l=xerces-c-dev

           In future, you may also directly type the following commands to create the Makefiles.

           export TRANSCODER="NATIVE"
           export MESSAGELOADER="INMEM"
           export NETACCESSOR="Socket"
           export THREADS="pthread"
           export CC="gcc"
           export CXX="g++"
           export CXXFLAGS=" -O -DXML_USE_NATIVE_TRANSCODER -DXML_USE_INMEM_MESSAGELOADER -DXML_USE_PTHREADS -DXML_USE_NETACCESSOR_SOCKET"
           export CFLAGS=" -O -DXML_USE_NATIVE_TRANSCODER -DXML_USE_INMEM_MESSAGELOADER -DXML_USE_PTHREADS -DXML_USE_NETACCESSOR_SOCKET"
           export LDFLAGS=""
           export LIBS=" -lpthread "
           configure

           If the result of the above commands look OK to you, go to the directory
           $HOME/xerces-c-src1_7_0/src and type "gmake" to make the XERCES-C system.

        The error message concerning conf.h is NOT an indication of a problem. This code has been inserted to make it work on AS/400, but it gives this message which appears to be
        an error. The problem will be fixed in future.

        So now you see what the wrapper script has actually been doing! It has invoked configure to create the Makefiles in the individual sub-directories, but in addition to that, it has set a
        few environment variables to correctly configure your compiler and compiler flags too.

        Now that the Makefiles are all created, you are ready to do the actual build.

           gmake

        Is that it? Yes, that's all you need to build Xerces-C++.

    Building samples
    ----------------

        The installation process for the samples is same on all UNIX platforms.

           cd xerces-c1_7_0-linux/samples
           ./runConfigure -p<platform> -c<C_compiler> -x<C++_compiler>
           gmake

        This will create the object files in each sample directory and the executables in '
        xerces-c1_7_0-linux/bin' directory.

        Note that runConfigure is just a helper script and you are free to use ./configure
        with the correct parameters to make it work on any platform-compiler combination
        of your choice. The script needs the following parameters:

           Usage: runConfigure "options"
                  where options may be any of the following:
                  -p <platform> (accepts 'aix', 'unixware', 'linux', 'solaris',
           'hp-10', 'hp-11', 'os400', 'irix', 'ptx', 'tru64', 'macosx')
                  -c <C compiler name> (e.g. gcc, xlc or icc)
                  -x <C++ compiler name> (e.g. g++, xlC, or icc)
                  -d (specifies that you want to build debug version)
                  -h (get help on the above commands)
                  -z <extra compiler options>

        NOTE:The code samples in this section assume that you are are working on
        the Linux binary drop. If you are using some other UNIX flavor, please replace
        '-linux' with the appropriate platform name in the code samples.

        To delete all the generated object files and executables, type:

           gmake clean

Building Xerces-C++ as a single-threaded library on Unix platforms
==================================================================

    To build a single-threaded library on Unix platforms you have to update
    one or more of the following files Makefile.incl, Makefile.in,
    runConfigure. The following steps guide you to create a
    single-threaded library for each platform:

    For Aix -

        * Replace xlc_r and xlC_r libraries with xlc and xlC respectively
        * Replace makeC++SharedLib_r with makeC++SharedLib
        * Remove the flag -D_THREAD_SAFE
        * Remove inclusion of any threaded library directories from the
          LIBPATH
        * Remove inclusion of -lpthreads and -lpthread_compat
        * Add -DAPP_NO_THREADS to define the variable under AIX specific
          options in Makefile.incl

    For Solaris -

        * Add -DAPP_NO_THREADS to define the variable under SOLARIS
          specific options in Makefile.incl
        * Remove compiler switch -mt
        * Remove -D_REENTRANT flag from the 'compile' options
        * Remove inclusion of -lpthread

    For Linux -

        * Add -DAPP_NO_THREADS to define the variable under LINUX
          specific options in Makefile.incl
        * Remove -D_REENTRANT flag from the 'compile' options
        * Remove inclusion of -lpthread

    For HPUX -

        * Add -DAPP_NO_THREADS to define the variable under HP specific
          options in Makefile.incl
        * Remove inclusion of -lpthread and -lcma
        * Remove threading defines like -D_PTHREADS_DRAFT4 ,
        * -DXML_USE_DCE

Building on iSeries (AS/400)
============================

    The following addresses the requirements and build of Xerces-C++ natively on the iSeries.

    Building Xerces-C++ library
    ---------------------------

        Requirements:

           * OS/400 QSHELL interpreter installed (install base option 30, operating system)
           * OS/400 - Portable App Solutions Environment (PASE) installed (install base option 33, operating system)
           * QShell Utilities, PRPQ 5799-XEH
           * iSeries Tools for Developers, PRPQ 5799-PTL (these are the gnu utilities)

        Compiler:

           * For v4r5m0: ILE C++ for AS/400, PRPQ 5799-GDW
           * For v5: WebSphere Development ToolsSet, 5722-WDS ( installed option 52, Compiler - ILE C++)

        Recommendations:

           * There is one option when building the XML4C parser on iSeries. For code page translation, you can use the
             iSeries native Iconv400 support or ICU as the transcoder plugin. If you choose ICU, follow the instructions to
             build the ICU service program with the ICU download. Those instructions are not included here.
           * We recommend the use of Iconv400. The binary posted on Alphaworks uses Iconv400.

        Setup Instructions:

           * Make sure that you have the requirements installed on your iSeries. We highly recommend that you read the
             writeup that accompanies the iSeries Tools for Developers PRPQ. There are install instructions as well as
             information about how modules, programs and service programs can be created in Unix-like fashion using gnu
             utilities. Note that symbolic links are use in the file system to point to actual iSeries *module, *pgm and
             *srvpgm objects in libraries.
           * Download the source zip file (NT version) directly to an iSeries IFS directory after creating a directory (eg.
             /XML4Cxxx) and then extract the source using a mapped drive. To do this, from Windows Explorer, select Tools
             -> Map Network Drive. Then select an available drive (e.g. F:) and specify an iSeries system you want to extract
             the zip file to (e.g. \\<your iSeries name>\root). Click on Finish. Then find the .zip file and right click on it and
             select Extract To ... Then select the files you want to extract to the iSeries system.
           * Create iSeries target library. This library will be the target for the resulting modules and Xerces-C++ service
             program. You will specify this library on the OUTPUTDIR environment variable in step 4.
           * Set up the following environment variables in your build process (use ADDENVVAR or WRKENVVAR CL
             commands):

              XERCESCROOT - <the full path up to the Xerces-C++ src directory, but not including 'src'>
              MAKE   - '/usr/bin/gmake'
              OUTPUTDIR  - <identifies target iSeries library for *module, *pgm and *srvpgm objects>
              ICUROOT - (optional if using ICU)  <the path of your ICU includes>

           * For v4r5m0 systems, add QCXXN, to your build process library list. This results in the resolution of
             CRTCPPMOD used by the icc compiler.

           You may want to put the environment variables and library list setup instructions in a CL program so you will not forget
           these steps during your build.

        Configure

           To configure the make files for an iSeries build do the following under Qsh:

              qsh:
                 cd <full path to Xerces-C++>/src
                 runConfigure -p os400 -x icc -c icc -m inmem -t Iconv400

        Troubleshooting:

              error: configure: error: installation or configuration problem:
              C compiler cannot create executables.

           If during runConfigure you see the above error message, it can mean one of a few things. Either QCXXN is not on your
           library list OR the runConfigure cannot create the temporary modules (CONFTest1, etc) it uses to test out the
           compiler options or PASE is not installed. The second reason happens because the test modules already exist from a
           previous run of runConfigure. To correct the problem, do the following:

              CL:
                 DLTMOD <OUTPUTDIR library>/CONFT* and
                 DLTPGM <OUTPUTDIR library>/CONFT*

        Build

              qsh:
                 cd <full path to Xerces-C++>/src
                 gmake

           The above gmake should result in a service program being created in your specified library and a symbolic link to that
           service program placed in <path to Xerces-C++/lib>. It is highly possible that the service program will not create
           however due to number of modules and path names, see trouble shooting for the workaround.

           After the service program has successfully been created and a link established, you can either bind your XML
           application programs directly to the parser's service program via the BNDSRVPGM option on the CRTPGM or CRTSRVPGM
           command or you can specify a binding directory on your icc command. To specify an archive file to bind to, use the
           -L, -l binding options on icc. An archive file on iSeries is a binding directory. To create an archive file, use qar
           command. (see the iSeries Tools for Developers write up).

           After building the Xerces-C service program, create a binding directory by doing the following (note, this binding
           directory is used when building the samples. Also, note that the .a file below can have a different name based on the
           parser version (using apache xerces versioning)):

              qsh:
                 cd <full path to Xerces-C++>/lib
                 qar -cuv libxerces-c1_7_0.a *.o
              will results in
                 command = CRTBNDDIR BNDDIR(yourlib/libxercesc) TEXT('/yourlib/Xerces-C++/lib/libxerces-c1_7_0.a')
                 command = ADDBNDDIRE BNDDIR(yourlib/libxercesc) OBJ((yourlib/LIBXERCESC *SRVPGM) )

        Troubleshooting gmake problem:

           Due to the number of modules (the .o symbolic links) that make up the service program and the path to get to those
           modules, the qshell ld request to create the service program will likely fail because the request is too large, you may
           get a message like the following at the end of the gmake request:

              FAILURE: spawnp()  with errno = 3491
              GMAKE: vfork: Argument list too long.

           If this is the case, you can manually create the service progam by doing the following:

              CL:
                 CRTSRVPGM  (<OUTPUTDIR-library>/libxercesc)  MODULE(<OUTPUTDIR-library>/*ALL) EXPORT(*ALL) TEXT('XML4C parser version xxx')
                 OPTION(*DUPPROC *DUPVAR)

           Note that if you manually create the service program you want to make sure that you do not include any CONFT*
           modules or samples modules in the OUTPUTDIR library. After the service program is manually created you can add a
           symbolic link to the service program into the appropriate /lib directory by qsh:

              qsh:
                 cd <full path to Xerces-C++>/lib
                 ln -s /qsys.lib/<outputdir>.lib/libxercesc.srvpgm   libxerces-c1_7_0.o
                 qar -cuv libxerces-c1_7_0.a *.o

           If you are on a v4 system using the ILE C++ PRPQ compiler (which is referred to as the 'old' compiler) you will get
           compiler errors requiring a few manual changes to the source:

              * src/dom/DocumentImpl.cpp
              * src/dom/DocumentImpl.hpp
              * src/idom/IDDocumentImpl.cpp
              * src/idom/IDDocumentImpl.hpp
              * src/validators/common/ContentSpecNode.hpp

           Update the following routines in src/dom/DocumentImpl.cpp as follows:

              void DocumentImpl::setUserData(NodeImpl* n, void* data)
              {
                     if (!userData && data)
               #ifdef __OS400__
                             userData = new RefHashTableOf<char>(29, false, new HashPtr());
               #else
                             userData = new RefHashTableOf<void>(29, false, new HashPtr());
               #endif
                     if (!data && userData)
                             userData->removeKey((void*)n);
                     else
               #ifdef __OS400__
                             userData->put((void*)n,(char*)data);
               #else
                             userData->put((void*)n,data);
               #endif
              }

              void* DocumentImpl::getUserData(NodeImpl* n)
              {
                     if (userData)
               #ifdef __OS400__
                             return (void*)userData->get((void*)n);
               #else
                             return userData->get((void*)n);
               #endif
                     else
                             return null;
              }

           To update src/dom/DoumentImpl.hpp as follows:

              #ifdef __OS400__
                     RefHashTableOf<char>            *userData;
              #else

                     RefHashTableOf<void>            *userData;
              #endif

           Update the following routines in src/idom/IDDocumentImpl.cpp as follows:

              void IDDocumentImpl::setUserData(IDOM_Node* n, void* data)
              {
                     if (!fUserData && data)
              #ifdef __OS400__
                             fUserData = new (this) RefHashTableOf<char>(29, false, new (this) HashPtr());
              #else
                             fUserData = new (this) RefHashTableOf<void>(29, false, new (this) HashPtr());
              #endif

                     if (!data && fUserData)
                             fUserData->removeKey((void*)n);
                     else
              #ifdef __OS400__
                             fUserData->put((void*)n,(char*)data);
              #else
                             fUserData->put((void*)n,data);
              #endif
              }

              void* IDDocumentImpl::getUserData(const IDOM_Node* n) const
              {
                     if (fUserData)
              #ifdef __OS400__
                             return (void*) fUserData->get((void*)n);
              #else
                             return fUserData->get((void*)n);
              #endif

                     else
                             return 0;
              }

           To update src/idom/IDDocumentImpl.hpp:

              #ifdef __OS400__
                 RefHashTableOf<char>        *fUserData;
              #else
                 RefHashTableOf<void>        *fUserData;
              #endif

           Update validators/common/ContentSpecNode.hpp removing the following:

              #ifndef __OS400__
              inline
              #endif
              ContentSpecNode::~ContentSpecNode()

        To build for transcoder ICU:

           1.Make sure you have an ICUROOT path set up so that you can find the ICU header files (usually /usr/local)
           2.Make sure you have created a binding directory (symbolic link) in the file system so that you can bind the
             Xerces-C++ service program to the ICU service program and specify that on the EXTRA_LINK_OPTIONS in
             src/Makefile.incl (usually the default is a link in /usr/local/lib).

    Building Samples on iSeries
    ---------------------------

        Note that the samples will create programs bind to the BND directory object
        created by qar referenced above.

           qsh
              cd <full path to Xerces-C++>/samples
              runConfigure -p os400 -x icc -c icc
              gmake

Building Xerces-C++ on OS/2 using Visual Age C++
================================================

    OS/2 is a favourite IBM PC platforms. The only option in this platform is
    to use Visual Age C++ compiler. Here are the steps you need to build
    Xerces-C++ using Visual Age C++ on OS/2.

    Building Xerces-C++ library
    ---------------------------

        Requirements:

           * VisualAge C++ Version 4.0 with Fixpak 1:
             Download the Fixpak from the IBM VisualAge C++ Corrective Services web
             page.

        There are two ways to build Xerces-C++. The "From Existing" method only requires
        VAC++. The "From Scratch" method requires both Object Rexx and VAC++
        installed.

        The "From Existing" Method

           1.In the xerces-c-src1_7_0\Projects\OS2\VACPP40 directory, find
             and edit the VAC++ configuration file project_options.icc.
           2.Change the directory on the first line 'BASE_DIR = "..."' to match the
             base directory of the Xerces-C++ sources on your system. Note that the
             directory path must use double backslashes "\\"!
           3.Save project_options.icc
           4.Start the Command Line in the VAC++ folder.
           5.Navigate to the xerces-c-src1_7_0\Projects\OS2\VACPP40
             directory.
           6.Run build.cmd. This does a migration build.
           7.When build.cmd finishes, review the file compiler.errors. This file
             should contain only informational messages, almost all complaining about
             constant values in comparisons.
           8.You should now have a xerces-c.dll and xerces-c.lib. The library
             file is an import library for the DLL.

        The "From Scratch" Method

           1.If you are not currently running Object Rexx, run the SWITCHRX
             command from a command line, answer "yes" to switching to Object
             Rexx, and follow the instructions to reboot. You can switch back to
             "Classic Rexx" by running SWITCHRX again. But you probably won't
             need to switch back since Object Rexx runs almost 100% of Classic
             Rexx programs.
           2.In the xerces-c-src1_7_0\Projects\OS2\VACPP40 directory, run
             genICC.cmd. This builds the VAC++ configuration files for the sources you
             have on your system.
           3.Check the generated ICC files to ensure that they didn't pick up some
             non-OS/2 platform stuff. This happens when new platform-specific
             directories are added to Xerces. If they did pick up new non-OS/2 stuff,
             either edit it out of the ICC file or add them to the "ignore" array in
             genICC.cmd and re-run genICC.
           4.Start the Command Line in the VAC++ folder.
           5.Navigate to the xerces-c-src1_7_0\Projects\OS2\VACPP40
             directory.
           6.Run build.cmd This does a migration build.
           7.When build.cmd finishes, review the file compiler.errors. This file
             should contain only informational messages, almost all complaining about
             constant values in comparisons.
           8.You should now have a xerces-c.dll and xerces-c.lib. The library
             file is an import library for the DLL.)

        Packaging the Binaries

           There is an Object Rexx program that will package the binaries and headers.
           (See step 1 of the "From scratch" method on how to switch to Object Rexx.)
           The packageBinaries.cmd file is in the
           xerces-c-src1_7_0\Projects\OS2\VACPP40 directory. Run
           packageBinaries, giving the source and target directories like this:

              packageBinaries -s x:\xerces-c-src1_7_0 -o x:\temp\xerces-c1_7_0-os2

           (Match the source directory to your system; the target directory can be anything
           you want.)

           If you don't want to use the Object Rexx program, you'll need to manually
           copy the "*.hpp" and "*.c" files to an include directory. (Be sure to maintain
           the same directory structure that you find under xerces-c-src1_7_0.)

    Building Samples
    ----------------

        Building the Xerces-C++ samples using IBM Visual Age C++ Professional 4.0 for
        OS/2 (VAC++).

           * In the XercesCSrcInstallDir;\samples\Projects\OS2\VACPP40
             directory, find and edit the VAC++ configuration file basedir.icc.
           * All of the directories used to build the samples are defined in
             basedir.icc. You need to edit the directories to match your system.
             Here are the directories you need to assign: SRC_DIR --
             XercesCSrcInstallDir; This is where VAC++ should look to find the
             samples directories containing the source files. BASE_DIR -- The install
             directory XercesCSrcInstallDir;. VAC++ will store the compiled
             samples in the bin directory under BASE_DIR. It will also look for the
             xerces-c.lib file in the lib directory under BASE_DIR. Other
             directories are set based on these two. You can choose to override them if
             you wish.
           * Save basedir.icc
           * Start the Command Line in the VAC++ folder.
           * Navigate to the
             XercesCSrcInstallDir;\samples\Projects\OS2\VACPP40
             directory.
           * Run bldsamples.cmd
           * When build.cmd finishes, review the file compiler.errors. This file
             should contain only informational messages, almost all complaining about
             constant values in comparisons.
           * You should now have several executable files.

        Rebuilding the Configuration Files

           Although it shouldn't be necessary, if you want to rebuild the VAC++ configuration
           files, you'll need to have Object Rexx running on your system:

           * If you are not currently running Object Rexx, run the SWITCHRX command
             from a command line, answer "yes" to switching to Object Rexx, and follow
             the instructions to reboot. (Note: You can switch back to "Classic Rexx" by
             running SWITCHRX again. But you probably won't need to switch back
             since Object Rexx runs almost 100% of Classic Rexx programs.)
           * In the Projects\OS2\VACPP40 directory, run genICC.cmd. This builds the
             VAC++ configuration files for the samples you have on your system.
           * Go to the first step above in the "Building asmples for OS/2" section.

Building Xerces-C++ on Macintosh
================================

    The Xerces-C++ Mac port has the key following attributes:

        1.Built atop CoreServices APIs and a limited number of Carbon
          APIs; supports builds for both Mac OS Classic, Carbon, and Mac
          OS X systems.
        2.Has a Mac OS native transcoder that utilizes the built-in Mac OS
          Unicode converter [MacOSUnicodeConverter].
        3.Has a Mac OS native netaccessor that utilizes the built-in Mac OS
          URLAccess routines [MacOSURLAccess].
        4.Supports builds from Metroworks CodeWarrior, Apple Project
          Builder, and Mac OS X shell.


    Using Xerces-C++ with CodeWarrior
    ---------------------------------
        Xerces-C++ and CodeWarrior:

           Xerces-C++ may be built with CodeWarrior under Mac OS Classic or Mac OS X.
           Since the Xerces-C++ code contains some files with very long names, and
           CodeWarrior does not yet support use of files with such long names, the installation
           in this case is somewhat involved.

        Installing Xerces-C++ for use with CodeWarrior:

           For compatibility with CodeWarrior, it is necessary to adjust some of the file names
           (and referencing include statements). To do this, it is necessary to perform the
           following steps on a unix (or Mac OS X) machine that has support for long file names
           (a Windows machine may also work):

          *  Retrieve Xerces-C++ from CVS, or untar a packaged build. Note that these
             steps should not be performed in a Classic Mac OS environment, as file
             names would then be mangled at this point!
          *  Xerces-C++ comes with a tool that will shorten file names as appropriate, and
             fix up referencing include statements. Duplicate the file
             Projects/MacOS/ShortenFiles.pl to the xercesc main directory (the same
             directory that contains the Projects directory). Executing this perl script from
             this location will create a new directory MacSrc that contains patched up
             versions of files from the src directory.

              cd <xercescroot>
              cp Projects/MacOS/ShortenFiles.pl .
              perl ShortenFiles.pl

          *  The source files will likely not now have proper Mac OS type/creator
             attribution. CodeWarrior badly wants this to be correct. So set the
             type/creator of these files somehow. The following should work from Mac OS X
             (but if you're not going to keep building on a Mac OS X machine, you may well
             need to perform this step in some other way once you get the files onto your
             classic machine).

              find . \( -name "*.c" -or -name "*.h" -or -name "*.cpp" -or -name "*.hpp" -or \
              -name "*.xml" \) -print0 | xargs -0 /Developer/Tools/SetFile -c CWIE -t TEXT

           * Move the entire directory structure to your Mac OS machine.

        Building Xerces-C++ with CodeWarrior:

           * Run CodeWarrior (tested with latest CW Pro 7.0).
           * Import the project
             Projects/MacOS/CodeWarrior/XercesLib/XercesLib.mcp.xml, saving it back
             out to the same directory as XercesLib.mcp.
           * This project contains five build targets that build all combinations of classic,
             carbon, debug, and release versions, with an all target that builds all of these.
             Build any or all of these.

        Building Xerces-C++ Samples with CodeWarrior:

           A CodeWarrior project is included that builds the DOMPrint sample. This may be
           used as an example from which to build additional sample projects. Please read the
           following important notes:

              * Once again, it is required that you import the .xml version of the project file,
                and save it back out.
              * The Xerces-C++ sample programs are written to assume a command line
                interface. To avoid making Macintosh-specific changes to these command line
                programs, we have opted to instead require that you make a small extension
                to your CodeWarrior runtime that supports such command line programs.
                Please read and follow the usage notes in
                XercesSampleSupport/XercesSampleStartupFragment.c.

    Building Xerces-C++ with Project Builder
    ----------------------------------------

        Projects are included to build the Xerces-C++ library and DOMPrint sample under
        Apple's Project Builder for Mac OS X. The following notes apply:

           * Since you are running under Mac OS X, and if you are not also performing
             CodeWarrior builds, it is not necessary to shorten file names or set the
             type/creator codes as required for CodeWarrior.
           * The Project Builder project builds XercesLib as the framework
             Xerces.framework. This framework, however, does not currently include a
             correct set of public headers. Any referencing code must have an include
             path directive that points into the Xerces-C++ src directory.
           * The DOMPrint project illustrates one such usage of the Xerces.framework.

    Building Xerces-C++ from the Mac OS X command line
    --------------------------------------------------

        Support for Mac OS X command line builds is now included in the standard "unix"
        Xerces-C++ build infrastructure.

        In general, the Mac OS X command line build follows the generic unix build
        instructions. You need to set your XERCESCROOT environment variable,
        ./runConfigure, and make.

           setenv XERCESCROOT "<directory>"
           cd src
           ./runConfigure -p macosx -n native
           make

        Similar instructions apply to build the samples and tests, though the -n flag
        is not used in these cases:

           cd samples
           ./runConfigure -p macosx
           make

    Special usage information for Xerces-C++ on the Macintosh
    ---------------------------------------------------------

        File Path Specification

           Apart from the build instructions, above, the most important note about use of
           Xerces-C++ on the Macintosh is that Xerces-C++ expects all filename paths to be
           specified in unix syntax. If running natively under a Mac OS X system, this path
           will be the standard posix path as expected by the shell. The easiest means of
           creating and interpreting these paths will be through the routines
           XMLCreateFullPathFromFSRef and XMLParsePathToFSRef as declared in
           the file MacOSPlatformUtils.hpp. FSSpec variants of these routines are also
           supplied.

        Mac OS Version Compatibility

           Xerces-C++ requires that several key components of the Mac OS be relatively up
           to date. It should be readily compatible with any system above Mac OS 9.0.
           Compatibility with earlier systems may perhaps be achieved if you can install
           appropriate components.

        Required components are:

           * Unicode Converter and Text Encoding Converter. These provide the base
             transcoding service used to support Xerces-C++ transcoding requirements.

        Optional components are:

           * URLAccess. Provides NetAccessor support to Xerces-C++ for use in
             fetching network referenced entities. If URLAccess is not installed, any
             such references will fail; the absence of URLAccess, however, will not in
             itself prevent Xerces-C++ from running.
           * Multiprocessing library. Provides mutual exclusion support. Once again,
             the routines will back down gracefully if Multiprocessing support is not
             available.
           * HFS+ APIs. If HFS+ APIs are available, all file access is performed using
             the HFS+ fork APIs to support long file access, and to support long
             unicode compliant file names. In the absence of HFS+ APIs, classic HFS
             APIs are used instead.

Building Xerces-C++ with ICU using bundled Perl scripts on Windows
==================================================================

    As mentioned earlier, Xerces-C++ may be built in stand-alone mode using
    native encoding support and also using ICU where you get support over 180
    different encodings. ICU stands for International Components for Unicode
    and is an open source distribution from IBM. You can get ICU libraries from
    IBM's developerWorks site or go to the ICU download page directly.

        Important: Please remember that ICU and Xerces-C++ must be built with the same
        compiler, preferably with the same version. You cannot for example, build ICU with a
        threaded version of the xlC compiler and build Xerces-C++ with a non-threaded one.


    There are two options to build Xerces-C++ with ICU. One is to use the
    MSDEV GUI environment, and the other is to invoke the compiler from the
    command line.

    Using, the GUI environment, requires one to edit the project files. Here, we
    will describe only the second option. It involves using the perl script
    'packageBinaries.pl'.

    Prerequisites:

        * Perl 5.004 or higher
        * Cygwin tools or MKS Toolkit
        * zip.exe

    Extract Xerces-C++ source files from the .zip archive using WinZip, say in
    the root directory (an arbitrary drive x:). It should create a directory like
    'x:\xerces-c-src1_7_0'.

    Extract the ICU files, using WinZip, in root directory of the disk where you
    have installed Xerces-C++, sources. After extraction, there should be a new
    directory 'x:\icu' which contains all the ICU source files.

    Start a command prompt to get a new shell window. Make sure you have
    perl, cygwin tools (uname, rm, cp, ...), and zip.exe somewhere in the path.
    Next setup the environment for MSVC using 'VCVARS32.BAT' or a similar file.
    Then at the prompt enter:

        set XERCESCROOT=x:\xerces-c-src1_7_0
        set ICUROOT=x:\icu
        cd x:\xerces-c-src1_7_0\scripts
        perl packageBinaries.pl -s x:\xerces-c-src1_7_0 -o x:\temp\xerces-c1_7_0-win32 -t icu

    (Match the source directory to your system; the target directory can be
    anything you want.)

    If everything is setup right and works right, then you should see a binary drop
    created in the target directory specified above. This script will build both ICU
    and Xerces-C++, copy the files (relevant to the binary drop) to the target
    directory.

    For a description of options available, you can enter:

        perl packageBinaries.pl

Building Xerces-C++ COM Wrapper on Windows
==========================================

    To build the COM module for use with XML on Windows platforms, you
    must first set up your machine appropriately with necessary tools and
    software modules and then try to compile it. The end result is an
    additional library that you can use along with the standard Xerces-C++
    for writing VB templates or for use with IE 5.0 using JavaScript.

    Setting up your machine for COM

        To build the COM project you will need to install the MS PlatformSDK. Some of the
        header files we use don't come with Visual C++ 6.0. You may download it from
        Microsoft's Website at
        http://www.microsoft.com/msdownload/platformsdk/setuplauncher.htm or directly
        FTP it from
        ftp://ftp.microsoft.com/developr/PlatformSDK/April2000/Msi/WinNT/x86/InstMsi.exe.

        The installation is huge, but you don't need most of it. So you may do a custom
        install by just selecting "Build Environment" and choosing the required
        components. First select the top level Platform SDK. Then click the down arrow
        and make all of the components unavailable. Next open the "Build Environment"
        branch and select only the following items:

           * Win32 API
           * Component Services
           * Web Services - Internet Explorer

        Important: When the installation is complete you need to update VC6's include
        path to include ..\platformsdk\include\atl30. You do this by choosing
        "Tools -> Options -> Directories". This path should be placed second after the
        normal PlatformSDK include. You change the order of the paths by clicking the up
        and down arrows.

        The order in which the directories appear on your path is important. Your first
        include path should be ..\platformsdk\include. The second one
        should be ..\platformsdk\include\atl30.

    Building COM module for Xerces-C++

        Once you have set up your machine, build Xerces-C++ COM module by choosing
        the project named 'xml4com' inside the workspace. Then select your build mode
        to be xml4com - Win32 Release MinDependency. Finally build the project.
        This will produce a DLL named xerces-com.dll which needs to be present in
        your path (on local machine) before you can use it.

    Testing the COM module

        There are some sample test programs in the test/COMTest directory which
        show examples of navigating and searching an XML tree using DOM. You need to
        browse the HTML files in this directory using IE 5.0. Make sure that your build has
        worked properly, specially the registration of the ActiveX controls that happens in
        the final step.

        You may also want to check out the NIST DOM test suite at
        http://xw2k.sdct.itl.nist.gov/BRADY/DOM/. You will have to modify the documents
        in the NIST suite to load the Xerces COM object instead of the MSIE COM object.

Building User Documentation
============================

    The user documentation (this very page that you are reading on the
    browser right now), was generated using an XML application called
    StyleBook. This application makes use of Xerces-J and Xalan to
    create the HTML file from the XML source files. The XML source files
    for the documentation are part of the Xerces-C++ module. These files
    reside in the doc directory.

    Pre-requisites for building the user documentation are:

        * JDK 1.2.2 (or later).
        * Xerces-J 1.0.1.bundled
        * Xalan-J 0.19.2.bundled
        * Stylebook 1.0-b2.bundled
        * The Apache Style files (dtd's and .xsl files).bundled

    Invoke a command window and setup PATH to include the JDK 1.2.2
    bin directory

    Next, cd to the Xerces-C++ source drop root directory, and enter

        * Under Windows:
          createDocs
        * Under Unix's:
          sh createDocs.bat

    This should generate the .html files in the 'doc/html' directory.

I wish to port Xerces to my favourite platform. Do you have any suggestions?
============================================================================

    All platform dependent code in Xerces has been isolated to a couple
    of files, which should ease the porting effort. Here are the basic steps
    that should be followed to port Xerces.

        1.The directory src/util/Platforms contains the platform
          sensitive files while src/util/Compilers contains all
          development environment sensitive files. Each operating system
          has a file of its own and each development environment has
          another one of its own too.
          As an example, the Win32 platform as a Win32Defs.hpp file and
          the Visual C++ environment has a VCPPDefs.hpp file. These files
          set up certain define tokens, typedefs, constants, etc... that will
          drive the rest of the code to do the right thing for that platform and
          development environment. AIX/CSet have their own AIXDefs.hpp
          and CSetDefs.hpp files, and so on. You should create new
          versions of these files for your platform and environment and
          follow the comments in them to set up your own. Probably the
          comments in the Win32 and Visual C++ will be the best to follow,
          since that is where the main development is done.

        2.Next, edit the file XercesDefs.hpp, which is where all of the
          fundamental stuff comes into the system. You will see conditional
          sections in there where the above per-platform and
          per-environment headers are brought in. Add the new ones for
          your platform under the appropriate conditionals.

        3.Now edit AutoSense.hpp. Here we set canonical Xerces internal
          #define tokens which indicate the platform and compiler. These
          definitions are based on known platform and compiler defines.
          AutoSense.hpp is included in XercesDefs.hpp and the canonical
          platform and compiler settings thus defined will make the
          particular platform and compiler headers to be the included at
          compilation.
          It might be a little tricky to decipher this file so be careful. If you
          are using say another compiler on Win32, probably it will use
          similar tokens so that the platform will get picked up already
          using what is already there.

        4.Once this is done, you will then need to implement a version of
          the platform utilities for your platform. Each operating system
          has a file which implements some methods of the
          XMLPlatformUtils class, specific to that operating system. These
          are not terribly complex, so it should not be a lot of work. The
          Win32 verions is called Win32PlatformUtils.cpp, the AIX
          version is AIXPlatformUtils.cpp and so on. Create one for your
          platform, with the correct name, and empty out all of the
          implementation so that just the empty shells of the methods are
          there (with dummy returns where needed to make the compiler
          happy.) Once you've done that, you can start to get it to build
          without any real implementation.

        5.Once you have the system building, then start implementing your
          own platform utilties methods. Follow the comments in the Win32
          version as to what they do, the comments will be improved in
          subsequent versions, but they should be fairly obvious now. Once
          you have these implementations done, you should be able to
          start debugging the system using the demo programs.

    Other concerns are:

        * Does ICU compile on your platform? If not, then you'll need to
          create a transcoder implementation that uses your local
          transcoding services. The Iconv transcoder should work for you,
          though perhaps with some modifications.

        * What message loader will you use? To get started, you can use
          the "in memory" one, which is very simple and easy. Then, once
          you get going, you may want to adapt the message catalog
          message loader, or write one of your own that uses local
          services.

        That is the work required in a nutshell!

What should I define XMLCh to be?
=================================

    XMLCh should be defined to be a type suitable for holding a utf-16
    encoded (16 bit) value, usually an unsigned short.

    All XML data is handled within Xerces-C++ as strings of XMLCh
    characters. Regardless of the size of the type chosen, the data stored
    in variables of type XMLCh will always be utf-16 encoded values.

    Unlike XMLCh, the encoding of wchar_t is platform dependent.
    Sometimes it is utf-16 (AIX, Windows), sometimes ucs-4 (Solaris,
    Linux), sometimes it is not based on Unicode at all (HP/UX, AS/400,
    system 390).

    Some earlier releases of xerce-c defined XMLCh to be the same type
    as wchar_t on most platforms, with the goal of making it possible to
    pass XMLCh strings to library or system functions that were expecting
    wchar_t paramters. This approach has been abandonded because of

        * Portability problems with any code that assumes that the types of
          XMLCh and wchar_t are compatible
        * Excessive memory usage, especially in the DOM, on platforms
          with 32 bit wchar_t.
        * utf-16 encoded XMLCh is not always compatible with ucs-4
          encoded wchar_t on Solaris and Linux. The problem occurs with
          Unicode characters with values greater than 64k; in ucs-4 the
          value is stored as a single 32 bit quatity. With utf-16, the value
          will be stored as a "surrogate pair" of two 16 bit values. Even
          with XMLCh equated to wchar_t, xerces will still create the utf-16
          encoded surrogate pairs, which are illegal in ucs-4 encoded
          wchar_t strings.

Where can I look for more help?
===============================

    If you have read this page, followed the instructions, and still cannot
    resolve your problem(s), there is more help. You can find out if others
    have solved this same problem before you, by checking the Apache
    XML mailing list archives at http://archive.covalent.net and the Bugzilla
    Apache bug database.

s