doc/build-other.xml - xerces-c - Git at Google

 <?xml version="1.0" standalone="no"?>
 <!DOCTYPE s1 SYSTEM "sbk:/style/dtd/document.dtd">

 <s1 title="Building on Other Platforms">
     <anchor name="iSeries"/>
     <s2 title="Building &XercesCName; on iSeries (AS/400)">
             <p>The following addresses the requirements and build of
            &XercesCName; natively on the iSeries.
             </p>
             <s3 title="Building &XercesCName; library">
                 <p><em>Requirements:</em></p>

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

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

                 <p><em>Recommendations:</em></p>

                 <ul>
                 <li>There is one option when building the XML4C parser on iSeries.
                 For code page translation, you can use the iSeries
                 native <code>Iconv400</code> support or ICU as the transcoder plug in. If you choose ICU, follow the instructions
                 to build the ICU service program with the ICU download. Those instructions
                 are not included here.</li>

                 <li>We recommend the use of <code>Iconv400</code>.
                 The binary posted on Alphaworks uses Iconv400.</li>
                 </ul>

                 <p><em>Setup Instructions:</em></p>

                 <ul>
                 <li>Make sure that you have the requirements installed on your iSeries.
                 We highly recommend that you read the write up 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 <code>*module</code>,
                 <code>*pgm</code> and <code>*srvpgm</code> objects in libraries.</li>

                 <li>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. \\&lt;your iSeries name&gt;\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.</li>

                  <li>Create iSeries target library. This library will be the target
                      for the resulting modules and &XercesCName; service program. You will
                      specify this library on the OUTPUTDIR environment variable
                      in step 4.</li>

                  <li>Set up the following environment variables in your build process
                      (use <code>ADDENVVAR</code> or <code>WRKENVVAR CL</code> commands):</li>
                  </ul>
 <source>
 XERCESCROOT - &lt;the full path up to the &XercesCName; src directory, but not including 'src'&gt;
 MAKE   - '/usr/bin/gmake'
 OUTPUTDIR  - &lt;identifies target iSeries library for *module, *pgm and *srvpgm objects&gt;
 ICUROOT - (optional if using ICU)  &lt;the path of your ICU includes&gt;
 </source>

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

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

          <p><em>Configure</em></p>

          <p>To configure the make files for an iSeries build do the following under Qsh:</p>
 <source>qsh:
 cd &lt;full path to &XercesCName;&gt;/src/xercesc
 runConfigure -p os400 -x icc -c icc -m inmem -t Iconv400</source>

          <p>Troubleshooting:</p>
 <source>error: configure: error: installation or configuration problem:
 C compiler cannot create executables.</source>

          <p>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 <em>OR</em> the <code>runConfigure</code> cannot create the temporary
          modules (<code>CONFTest1</code>, etc) it uses to test out the compiler
          options or <code>PASE</code> is not installed. The second reason happens because the test modules already exist
          from a previous run of <code>runConfigure</code>. To correct the problem,
          do the following:</p>
 <source>CL:
 DLTMOD &lt;OUTPUTDIR library&gt;/CONFT* and
 DLTPGM &lt;OUTPUTDIR library&gt;/CONFT*</source>

         <p><em>Build</em></p>

 <source>qsh:
 cd &lt;full path to &XercesCName;&gt;/src/xercesc
 gmake</source>

          <p>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 &lt;path to &XercesCName;/lib&gt;. 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.</p>

          <p>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 <code>BNDSRVPGM</code> option on the <code>CRTPGM</code> or
          <code>CRTSRVPGM</code> command  or you can specify a binding directory
          on your <code>icc</code>  command. To specify an archive file to bind to,
          use the  <code>-L, -l</code> binding options on icc.  An archive file
          on iSeries is a binding directory.  To create an archive file, use
          <code>qar</code> command.  (see the iSeries Tools for Developers write up).
          </p>

          <p>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)):</p>
 <source>qsh:
 cd &lt;full path to &XercesCName;&gt;/lib
 qar -cuv &XercesCUnixLib;&XercesCUnixSoName;.so *.o
 will results in
 command = CRTBNDDIR BNDDIR(yourlib/libxercesc) TEXT('/yourlib/&XercesCName;/lib/&XercesCUnixLib;&XercesCUnixSoName;.so')
 command = ADDBNDDIRE BNDDIR(yourlib/libxercesc) OBJ((yourlib/LIBXERCESC *SRVPGM) )</source>


          <p><em>Troubleshooting gmake problem:</em></p>
          <p>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:</p>
 <source>
 FAILURE: spawnp()  with errno = 3491
 GMAKE: vfork: Argument list too long.
 </source>

          <p>If this is the case, you can manually create the service program by doing the following:</p>

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

          <p>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:</p>

 <source>
 qsh:
 cd &lt;full path to &XercesCName;&gt;/lib
 ln -s /qsys.lib/&lt;outputdir&gt;.lib/libxercesc.srvpgm   &XercesCUnixLib;&XercesCUnixSoName;.so
 qar -cuv &XercesCUnixLib;&XercesCUnixSoName;.so *.o
 </source>

          <p>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:</p>

          <ul>
          <li>src/xercesc/dom/impl/DOMDocumentImpl.cpp</li>
          <li>src/xercesc/dom/impl/DOMDocumentImpl.hpp</li>
          <li>src/xercesc/dom/deprecated/DocumentImpl.cpp</li>
          <li>src/xercesc/dom/deprecated/DocumentImpl.hpp</li>
          <li>src/xercesc/validators/common/ContentSpecNode.hpp</li>
          </ul>

          <p>Update  the following routines in src/xercesc/dom/deprecated/DocumentImpl.cpp as follows:</p>
 <source>
  void DocumentImpl::setUserData(NodeImpl* n, void* data)
  {
 	if (!userData &amp;&amp; data)
   #ifdef __OS400__
 		userData = new RefHashTableOf&lt;char&gt;(29, false, new HashPtr());
   #else
 		userData = new RefHashTableOf&lt;void&gt;(29, false, new HashPtr());
   #endif
 	if (!data &amp;&amp; userData)
 		userData-&gt;removeKey((void*)n);
 	else
   #ifdef __OS400__
 		userData-&gt;put((void*)n,(char*)data);
   #else
 		userData-&gt;put((void*)n,data);
   #endif
  }

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

          <p>To update src/xercesc/dom/deprecated/DoumentImpl.hpp as follows:</p>

 <source>
  #ifdef __OS400__
 	RefHashTableOf&lt;char&gt;		*userData;
  #else

 	RefHashTableOf&lt;void&gt;		*userData;
  #endif
 </source>

           <p>Update  the following routines in src/xercesc/dom/impl/DOMDocumentImpl.cpp as follows:</p>
 <source>
  void DOMDocumentImpl::setUserData(DOMNode* n, void* data)
  {
 	if (!fUserData &amp;&amp; data)
  #ifdef __OS400__
 		fUserData = new (this) RefHashTableOf&lt;char&gt;(29, false, new (this) HashPtr());
  #else
 		fUserData = new (this) RefHashTableOf&lt;void&gt;(29, false, new (this) HashPtr());
  #endif

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

  void* DOMDocumentImpl::getUserData(const DOMNode* n) const
  {
 	if (fUserData)
  #ifdef __OS400__
 		return (void*) fUserData-&gt;get((void*)n);
  #else
 		return fUserData-&gt;get((void*)n);
  #endif

 	else
 		return 0;
  }
 </source>

           <p>To update src/xercesc/dom/impl/DOMDocumentImpl.hpp:</p>
 <source>
  #ifdef __OS400__
     RefHashTableOf&lt;char&gt;        *fUserData;
  #else
     RefHashTableOf&lt;void&gt;        *fUserData;
  #endif
 </source>
           <p>Update validators/common/ContentSpecNode.hpp removing the following:</p>
 <source>
  #ifndef __OS400__
  inline
  #endif
  ContentSpecNode::~ContentSpecNode()
 </source>

          <p>To build for transcoder ICU:</p>
          <ol>
           <li>Make sure you have an <code>ICUROOT</code> path set up so that you can
           find the ICU header files (usually <code>/usr/local</code>)</li>
           <li>Make sure you have created a binding directory (symbolic link)
           in the file system so that you can bind the &XercesCName; service program
           to the ICU service program and specify that on the <code>EXTRA_LINK_OPTIONS</code>
           in <code>src/xercesc/Makefile.incl</code> (usually the default is a link
           in <code>/usr/local/lib</code>).</li>
          </ol>

         </s3>

         <s3 title="Building Samples on iSeries">

           <p>Note that the samples will create programs bind to the BND directory object
              created by qar referenced above.</p>
 <source>qsh
 cd &lt;full path to &XercesCName;&gt;/samples
 runConfigure -p os400 -x icc -c icc
 gmake </source>

         </s3>
     </s2>

     <anchor name="Mac"/>
     <s2 title="Building &XercesCName; on Macintosh">
 		<p>The &XercesCName; Mac port has the key following attributes:
 		</p>

 		<ol>
 			<li>Built atop CoreServices APIs and a limited number of Carbon APIs;
 			supports builds for both Mac OS Classic, Carbon, and Mac OS X systems.
 			</li>

 			<li>Has a Mac OS native transcoder that utilizes the built-in Mac OS Unicode
 			converter [MacOSUnicodeConverter].
 			</li>

 			<li>Has two Mac OS native netaccessor classes. The first is based on Carbon and
 			and classic supported URLAccess and may be used in the broadest variety of
 			configurations [MacOSURLAccess]. The second [MacOSURLAccessCF] is based on
 			CFURLAccess, which requires either Carbon or Mac OS X CoreServices.framework.
 			This second NetAccessor is useful in Mac OS X configurations where reliance on
 			the full Carbon.framework would prohibit execution of the Xerces code in a
 			remote context that has no access to the GUI.
 			</li>

 			<li>Supports builds from Metroworks CodeWarrior, Apple Project Builder,
 			and Mac OS X shell.
 			</li>
 		</ol>

 		<s3 title="Using &XercesCName; with CodeWarrior">

 			<p><em>&XercesCName; and CodeWarrior:</em>
 			</p>

 			<p>&XercesCName; may be built with CodeWarrior under Mac OS Classic or Mac OS X. Since
 			the &XercesCName; 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.
 			</p>

 			<p><em>Installing &XercesCName; for use with CodeWarrior:</em>
 			</p>

 			<p>Note: versions of CodeWarrior prior to 8.0 did not support HFS+ long file names,
 			and thus required special steps to alter the file names prior to use. This restriction
 			has been removed for CodeWarrior 8.0, and the projects now directly reference the unaltered
 			source tree. The project files in this release require CodeWarrior v8.0 or higher.
 			</p>

 			<p>It is extemely important to ensure that you retrieve and unpack the sources
 			with a tool that does not truncate file names. The command line tar utility on Mac OS X
 			will do the right thing; current versions of StuffIt seem to truncate names as they
 			unpack tar archives. Failure to do this properly will result in broken projects.
 			</p>

 			<p><em>Building &XercesCName; with CodeWarrior:</em>
 			</p>

 			<ul>
 				<li>Run CodeWarrior (requires CodeWarrior 8.0 with support for long file names).
 				</li>

 				<li>Import the project Projects/MacOS/CodeWarrior/XercesLib/XercesLib.mcp.xml,
 				saving it back out to the same directory as XercesLib.mcp.
 				</li>

 				<li>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.
 				</li>
 			</ul>

 			<p><em>Building &XercesCName; Samples with CodeWarrior:</em>
 			</p>

 			<p>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:
 			</p>

 			<ul>
 				<li>Once again, it is required that you import the .xml version of the project
 				file, and save it back out.
 				</li>

 				<li>The &XercesCName; 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.
 				</li>
 			</ul>

 		</s3>

 		<s3 title="Building &XercesCName; with Project Builder">

 			<p>Projects are included to build the &XercesCName; library and DOMPrint sample under
 			Apple's Project Builder for Mac OS X. The following notes apply:
 			</p>

 			<ul>
 				<li>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.
 				</li>

 				<li>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 &XercesCName; src directory.
 				</li>

 				<li>The DOMPrint project illustrates one such usage of the Xerces.framework.
 				</li>
 			</ul>
 		</s3>

 		<s3 title="Building &XercesCName; from the Mac OS X command line">

 			<p>Support for Mac OS X command line builds is now included in the standard
 			"unix" &XercesCName; build infrastructure.
 			</p>

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

 <source>setenv XERCESCROOT "&lt;xerces-c-directory&gt;"
 cd src/xercesc
 ./runConfigure -p macosx -n native
 make</source>

 			<ul>
 				<li>Similar instructions apply to build the samples and tests, though the
 				<code>-n</code> flag is not used in these cases:
 				</li>
 			</ul>

 <source>cd samples
 ./runConfigure -p macosx
 make</source>

 		</s3>

 		<s3 title="Special usage information for &XercesCName; on the Macintosh">

 			<p><em>File Path Specification</em></p>

 			<p>Apart from the build instructions, above, the most important note
 			about use of &XercesCName; on the Macintosh is that &XercesCName; 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 <code>XMLCreateFullPathFromFSRef</code>
 			and <code>XMLParsePathToFSRef</code> as declared in the file
 			<code>MacOSPlatformUtils.hpp</code>. FSSpec variants of these routines are
 			also supplied.
 			</p>

 			<p><em>Mac OS Version Compatibility</em></p>

 			<p>&XercesCName; 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.
 			</p>

 			<p>Required components are:
 			</p>

 			<ul>
 				<li>Unicode Converter and Text Encoding Converter. These provide the base
 				transcoding service used to support &XercesCName; transcoding requirements.
 				</li>

 			</ul>

 			<p>Optional components are:
 			</p>

 			<ul>
 				<li>URLAccess. Provides NetAccessor support to &XercesCName; 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 &XercesCName; from running. If &XercesCName; is
 				configured to use MacOSURLAccessCF, then URLAccess (and thus Carbon)
 				is not required, but CoreServices.framework is required for Mac OS X.
 				</li>

 				<li>Multiprocessing library. Provides mutual exclusion support. Once again,
 				the routines will back down gracefully if Multiprocessing support is not
 				available.
 				</li>

 				<li>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.
 				</li>
 			</ul>
 		</s3>
     </s2>
 </s1>
	<?xml version="1.0" standalone="no"?>
	<!DOCTYPE s1 SYSTEM "sbk:/style/dtd/document.dtd">

	<s1 title="Building on Other Platforms">
	<anchor name="iSeries"/>
	<s2 title="Building &XercesCName; on iSeries (AS/400)">
	<p>The following addresses the requirements and build of
	&XercesCName; natively on the iSeries.
	</p>
	<s3 title="Building &XercesCName; library">
	<p><em>Requirements:</em></p>

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

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

	<p><em>Recommendations:</em></p>

	<ul>
	<li>There is one option when building the XML4C parser on iSeries.
	For code page translation, you can use the iSeries
	native <code>Iconv400</code> support or ICU as the transcoder plug in. If you choose ICU, follow the instructions
	to build the ICU service program with the ICU download. Those instructions
	are not included here.</li>

	<li>We recommend the use of <code>Iconv400</code>.
	The binary posted on Alphaworks uses Iconv400.</li>
	</ul>

	<p><em>Setup Instructions:</em></p>

	<ul>
	<li>Make sure that you have the requirements installed on your iSeries.
	We highly recommend that you read the write up 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 <code>*module</code>,
	<code>pgm</code> and <code>srvpgm</code> objects in libraries.</li>

	<li>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.</li>

	<li>Create iSeries target library. This library will be the target
	for the resulting modules and &XercesCName; service program. You will
	specify this library on the OUTPUTDIR environment variable
	in step 4.</li>

	<li>Set up the following environment variables in your build process
	(use <code>ADDENVVAR</code> or <code>WRKENVVAR CL</code> commands):</li>
	</ul>
	<source>
	XERCESCROOT - <the full path up to the &XercesCName; 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>
	</source>

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

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

	<p><em>Configure</em></p>

	<p>To configure the make files for an iSeries build do the following under Qsh:</p>
	<source>qsh:
	cd <full path to &XercesCName;>/src/xercesc
	runConfigure -p os400 -x icc -c icc -m inmem -t Iconv400</source>

	<p>Troubleshooting:</p>
	<source>error: configure: error: installation or configuration problem:
	C compiler cannot create executables.</source>

	<p>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 <em>OR</em> the <code>runConfigure</code> cannot create the temporary
	modules (<code>CONFTest1</code>, etc) it uses to test out the compiler
	options or <code>PASE</code> is not installed. The second reason happens because the test modules already exist
	from a previous run of <code>runConfigure</code>. To correct the problem,
	do the following:</p>
	<source>CL:
	DLTMOD <OUTPUTDIR library>/CONFT* and
	DLTPGM <OUTPUTDIR library>/CONFT*</source>

	<p><em>Build</em></p>

	<source>qsh:
	cd <full path to &XercesCName;>/src/xercesc
	gmake</source>

	<p>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 &XercesCName;/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.</p>

	<p>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 <code>BNDSRVPGM</code> option on the <code>CRTPGM</code> or
	<code>CRTSRVPGM</code> command or you can specify a binding directory
	on your <code>icc</code> command. To specify an archive file to bind to,
	use the <code>-L, -l</code> binding options on icc. An archive file
	on iSeries is a binding directory. To create an archive file, use
	<code>qar</code> command. (see the iSeries Tools for Developers write up).
	</p>

	<p>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)):</p>
	<source>qsh:
	cd <full path to &XercesCName;>/lib
	qar -cuv &XercesCUnixLib;&XercesCUnixSoName;.so *.o
	will results in
	command = CRTBNDDIR BNDDIR(yourlib/libxercesc) TEXT('/yourlib/&XercesCName;/lib/&XercesCUnixLib;&XercesCUnixSoName;.so')
	command = ADDBNDDIRE BNDDIR(yourlib/libxercesc) OBJ((yourlib/LIBXERCESC *SRVPGM) )</source>


	<p><em>Troubleshooting gmake problem:</em></p>
	<p>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:</p>
	<source>
	FAILURE: spawnp() with errno = 3491
	GMAKE: vfork: Argument list too long.
	</source>

	<p>If this is the case, you can manually create the service program by doing the following:</p>

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

	<p>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:</p>

	<source>
	qsh:
	cd <full path to &XercesCName;>/lib
	ln -s /qsys.lib/<outputdir>.lib/libxercesc.srvpgm &XercesCUnixLib;&XercesCUnixSoName;.so
	qar -cuv &XercesCUnixLib;&XercesCUnixSoName;.so *.o
	</source>

	<p>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:</p>

	<ul>
	<li>src/xercesc/dom/impl/DOMDocumentImpl.cpp</li>
	<li>src/xercesc/dom/impl/DOMDocumentImpl.hpp</li>
	<li>src/xercesc/dom/deprecated/DocumentImpl.cpp</li>
	<li>src/xercesc/dom/deprecated/DocumentImpl.hpp</li>
	<li>src/xercesc/validators/common/ContentSpecNode.hpp</li>
	</ul>

	<p>Update the following routines in src/xercesc/dom/deprecated/DocumentImpl.cpp as follows:</p>
	<source>
	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;
	}
	</source>

	<p>To update src/xercesc/dom/deprecated/DoumentImpl.hpp as follows:</p>

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

	RefHashTableOf<void> *userData;
	#endif
	</source>

	<p>Update the following routines in src/xercesc/dom/impl/DOMDocumentImpl.cpp as follows:</p>
	<source>
	void DOMDocumentImpl::setUserData(DOMNode* 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* DOMDocumentImpl::getUserData(const DOMNode* n) const
	{
	if (fUserData)
	#ifdef __OS400__
	return (void) fUserData->get((void)n);
	#else
	return fUserData->get((void*)n);
	#endif

	else
	return 0;
	}
	</source>

	<p>To update src/xercesc/dom/impl/DOMDocumentImpl.hpp:</p>
	<source>
	#ifdef __OS400__
	RefHashTableOf<char> *fUserData;
	#else
	RefHashTableOf<void> *fUserData;
	#endif
	</source>
	<p>Update validators/common/ContentSpecNode.hpp removing the following:</p>
	<source>
	#ifndef __OS400__
	inline
	#endif
	ContentSpecNode::~ContentSpecNode()
	</source>

	<p>To build for transcoder ICU:</p>
	<ol>
	<li>Make sure you have an <code>ICUROOT</code> path set up so that you can
	find the ICU header files (usually <code>/usr/local</code>)</li>
	<li>Make sure you have created a binding directory (symbolic link)
	in the file system so that you can bind the &XercesCName; service program
	to the ICU service program and specify that on the <code>EXTRA_LINK_OPTIONS</code>
	in <code>src/xercesc/Makefile.incl</code> (usually the default is a link
	in <code>/usr/local/lib</code>).</li>
	</ol>

	</s3>

	<s3 title="Building Samples on iSeries">

	<p>Note that the samples will create programs bind to the BND directory object
	created by qar referenced above.</p>
	<source>qsh
	cd <full path to &XercesCName;>/samples
	runConfigure -p os400 -x icc -c icc
	gmake </source>

	</s3>
	</s2>

	<anchor name="Mac"/>
	<s2 title="Building &XercesCName; on Macintosh">
	<p>The &XercesCName; Mac port has the key following attributes:
	</p>

	<ol>
	<li>Built atop CoreServices APIs and a limited number of Carbon APIs;
	supports builds for both Mac OS Classic, Carbon, and Mac OS X systems.
	</li>

	<li>Has a Mac OS native transcoder that utilizes the built-in Mac OS Unicode
	converter [MacOSUnicodeConverter].
	</li>

	<li>Has two Mac OS native netaccessor classes. The first is based on Carbon and
	and classic supported URLAccess and may be used in the broadest variety of
	configurations [MacOSURLAccess]. The second [MacOSURLAccessCF] is based on
	CFURLAccess, which requires either Carbon or Mac OS X CoreServices.framework.
	This second NetAccessor is useful in Mac OS X configurations where reliance on
	the full Carbon.framework would prohibit execution of the Xerces code in a
	remote context that has no access to the GUI.
	</li>

	<li>Supports builds from Metroworks CodeWarrior, Apple Project Builder,
	and Mac OS X shell.
	</li>
	</ol>

	<s3 title="Using &XercesCName; with CodeWarrior">

	<p><em>&XercesCName; and CodeWarrior:</em>
	</p>

	<p>&XercesCName; may be built with CodeWarrior under Mac OS Classic or Mac OS X. Since
	the &XercesCName; 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.
	</p>

	<p><em>Installing &XercesCName; for use with CodeWarrior:</em>
	</p>

	<p>Note: versions of CodeWarrior prior to 8.0 did not support HFS+ long file names,
	and thus required special steps to alter the file names prior to use. This restriction
	has been removed for CodeWarrior 8.0, and the projects now directly reference the unaltered
	source tree. The project files in this release require CodeWarrior v8.0 or higher.
	</p>

	<p>It is extemely important to ensure that you retrieve and unpack the sources
	with a tool that does not truncate file names. The command line tar utility on Mac OS X
	will do the right thing; current versions of StuffIt seem to truncate names as they
	unpack tar archives. Failure to do this properly will result in broken projects.
	</p>

	<p><em>Building &XercesCName; with CodeWarrior:</em>
	</p>

	<ul>
	<li>Run CodeWarrior (requires CodeWarrior 8.0 with support for long file names).
	</li>

	<li>Import the project Projects/MacOS/CodeWarrior/XercesLib/XercesLib.mcp.xml,
	saving it back out to the same directory as XercesLib.mcp.
	</li>

	<li>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.
	</li>
	</ul>

	<p><em>Building &XercesCName; Samples with CodeWarrior:</em>
	</p>

	<p>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:
	</p>

	<ul>
	<li>Once again, it is required that you import the .xml version of the project
	file, and save it back out.
	</li>

	<li>The &XercesCName; 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.
	</li>
	</ul>

	</s3>

	<s3 title="Building &XercesCName; with Project Builder">

	<p>Projects are included to build the &XercesCName; library and DOMPrint sample under
	Apple's Project Builder for Mac OS X. The following notes apply:
	</p>

	<ul>
	<li>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.
	</li>

	<li>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 &XercesCName; src directory.
	</li>

	<li>The DOMPrint project illustrates one such usage of the Xerces.framework.
	</li>
	</ul>
	</s3>

	<s3 title="Building &XercesCName; from the Mac OS X command line">

	<p>Support for Mac OS X command line builds is now included in the standard
	"unix" &XercesCName; build infrastructure.
	</p>

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

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

	<ul>
	<li>Similar instructions apply to build the samples and tests, though the
	<code>-n</code> flag is not used in these cases:
	</li>
	</ul>

	<source>cd samples
	./runConfigure -p macosx
	make</source>

	</s3>

	<s3 title="Special usage information for &XercesCName; on the Macintosh">

	<p><em>File Path Specification</em></p>

	<p>Apart from the build instructions, above, the most important note
	about use of &XercesCName; on the Macintosh is that &XercesCName; 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 <code>XMLCreateFullPathFromFSRef</code>
	and <code>XMLParsePathToFSRef</code> as declared in the file
	<code>MacOSPlatformUtils.hpp</code>. FSSpec variants of these routines are
	also supplied.
	</p>

	<p><em>Mac OS Version Compatibility</em></p>

	<p>&XercesCName; 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.
	</p>

	<p>Required components are:
	</p>

	<ul>
	<li>Unicode Converter and Text Encoding Converter. These provide the base
	transcoding service used to support &XercesCName; transcoding requirements.
	</li>

	</ul>

	<p>Optional components are:
	</p>

	<ul>
	<li>URLAccess. Provides NetAccessor support to &XercesCName; 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 &XercesCName; from running. If &XercesCName; is
	configured to use MacOSURLAccessCF, then URLAccess (and thus Carbon)
	is not required, but CoreServices.framework is required for Mac OS X.
	</li>

	<li>Multiprocessing library. Provides mutual exclusion support. Once again,
	the routines will back down gracefully if Multiprocessing support is not
	available.
	</li>

	<li>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.
	</li>
	</ul>
	</s3>
	</s2>
	</s1>