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 XML4C. 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 xml4c-src-3_5_1\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 XML4C 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 xml4c-src-3_5_1\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 xml4c-src-3_5_1\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 xml4c-src-3_5_1\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 xml4c-src-3_5_1\Projects\OS2\VACPP40 directory. Run packageBinaries, giving the source and target directories like this:

	packageBinaries -s x:\xml4c-src-3_5_1 -o x:\temp\xml4c-3_5_1-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 xml4c-src-3_5_1.)

Requirements:

• QSHELL interpreter installed (install base option 30, operating system)
• QShell Utilities, PRPQ 5799-XEH
• ILE C++ for AS/400, PRPQ 5799-GDW
• GNU facilities (the gnu facilities are currently available by request only. Send e-mail to rchgo400@us.ibm.com)

Recommendations:

• There are a couple of options when building the XML4C parser on AS/400. For messaging support, you can use the in memory message option or the message file support. For code page translation, you can use the AS/400 native Iconv400 support or ICU. If you choose ICU, follow the instructions to build the ICU service program with the ICU download. Those instructions are not included here.
• Currently we recommend that you take the options of MsgFile and Iconv400 (see below)

Setup Instructions:

• Make sure that you have the requirements installed on your AS/400. We highly recommend that you read the writeup that accompanies the gnu facilities download. 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 AS/400 *module, *pgm and *srvpgm objects in libraries.
• Download the tar file (unix version) to the AS/400 (using a mapped drive), and decompress and untar the source. We have had difficulty with the tar command on AS/400. This is under investigation. If you have trouble, we recommend the following work around:

	qsh: gunzip -d <tar file.gz> pax -r -f <uncompressed tar file>

• Create AS400 target library. This library will be the target for the resulting modules and XML4C 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 to your XML4C sources> PLATFORM - 'OS400' MAKE - '/usr/bin/gmake' OUTPUTDIR - <identifies target as400 library for *module, *pgm and *srvpgm objects> ICUROOT - (optional if using ICU) <the path of your ICU includes>

• Add QCXXN, to your build process library list. This results in the resolution of CRTCPPMOD used by the icc compiler.
• The runConfigure instruction below uses 'egrep'. This is not on the AS/400 but you can create it by doing the following: edtf '/usr/bin/egrep' with the following source:

	#!/usr/bin/sh /usr/bin/grep -e "$@"

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 AS/400 build do the following:

	qsh cd <full path to XML4C>/src runConfigure -p os400 -x icc -c icc -m MsgFile -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 two 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. The second reason happens because the test modules already exist from a previous run of runConfigure. To correct the problem, do the following:

	DLTMOD <your OUTPUTDIR library>/CONFT* and DLTPGM your <OUTPUTDIR library>/CONFT*

Build

	qsh gmake -e

The above gmake will result in a service program being created in your specified library and a symbolic link to that service program placed in <path to XML4C/lib>. 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 AS/400 is a binding directory. To create an archive file, use qar command. (see the gnu facilities write up).

After building the XML4C service program, create a binding directory by doing the following (note, this binding directory is used when building the samples):

	qsh cd <full path to XML4C>/lib> qar -cuv libxercesc1_1.a *.o command = CRTBNDDIR BNDDIR(yourlib/libxercesc) TEXT('/yourlib/XML4C/lib/libxercesc1_1.a') command = ADDBNDDIRE BNDDIR(yourlib/libxercesc) OBJ((yourlib/LIBXERCESC *SRVPGM) )

Troubleshooting:

If you are on a V4R3 system, you will get a bind problem 'descriptor QlgCvtTextDescToDesc not found' using Iconv400. On V4R3 the system doesn't automatically pick up the QSYS/QLGUSR service program for you when resolving this function. This is not the case on V4R4. To fix this, you can either manually create the service program after creating all the resulting modules in your <OUTPUTDIR> library or you can create a symbolic link to a binding directory that points to the QLGUSR service program and then specify an additional -L, -l on the EXTRA_LINK_OPTIONS in Makefile.incl. See the ln and qar function in the gnu utilities.

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

Creating AS400 XML parser message file:

As specified earlier, the -m MsgFile support on the runConfigure enable the parser messages to be pulled from an AS/400 message file. To view the source for creating the message file and the XML parser messages, see the following stream file:

	EDTF <full path to XML4C>/src/util/MsgLoaders/MsgFile/CrtXMLMsgs

In the prolog of CrtXMLMsgs there are instructions to create the message file:

1. Use the CPYFRMSTMF to copy the CL source to an AS/400 source physical file. Note that the target source file needs to have record length of about 200 bytes to avoid any truncation.
2. Create the CL program to create the message file and add the various message descriptions
3. Call the CL program, providing the name of the message file (use QXMLMSG as default) and a library (this can be any library, including any product library in which you wish to embed the xml parser)

Note that the XML4C source code for resolving parser messages is using by default message file QXMLMSG, *LIBL. If you want to change either the message file name or explicitly qualify the library to match your product needs, you must edit the following .cpp files prior to your build.

	<full path to XML4C>/src/util/MsgLoaders/MsgFile/MsgLoader.cpp <full path to XML4C>/src/util/Platforms/OS400/OS400PlatformUtils.cpp

Troubleshooting:

If you are using the parser and are failing to get any message text for error codes, it may be because of the *LIBL resolution of the message file.

	qsh cd <full path to XML4C>/samples runConfigure -p os400 -x icc -c icc gmake -e

Troubleshooting:

If you take a 'sed' error, while trying to make the samples. This is an AS400 anomaly having to do with certain new line character and the sed function. A temporary work around is to use EDTF on the configure stream file (../samples/configure) and delete the following line near the bottom: s%@DEFS@%$DEFS%g.

XML4C and CodeWarrior:

XML4C may be built with CodeWarrior under Mac OS Classic or Mac OS X. Since the XML4C 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 XML4C 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 XML4C 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!
• XML4C 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 XML4C with CodeWarrior:

• Run CodeWarrior (tested with latest CW Pro 6.2).
• 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.
• Note that the Carbon targets contain an access path for a Carbon Support folder in the compiler folder. Up-to-date Apple headers and libraries are required. Either create a Carbon Support folder with recent headers and libraries or, if your MacOS Support folder is up to date, point the access path to this, or make an alias to it called "Carbon Support".

Building XML4C 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 XML4C 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 XML4C 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 XML4C src directory.
• The DOMPrint project illustrates one such usage of the Xerces.framework.

Support for Mac OS X command line builds is now included in the standard "unix" XML4C 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

File Path Specification

Apart from the build instructions, above, the most important note about use of XML4C on the Macintosh is that XML4C 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

XML4C 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 XML4C transcoding requirements.

Optional components are:

• URLAccess. Provides NetAccessor support to XML4C 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 XML4C 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.