doc/samples.xml - xerces-c - Git at Google

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

 <s1 title="&XercesCName; Samples">

     <s2 title="Building the Samples">
     <p>&XercesCName; comes packaged with ten sample applications that
     demonstrate salient features of the parser using simple
     applications written on top of the SAX and DOM APIs provided by
     the parser.</p>

     <p>Once you have set up your PATH variable, you can run the
     samples by opening a command window (or your shell prompt for
     UNIX environments). Sample XML data files are provided in the
     samples/data directory.</p>

     <p>The installation process for the samples is same on all UNIX
     platforms.
     Note that <em>runConfigure</em> is just a helper script and you are free to
     use <em>./configure</em> with the correct parameters to make it work
     on any platform-compiler combination of your choice. The script needs the following parameters:
     </p>
 <source>Usage: runConfigure "options"
        where options may be any of the following:
        -p &lt;platform&gt; (accepts 'aix', 'linux', 'solaris', 'hp-10', 'hp-11')
        -c &lt;C compiler name&gt; (e.g. gcc, xlc_r, cc or aCC)
        -x &lt;C++ compiler name&gt; (e.g. g++, xlC_r, CC or aCC)
        -d (specifies that you want to build debug version)
        -h (get help on the above commands)</source>

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

     </s2>

     <s2 title="Building the Samples for OS2">

     <p>Building the &XercesCName; samples using IBM Visual Age C++ Professional 4.0
     for OS/2 (VAC++).</p>

      <ul>
      <li> In the <code>XercesCSrcInstallDir;\samples\Projects\OS2\VACPP40</code> directory,
      find and edit the VAC++ configuration file <code>basedir.icc</code>.</li>

      <li>All of the directories used to build the samples are defined in
      <code>basedir.icc</code>. You need to edit the directories to match your system.
      Here are the directories you need to assign:

             SRC_DIR -- <code>XercesCSrcInstallDir;</code>
                        This is where VAC++ should look to find the samples
                        directories containing the source files.
             BASE_DIR -- The install directory <code>XercesCSrcInstallDir;</code>.
             		VAC++ will store the compiled samples in the <code>bin</code>
             		directory under BASE_DIR. It will also look for the
             		<code>xerces-c.lib</code> file in the <code>lib</code> directory under BASE_DIR.

         Other directories are set based on these two. You can choose to override them
         if you wish.</li>

      <li>Save <code>basedir.icc</code></li>

      <li>Start the Command Line in the VAC++ folder.</li>

      <li>Navigate to the <code>XercesCSrcInstallDir;\samples\Projects\OS2\VACPP40</code> directory.</li>

      <li>Run <code>bldsamples.cmd</code></li>

      <li>When <code>build.cmd</code> finishes, review the file <code>compiler.errors</code>.
      This file should contain only informational messages, almost all complaining about constant
         values in comparisons.</li>

      <li>You should now have several executable files.</li>

     </ul>

     <p>Rebuilding the Configuration Files</p>

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

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

      <li>In the Projects\OS2\VACPP40 directory, run genICC.cmd. This builds the VAC++
         configuration files for the samples you have on your system.</li>


       <li>Go to the first step above in the "Building asmples for OS/2" section.</li>
 	</ul>
    </s2>

     <s2 title="Running the Samples">

     <p>The sample applications are dependent on the &XercesCName; shared library
 		(and could also depend on the ICU library if you built &XercesCName; with ICU).
 		Therefore, on Windows platforms you must make sure that your <code>PATH</code>
 		environment variable is set properly to pick up these shared libraries at
 		runtime.</p>

 		<p>On UNIX platforms you must ensure that <ref>LIBPATH</ref>
 		environment variable is set properly to pick up the shared libraries at
 		runtime. (UNIX gurus will understand here that <ref>LIBPATH</ref> actually
 		translates to <em>LD_LIBRARY_PATH</em> on Solaris and Linux, <em>SHLIB_PATH</em> on HP-UX
 		and stays as <em>LIBPATH</em> on AIX).</p>

 		<p>To set you LIBPATH (on AIX for example), you would type:</p>
 <source>export LIBPATH=&XercesCInstallDir;/lib:$LIBPATH</source>

 		<s3 title="&XercesCName; Samples">
 			<ul>
 				<li><link idref="saxcount">SAXCount</link>
 					<br/>SAXCount counts the elements, attributes, spaces and
 					characters in an XML file.</li>
 				<li><link idref="saxprint">SAXPrint</link>
 					<br/>SAXPrint parses an XML file and prints it out.</li>
 				<li><link idref="domcount">DOMCount</link>
 					<br/>DOMCount counts the elements in a XML file.</li>
 				<li><link idref="domprint">DOMPrint</link>
 					<br/>DOMPrint parses an XML file and prints it out.</li>
 				<li><link idref="memparse">MemParse</link>
 					<br/>MemParse parses XML in a memory buffer, outputing the number of elements and attributes.</li>
 				<li><link idref="redirect">Redirect</link>
 					<br/>Redirect redirects the input stream for external entities.</li>
 				<li><link idref="pparse">PParse</link>
 					<br/>PParse demonstrates progressive parsing.</li>
 				<li><link idref="stdinparse">StdInParse</link>
 					<br/>StdInParse demonstrates streaming XML data from standard input.</li>
 				<li><link idref="enumval">EnumVal</link>
 					<br/>EnumVal shows how to enumerate the markup decls in a DTD Validator.</li>
 				<li><link idref="createdoc">CreateDOMDocument</link>
 					<br/>CreateDOMDocument creates a DOM tree in memory from scratch.</li>
 				<li><link idref="sax2count">SAX2Count</link>
 					<br/>SAX2Count counts the elements, attributes, spaces and
 					characters in an XML file.</li>
 				<li><link idref="sax2print">SAX2Print</link>
 					<br/>SAX2Print parses an XML file and prints it out.</li>
 				<li><link idref="idomcount">IDOMCount</link>
 					<br/>IDOMCount counts the elements in a XML file.</li>
 				<li><link idref="idomprint">IDOMPrint</link>
 					<br/>IDOMPrint parses an XML file and prints it out.</li>
 			</ul>
 		</s3>
     </s2>
 </s1>
	<?xml version="1.0" standalone="no"?>
	<!DOCTYPE s1 SYSTEM "./dtd/document.dtd">

	<s1 title="&XercesCName; Samples">

	<s2 title="Building the Samples">
	<p>&XercesCName; comes packaged with ten sample applications that
	demonstrate salient features of the parser using simple
	applications written on top of the SAX and DOM APIs provided by
	the parser.</p>

	<p>Once you have set up your PATH variable, you can run the
	samples by opening a command window (or your shell prompt for
	UNIX environments). Sample XML data files are provided in the
	samples/data directory.</p>

	<p>The installation process for the samples is same on all UNIX
	platforms.
	Note that <em>runConfigure</em> is just a helper script and you are free to
	use <em>./configure</em> with the correct parameters to make it work
	on any platform-compiler combination of your choice. The script needs the following parameters:
	</p>
	<source>Usage: runConfigure "options"
	where options may be any of the following:
	-p <platform> (accepts 'aix', 'linux', 'solaris', 'hp-10', 'hp-11')
	-c <C compiler name> (e.g. gcc, xlc_r, cc or aCC)
	-x <C++ compiler name> (e.g. g++, xlC_r, CC or aCC)
	-d (specifies that you want to build debug version)
	-h (get help on the above commands)</source>

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

	</s2>

	<s2 title="Building the Samples for OS2">

	<p>Building the &XercesCName; samples using IBM Visual Age C++ Professional 4.0
	for OS/2 (VAC++).</p>

	<ul>
	<li> In the <code>XercesCSrcInstallDir;\samples\Projects\OS2\VACPP40</code> directory,
	find and edit the VAC++ configuration file <code>basedir.icc</code>.</li>

	<li>All of the directories used to build the samples are defined in
	<code>basedir.icc</code>. You need to edit the directories to match your system.
	Here are the directories you need to assign:

	SRC_DIR -- <code>XercesCSrcInstallDir;</code>
	This is where VAC++ should look to find the samples
	directories containing the source files.
	BASE_DIR -- The install directory <code>XercesCSrcInstallDir;</code>.
	VAC++ will store the compiled samples in the <code>bin</code>
	directory under BASE_DIR. It will also look for the
	<code>xerces-c.lib</code> file in the <code>lib</code> directory under BASE_DIR.

	Other directories are set based on these two. You can choose to override them
	if you wish.</li>

	<li>Save <code>basedir.icc</code></li>

	<li>Start the Command Line in the VAC++ folder.</li>

	<li>Navigate to the <code>XercesCSrcInstallDir;\samples\Projects\OS2\VACPP40</code> directory.</li>

	<li>Run <code>bldsamples.cmd</code></li>

	<li>When <code>build.cmd</code> finishes, review the file <code>compiler.errors</code>.
	This file should contain only informational messages, almost all complaining about constant
	values in comparisons.</li>

	<li>You should now have several executable files.</li>

	</ul>

	<p>Rebuilding the Configuration Files</p>

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

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

	<li>In the Projects\OS2\VACPP40 directory, run genICC.cmd. This builds the VAC++
	configuration files for the samples you have on your system.</li>


	<li>Go to the first step above in the "Building asmples for OS/2" section.</li>
	</ul>
	</s2>

	<s2 title="Running the Samples">

	<p>The sample applications are dependent on the &XercesCName; shared library
	(and could also depend on the ICU library if you built &XercesCName; with ICU).
	Therefore, on Windows platforms you must make sure that your <code>PATH</code>
	environment variable is set properly to pick up these shared libraries at
	runtime.</p>

	<p>On UNIX platforms you must ensure that <ref>LIBPATH</ref>
	environment variable is set properly to pick up the shared libraries at
	runtime. (UNIX gurus will understand here that <ref>LIBPATH</ref> actually
	translates to <em>LD_LIBRARY_PATH</em> on Solaris and Linux, <em>SHLIB_PATH</em> on HP-UX
	and stays as <em>LIBPATH</em> on AIX).</p>

	<p>To set you LIBPATH (on AIX for example), you would type:</p>
	<source>export LIBPATH=&XercesCInstallDir;/lib:$LIBPATH</source>

	<s3 title="&XercesCName; Samples">
	<ul>
	<li><link idref="saxcount">SAXCount</link>
	<br/>SAXCount counts the elements, attributes, spaces and
	characters in an XML file.</li>
	<li><link idref="saxprint">SAXPrint</link>
	<br/>SAXPrint parses an XML file and prints it out.</li>
	<li><link idref="domcount">DOMCount</link>
	<br/>DOMCount counts the elements in a XML file.</li>
	<li><link idref="domprint">DOMPrint</link>
	<br/>DOMPrint parses an XML file and prints it out.</li>
	<li><link idref="memparse">MemParse</link>
	<br/>MemParse parses XML in a memory buffer, outputing the number of elements and attributes.</li>
	<li><link idref="redirect">Redirect</link>
	<br/>Redirect redirects the input stream for external entities.</li>
	<li><link idref="pparse">PParse</link>
	<br/>PParse demonstrates progressive parsing.</li>
	<li><link idref="stdinparse">StdInParse</link>
	<br/>StdInParse demonstrates streaming XML data from standard input.</li>
	<li><link idref="enumval">EnumVal</link>
	<br/>EnumVal shows how to enumerate the markup decls in a DTD Validator.</li>
	<li><link idref="createdoc">CreateDOMDocument</link>
	<br/>CreateDOMDocument creates a DOM tree in memory from scratch.</li>
	<li><link idref="sax2count">SAX2Count</link>
	<br/>SAX2Count counts the elements, attributes, spaces and
	characters in an XML file.</li>
	<li><link idref="sax2print">SAX2Print</link>
	<br/>SAX2Print parses an XML file and prints it out.</li>
	<li><link idref="idomcount">IDOMCount</link>
	<br/>IDOMCount counts the elements in a XML file.</li>
	<li><link idref="idomprint">IDOMPrint</link>
	<br/>IDOMPrint parses an XML file and prints it out.</li>
	</ul>
	</s3>
	</s2>
	</s1>