http://xml.apache.org/http://www.apache.org/http://www.w3.org/

Home

Readme
Download
Installation
Build Instructions

API Docs
Samples
Schema

FAQs
Programming
Migration

Releases
Bug-Reporting
Feedback

Y2K Compliance
PDF Document

CVS Repository
Mail Archive

Building Xerces-C++ 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 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. 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 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   - '/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/xercesc
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/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-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 program 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/xercesc/dom/DocumentImpl.cpp
  • src/xercesc/dom/DocumentImpl.hpp
  • src/xercesc/idom/IDDocumentImpl.cpp
  • src/xercesc/idom/IDDocumentImpl.hpp
  • src/xercesc/validators/common/ContentSpecNode.hpp

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

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

	RefHashTableOf<void>		*userData;
 #endif

Update the following routines in src/xercesc/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/xercesc/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/xercesc/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.)

NoteIf 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 samples 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 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.
  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" -or -name "*.r" \) -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 "<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

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



Copyright © 2001 The Apache Software Foundation. All Rights Reserved.