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)
• iSeries Tools for Developers, PRPQ 5799-PTL (these are the gnu utilities)
• For v5: WebSphere Development ToolsSet, 5722-WDS ( installed option 52, Compiler - ILE C++)

Recommendation:

• 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 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. We recommend the use of Iconv400.

Setup Instructions:

• 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 *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 - '/qibm/proddata/developertools/qsh/bin/gmake' OUTPUTDIR - <identifies target iSeries library for *module, *pgm and *srvpgm objects> PATH - '/usr/bin:/qibm/proddata/developertools/qsh/bin' ICUROOT - (if using ICU) <the path of your ICU installation>

• 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/xercesc edit runConfigure and comment out the line: getoptErr=`getopt p:c:x:dm:n:t:r:b:l:z:P:C:h $*` runConfigure -p os400 -x icc -c icc -m inmem -t Iconv400 -r none

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

If runConfigure runs fine then do the following under Qsh to actually build the modules:

	qsh: cd <full path to Xerces-C++>/src/xercesc 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-c26.0.so *.o will results in command = CRTBNDDIR BNDDIR(yourlib/libxercesc) TEXT('/yourlib/Xerces-C++/lib/libxerces-c26.0.so') 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 program by doing the following:

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

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-c26.0.so qar -cuv libxerces-c26.0.so *.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/xercesc/dom/impl/DOMDocumentImpl.cpp
• src/xercesc/dom/impl/DOMDocumentImpl.hpp
• src/xercesc/dom/deprecated/DocumentImpl.cpp
• src/xercesc/dom/deprecated/DocumentImpl.hpp
• src/xercesc/validators/common/ContentSpecNode.hpp

Update the following routines in src/xercesc/dom/deprecated/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/xercesc/dom/deprecated/DoumentImpl.hpp as follows:

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

Update the following routines in src/xercesc/dom/impl/DOMDocumentImpl.cpp as follows:

	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; }

To update src/xercesc/dom/impl/DOMDocumentImpl.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/xercesc/Makefile.incl (usually the default is a link in /usr/local/lib).

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

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 earlier versions of Mac OS, as well as earlier versions of CodeWarrior, did not support file names longer than 32 characters, CodeWarrior 8.0 is required. If you are building Xerces-C++ on a Mac OS 9 system, be extremely careful in how to unpack and/or transfer the Xerces-C++ files to that system, to ensure that their file names are not truncated in the process.

Installing Xerces-C++ for use with CodeWarrior:

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.

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 gnutar utility on Mac OS X will do the right thing; older versions of StuffIt truncate names to 31 characters as they unpack tar archives, though versions >= 7.0.1 seem to work, at least on Mac OS X. The command line tool tar will truncate path names that get too long; gnutar should be used instead. Failure to heed these warnings will result in broken projects.

Building Xerces-C++ with CodeWarrior:

• Run CodeWarrior (requires CodeWarrior 8.0 with support for long file names).
• 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.

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

• Be sure to heed warnings under "special instructions" below regarding which tools must be used to unpack archives: gnutar is your friend.
• The Xcode 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.

Projects for Apple's Project Builder environment, which is no longer supported under Mac OS X 10.3, are provided but may be out of date. You may need to add or delete files from the project in order to support changes in Xerces-C++. Please feel free to submit patches against these projects If you care about the Project Builder projects, and want to keep them up to date.

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 (the full path up to the Xerces-C++ src directory, but not including 'src'), ./runConfigure, and make. Be sure to heed warnings under "special instructions" below regarding which tools must be used to unpack archives: gnutar is your friend.

	setenv XERCESCROOT "<xerces-c-directory>" cd src/xercesc ./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

Unpacking the tar archive

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 gnutar utility on Mac OS X will do the right thing; older versions of StuffIt truncate names to 31 characters as they unpack tar archives, though versions >= 7.0.1 seem to work, at least on Mac OS X. The command line tool tar will truncate path names that get too long; gnutar should be used instead. Failure to heed these warnings will result in broken projects.

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. If Xerces-C++ is configured to use MacOSURLAccessCF, then URLAccess (and thus Carbon) is not required, but CoreServices.framework is required for Mac OS X.
• 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.