<?xml version="1.0" standalone="no"?> 
<!DOCTYPE s1 SYSTEM "../../style/dtd/document.dtd">
<!--
 * Copyright 1999-2004 The Apache Software Foundation.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
-->
<s1 title="&xslt4c; Basic usage patterns">
<ul>
  <li><link anchor="intro">Introduction</link></li>
  <li><link anchor="xalantransformer">Basic usage pattern with the XalanTransformer C++ API</link></li>
  <li><link anchor="stylepi">Using a stylesheet processing instruction</link></li>
  <li><link anchor="params">Setting stylesheet parameters</link></li>
  <li><link anchor="incremental">Processing output incrementally</link></li>
  <li><link anchor="compiled">Performing a series of transformations</link></li>
  <li><link anchor="dom">Working with DOM input and output</link></li>
  <li><link anchor="xercesdomwrapperparsedsource">Using a Xerces DOM as the source for a Xalan transformation</link></li>
  <li><link anchor="xpath">Working with XPath expressions</link></li>
  <li><link anchor="tracelistener">Using the TraceListener</link></li>
  <li><link anchor="icu">Using the International Components for Unicode (ICU)</link></li>
  <li><link anchor="capi">Basic usage pattern with the XalanTransformer C API</link></li>
  <li><link anchor="cvar">Variations with the XalanTransformer C API</link></li>
  <li>See also: <link idref="extensions">Creating and using extension functions</link></li>
</ul>
  
<anchor name="intro"/>
<s2 title="Introduction">  
<p>To perform a transformation, use one of the <jump href="apiDocs/classXalanTransformer.html">XalanTransformer
   </jump> transform() methods. The transformation requires an XML source document and an XSL stylesheet. Both of these objects 
   may be represented by instances of <jump href="apiDocs/classXSLTInputSource.html">XSLTInputSource </jump>. You can construct 
   an XSLTInputSource with a string (the system ID for a file or URI), an input stream, or a DOM.</p>
<p>If you are using an XSL stylesheet to perform a series of transformations, you can improve performance by calling transform() 
   with a compiled stylesheet, an instance of <jump href="apiDocs/classXalanCompiledStylesheet.html">XalanCompiledStylesheet</jump>. 
   If you are transforming an XML source more than once, you should call transform() with a parsed XML source, an instance of 
   <jump href="apiDocs/classXalanParsedSource.html">XalanParsedSource</jump>. See <link anchor="compiled">Performing a series of 
   transformations</link>.</p>
<p>If you XML source document contains a stylesheet Processing Instruction (PI), you do not need to include a stylesheet object 
  when you call transform().</p>
<p>The transformation output is represented by an <jump href="apiDocs/classXSLTResultTarget.html">XSLTResultTarget</jump>, which 
   you can set up to refer to an output stream, the system ID for a file or URI, or a Formatter for one of the various styles of 
   DOM output.</p>
<p>For detailed API documentation, see <jump href="apiDocs/index.html">&xslt4c; API</jump>. For an overview of the command-line 
   utility, see <link idref="commandline">Command-Line Utility</link>.</p>

</s2>
<anchor name="xalantransformer"/>
<s2 title="Basic usage patten with the XalanTransformer C++ API">
<p>Using <jump href="apiDocs/classXalanTransformer.html">XalanTransformer</jump> and the C++ API, you can perform one or more 
   transformations as described in the following steps.</p>
<note>For a working sample that illustrates these steps, see the <link idref="samples" anchor="xalantransform">XalanTransform</link> 
      sample.</note>
      
<s3 title="1. Include the required header files.">
<p>Always start with xalanc/Include/PlatformDefinitions.hpp, the &xslt4c; base header file. Also include xercesc/util/PlatformUtils.hpp, 
   xalanc/XalanTransformer/XalanTransformer.hpp, and any other header files your particular application requires.</p>
<source>
#include &lt;xalanc/Include/PlatformDefinitions.hpp&gt;
#include &lt;xercesc/util/PlatformUtils.hpp&gt;
#include &lt;xalanc/XalanTransformer/XalanTransformer.hpp&gt;
...
</source>
</s3>

<s3 title="2. Define namespaces">
<p>As of version 1.5, &xslt4c; now uses C++ namespaces for those platforms which support them.  A number of macros are provided to 
   make using the &xslt4c; (and &xml4c;) namespaces easier.</p>
<p>In the following example, the <em>XALAN_USING_XERCES</em> and <em>XALAN_USING_XALAN</em> macros are used to declare that the 
   program is using <em>XMLPlatformUtils</em> and <em>XalanTransformer</em> from the &xml4c; and &xslt4c; namespaces respectively.</p>
<source>
XALAN_USING_XERCES(XMLPlatformUtils)
XALAN_USING_XALAN(XalanTransformer)
</source>

<p>These macros can be used immediately after the included header files (for global applicability in a given source file) or within 
   functions and methods for local applicability.</p>
<note>Whilst you can use the standard C++ namespace syntax directly, the &xml4c; and &xslt4c; namespaces are linked to the version 
      number.  For example, the Xalan namespace is currently <em>xalanc_1_9</em>.  The macros will automatically take care of this 
      when code is re-compiled against a new version of the libraries.  Using the namespaces directly will require each namespace 
      related statement be updated by hand.</note>
</s3>

<s3 title="3. Initialize Xerces and Xalan.">
<p>Use the static initializers to initialize the &xslt4c; and &xml4c; platforms. You must initialize &xml4c; once per process. You 
   may initialize and terminate &xslt4c; multiple times, but this is not recommended: it is inefficient and is not thread safe.</p>  
<source>
XMLPlatformUtils::Initialize();
XalanTransformer::initialize();
</source>
</s3>

<s3 title="4. Create a XalanTransformer.">
<source>
XalanTransformer theXalanTransformer;
</source>
</s3>

<s3 title="5. Perform each transformation.">
<p>You can explicitly instantiate <jump href="apiDocs/classXSLTInputSource.html">XSLTInputSource</jump> objects for the XML 
   source document and XSL stylesheet, and an <jump href="apiDocs/classXSLTResultTarget.html">XSLTResultTarget</jump> object 
   for the output, and then call <jump href="apiDocs/classXalanTransformer.html">XalanTransformer</jump> transform() with those 
   objects as parameters. For example:</p>
<source>
XSLTInputSource xmlIn("foo.xml");
XSLTInputSource xslIn("foo.xsl");
XSLTResultTarget xmlOut("foo-out.xml");
int theResult =
    theXalanTransformer.transform(xmlIn,xslIn,xmlOut)
</source>

<p>Alternatively, you can call transform() with the strings (system identifiers), streams, and/or DOMs that the compiler needs 
   to implicitly construct the <jump href="apiDocs/classXSLTInputSource.html">XSLTInputSource</jump> and 
   <jump href="apiDocs/classXSLTResultTarget.html">XSLTResultTarget</jump> objects. For example:</p>
<source>
const char* xmlIn = "foo.xml";
const char* xslIn = "foo.xsl";
const char* xmlOut = "foo-out.xml";
int theResult =
    theXalanTransformer.transform(xmlIn,xslIn,xmlOut)
</source>
<p>Keep in mind that <jump href="apiDocs/classXSLTInputSource.html">XSLTInputSource</jump> and 
   <jump href="apiDocs/classXSLTResultTarget.html">XSLTResultTarget</jump> provide a variety of single-argument constructors that 
   you can use in this manner:</p>
<ul>
  <li><code>XSLTInputSource(const char* systemID);</code></li>
  <li><code>XSLTInputSource(const XMLCh* systemID);//Unicode chars</code></li>
  <li><code>XSLTInputSource(istream* stream);</code></li>
  <li><code>XSLTInputSource(XalanNode* node);</code><br/><br/></li>
  <li><code>XSLTResultTarget(char* fileName);</code></li>
  <li><code>XSLTResultTarget(XalanDOMString&amp; fileName);</code></li>
  <li><code>XSLTResultTarget(ostream* stream);</code></li>
  <li><code>XSLTResultTarget(ostream&amp; stream);</code></li>  
  <li><code>XSLTResultTarget(Writer* characterStream);</code></li>
  <li><code>XSLTResultTarget(XalanDocument* document);</code></li>
  <li><code>XSLTResultTarget(XalanDocumentFragment* documentFragment);</code></li>
  <li><code>XSLTResultTarget(XalanElement* element);</code></li>
  <li><code>XSLTResultTarget(FormatterListener&amp; flistener);</code></li>
</ul>
<note>Each transform() method returns an integer code, 0 for success. If an error occurs, you can use the getLastError() method 
      to return a pointer to the error message.</note>
</s3>

<s3 title="6. Shut down Xalan.">
<p>When you shut down Xalan, you may also want to shut down Xerces and ICU support (if enabled). Keep the following considerations 
   in mind:</p>
<ul>
  <li>Once you have shut down Xerces, you can no longer make Xalan or Xerces calls in the current process.<br/><br/></li>
  <li>Shut down ICU support if you have enabled it (see <link anchor="icusupport">enabling ICU support</link>) and if the 
      application is exiting or no longer requires the ICU. The <code>XMLPlatformUtils::Terminate()</code> call does nothing 
      if ICU support has not been enabled.</li>
  <li>Ensure that there are no &xslt4c; or &xml4c; objects extant at the point of termination.  Any deletion of objects after 
      termination could cause errors.</li>
</ul>
<p>Use the static terminators.</p>
<source>
XalanTransformer::terminate();
XMLPlatformUtils::Terminate();
XalanTransformer::ICUCleanUp();
</source>
</s3>

</s2>
<anchor name="stylepi"/>
<s2 title="Using a stylesheet processing instruction">
<p>If you want to use the stylesheet referred to by a stylesheet processing instruction in the XML document, simply call 
   transform() without the second XSLTInputSource argument. For example:</p>
<source>
// foo.xml contains a stylesheet PI
const char* xmlIn = "foo.xml";
const char* xmlOut = "foo-out.xml";
int theResult =
    theXalanTransformer.transform(xmlIn,xmlOut)
</source>
</s2>

<anchor name="params"/>
<s2 title="Setting stylesheet parameters">
<p>An XSL stylesheet can include parameters that are set at run time before a transformation takes place. When we generate 
   the HTML documents that make up the Xalan doc set, for example, we send the stylesheet an id parameter along with each 
   XML source document. The id identifies that document and enables the stylesheet to integrate it into the overall doc set.</p>
<p>To set a stylesheet parameter, use the <jump href="apiDocs/classXalanTransformer.html">XalanTransformer</jump> 
   setStylesheetParam() method. The setStylesheetParam() method takes two arguments: the parameter name and the expression. 
   For example:</p>
<source>
const XalanDOMString key("param1");
const XalanDOMString expression("'Hello World'");
theXalanTransformer.setStylesheetParam(key, expression);
// foo.xsl defines a stylesheet parameter named param1.
theXalanTransformer.transform("foo.xml","foo.xsl","foo-out.xml")
</source>
<note>If the expression is a string, enclose it in single quotes to make it a string expression.</note>
<p>You can include the -param flag with two arguments when you call the <link idref="commandline">command line utility</link>. 
   The first argument is the parameter name or key, and the second argument is the string expression (in single quotes). For example:</p>
<p><code>Xalan -p param1 'boo' foo.xml foo.xsl</code></p>
<p>If the string expression includes spaces or other characters that the shell intercepts, first enclose the string in single quotes 
   so &xslt4c; interprets it as a string expression, and then enclose the resulting string in double quotes so the shell interprets it as 
   a single argument. For example:</p>
<p><code>Xalan -p "'hello there'" foo.xml foo.xsl</code></p>
<p>The <link idref="samples" anchor="usestylesheetparam">UseStylesheetParam</link> sample application also uses a command-line parameter.
</p>
</s2>

<anchor name="incremental"/>
<s2 title="Processing output incrementally">
<p><jump href="apiDocs/classXalanTransformer.html">XalanTransformer</jump> provides a transform() method that sends the output in blocks 
to a callback function, which enables you to begin processing the output while the transformation is still in process:</p>
<source>
int
transform(const XSLTInputSource&amp; xmlIn,
          const XSLTInputSource&amp; xslIn,
          void* theOutputHandle,
          XalanOutputHandlerType theOutputHandler,
          XalanFlushHanderType theFlushHandler = 0);
</source>
<p>For an example, see <link idref="samples" anchor="xalantransformercallback">XalanTransformerCallback</link>.</p>
</s2>

<anchor name="compiled"/>
<s2 title="Performing a series of transformations">
<p>Before Xalan performs a standard transformation, it must parse the XML document and compile the XSL stylesheet into binary 
   representations. If you plan to use the same XML document or stylesheet in a series of transformations, you can improve performance 
   by parsing the XML document or compiling the stylesheet once and using the binary representation when you call transform().</p>
<p><jump href="apiDocs/classXalanTransformer.html">XalanTransformer</jump> includes methods for creating compiled stylesheets and 
   parsed XML documents: the compileStylesheet() method returns a pointer to a <jump href="apiDocs/classXalanCompiledStylesheet.html">
   XalanCompiledStylesheet</jump>; the parseSource() method returns a pointer to a <jump href="apiDocs/classXalanParsedSource.html">
   XalanParsedSource</jump>.</p>
<note>In the case of failure, both methods return 0.</note>
<p>Example using a XalanCompiledStylesheet to perform multiple transformations:</p>
<source>
XalanCompiledStylesheet* compiledStylesheet = 0;
compiledStylesheet = theXalanTransformer.compileStylesheet("foo.xsl");
assert(compiledStylesheet!=0);
theXalanTransformer.transform("foo1.xml", *compiledStylesheet, "foo1.out.");
theXalanTransformer.transform("foo2.xml", *compiledStylesheet, "foo2.out");
...
</source>
<p>For a working sample, see the <link idref="samples" anchor="compilestylesheet">CompileStylesheet</link> sample.</p>
<p>Example using a XalanParsedSource for multiple transformations:</p>
<source>
XalanParsedSource* parsedXML = 0;
parsedXML = theXalanTransformer.parseSource("foo.xml");
assert(parsedXML!=0);
theXalanTransformer.transform(*parsedXML, "foo1.xsl", "foo-xsl1.out");
theXalanTransformer.transform(*parsedXML, "foo2.xsl", "foo-xsl2.out");
...
</source>
<p>For a sample that uses both a parsed XML source and a compiled stylesheet, see <link idref="samples" anchor="threadsafe">ThreadSafe
</link>.</p>
</s2>

<anchor name="dom"/>
<s2 title="Working with DOM input and output">
<p>You can set up an <jump href="apiDocs/classXSLTResultTarget.html">XSLTResultTarget</jump> to produce a DOM when you perform a 
   transformation. You can also use a DOM as input for a transformation.</p>
<p>The following code fragment illustrates the procedures for working with DOM output :</p>
<source>

// Use the Xerces DOM parser to create a DOMDocument.

#include &lt;xercesc/dom/DOMDocument.hpp&gt;
#include &lt;xercesc/dom/DOMImplementation.hpp&gt;

#include &lt;xalanc/XMLSupport/FormatterToXML.hpp&gt;
#include &lt;xalanc/XMLSupport/XalanTransformer.hpp&gt;

XALAN_USING_XERCES(DOMDocument)
XALAN_USING_XERCES(DOMImplementation)

XALAN_USING_XALAN(FormatterToXML)
XALAN_USING_XALAN(XalanTransformer)


    // If you want to produce DOM output, create an empty Xerces Document
    // to contain the transformation output.
    
    DOMDocument * theDOM = 
        DOMImplementation::getImplementation()->createDocument();    

    // Now create a FormatterListener which can be used by the transformer
    // to send each output node to the new Xerces document

    FormatterToXercesDOM theFormatter(theDOM);

    // Now do the transform as normal
    XalanTransformer theXalanTransformer
    int theResult = theXalanTransformer.transform(
        "foo.xml", 
        "foo.xsl", 
        theFormatter);
...

    // After you perform the transformation, the DOMDocument contains
    // the output.
</source>
<note>You can also follow the same process but use a <em>FormatterToDeprecatedXercesDOM</em> if you require a DOM_Document
      output.  However this is discouraged, as support for the deprecated DOM may be removed in future releases of &xslt4c;</note>
<p>If you want to use a Xerces DOM object as input for a transformation without wrapping the DOM in a XercesParserLiaison, see 
   <link anchor="xercesdomwrapperparsedsource">passing in a Xerces DOM</link>.</p>

<s3 title="Limitations">
<p>Performance is much better when &xslt4c; uses native source tree handling rather than interacting with the Xerces DOMParser.</p>
<p>If you are using the deprecated DOM, the Xerces DOMParser by default, creates a DOM_XMLDecNode in the DOM tree to represent 
   the XML declaration. The Xalan bridge for the Xerces DOM does not support this non-standard node type. Accordingly, you must 
   call DOMParser::setToCreateXMLDeclTypeNode(false) <em>before</em> you parse the XML file. If not, the behavior is undefined, 
   and your application may crash.</p>
</s3>

<anchor name="xercesdomwrapperparsedsource"/>
<s3 title="Passing in a Xerces DOM to a transformation">
<p>You may want to use a Xerces DOM that was created without using the XalanTransformer class. As the following code snippet 
   illustrates, you can use <jump href="apiDocs/classXercesDOMWrapperParsedSource.html">XercesDOMWrapperParsedSource</jump> to 
   pass in a Xerces DOM as the source for an XSL transformation.</p>
<source>
#include &lt;xercesc/parsers/DOMParser.hpp&gt;
#include &lt;xalanc/XalanTransformer/XercesDOMWrapperParsedSource.hpp&gt;

void parseWithXerces(XalanTransformer &amp;xalan, 
                     const XSLTInputSource &amp;xmlInput,
                     const XalanCompiledStylesheet* styleSheet,
                     const XSLTResultTarget &amp;output,
                     XMLFileReporter &amp;logFile)
{
    XercesDOMParser theParser;
  
    // Turn on validation and namespace support.
    theParser.setDoValidation(true);
    theParser.setDoNamespaces(true);

    // Parse the document
  
    theParser.parse(xmlInput);
    DOMDocument *theDOM = theParser.getDocument();
    theDOM->normalize();

    XercesDOMSupport theDOMSupport;
    XercesParserLiaison theParserLiaison;
  
    // Use the DOM to create a XercesDOMWrapperParsedSource, 
    // which you can pass to the transform method.
    try
    {
        const XercesDOMWrapperParsedSource parsedSource(
                                   theDOM,
                                   theParserLiaison,
                                   theDOMSupport,
                                   XalanDOMString(xmlInput.getSystemId()));

        xalan.transform(parsedSource, stylesheet, output);

    }
    catch (....)
    {
      ...
    }
}  
</source>
</s3>
</s2>

<anchor name="xpath"/>
<s2 title="Working with XPath expressions">
<p>XSL stylesheets use XPath expressions to select nodes, specify conditions, and generate text for the result tree. XPath 
   provides an API that you can call directly. For example, you may want to select nodes programmatically and do your own 
   processing without a stylesheet. &xslt4c; provides an XPathEvaluator interface to simplify the process of executing XPath 
   expressions.</p>
<p>For an example that executes XPath expressions against XML source files, see <link idref="samples" anchor="simplexpathapi">
   SimpleXPathAPI</link> (takes advantage of the XPathEvaluator interface) and <link idref="samples" anchor="xpathwrapper">
   XPathWrapper</link>.</p>
</s2>

<anchor name="tracelistener"/>
<s2 title="Using TraceListener">
<p>TraceListener is a debugging abstract base class implemented by TraceListenerDefault. You can use TraceListener to trace 
   any combination of the following:</p>
<ul>
  <li>Calls to templates</li>
  <li>Calls to template children</li>
  <li>Selection events</li>    
  <li>Result tree generation events</li>
</ul>
<p>To construct a TraceListener with TraceListenerDefault, you need a PrintWriter and a boolean for each of these four 
   tracing options. You can then use the XSLTEngimeImpl setTraceSelects and addTraceListener methods to add the TraceListener 
   to an XSLTProcessor. See the <link idref="samples" anchor="tracelisten">TraceListen</link> sample application.</p>
<p>The TraceListen uses TraceListenerDefault to write events to the screen.</p>
</s2>

<anchor name="icu"/>
<s2 title="Using the ICU">
<p>You can use the <resource-ref idref="icu"/> to extend support for encoding, number formatting, and sorting.</p>
<ul>
  <li><em>Encoding</em>
      <br/> &xml4c; and &xslt4c; use UTF-16 encoding to work with Unicode data.  If you integrate the ICU with &xml4c;, both 
      &xml4c; and &xslt4c; use ICU support for input and output transcoding.<br/><br/></li>
  <li><em>format-number()</em>
      <br/>This XSLT function includes two or three arguments (the third is optional): number, format pattern, and decimal-format 
      name. &xslt4c; ignores the format pattern and optional decimal-format name. If you install ICU support for format-number(), 
      this function is fully supported with all its arguments.<br/><br/></li>
  <li><em>xsl:sort</em>
      <br/>If you install ICU support for xml:sort, &xslt4c; implements Unicode-style collation.</li>
</ul>

<p>If you choose to build Xalan with ICU, you will need to rebuild Xerces with ICU as well.</p>
<p>To get the ICU:</p> 
<ol>
  <li>Download and unzip the <resource-ref idref="icu-download"/> from the IBM developerWorks open source zone.<br/><br/></li>
  <li>Do an ICU build -- see the Windows NT or Unix build instructions in the build_instruct.html that accompanies the download.<br/>
      <em>Important</em> For Windows, define the environment variable ICUROOT and then restart Visual C++ or Visual Studio .NET. 
      in order for the ICUROOT variable to take effect.<br/><br/></li>
</ol>

<anchor name="icusupport"/>
<s3 title="Enabling ICU support for encoding">
<p>If you want to enable ICU support for encoding, you must integrate ICU with your &xml4c; build. &xml4c; uses ICU for input 
   encoding. See <resource-ref idref="xerces-build-icu"/>.</p>
<p>Once you have integrated the ICU with &xml4c;, &xslt4c; automatically uses ICU support for output encoding (the xsl:output 
   encoding attribute).</p>
</s3>

<s3 title="Enabling ICU support for number formatting and sorting"> 
<p>If you only want to use the ICU to support number formatting and sorting, you do not need to integrate the ICU with &xslt4c;, 
   but you must do the following in the application where you want to enable ICU support:</p>
<ol>
  <li>Define the environment variable ICUROOT.<br/><br/></li>
  <li>Substitute ICU support for format-number(), xsl:number, and/or xsl:sort.<br/><br/></li>
  <li>Rebuild the Xalan library to include the ICUBridge.</li>
</ol>
<p><em>ICUBridge</em></p>
<p>All &xslt4c; references to ICU are centralized in the ICUBridge module, which supplies the infrastructure for enabling ICU 
   support for number formatting and sorting.</p>
<source>
#include &lt;xalanc/ICUBridge/ICUBridge.hpp&gt;
#include &lt;xalanc/ICUBridge/FunctionICUFormatNumber.hpp&gt;
#include &lt;xalanc/ICUBridge/ICUXalanNumberFormatFactory.hpp&gt;
#include &lt;xalanc/ICUBridge/ICUBridgeCollationCompareFunctor.hpp&gt;
</source>
<p>For Windows, do a clean build of the Xalan library using the "XalanICU.dsw" workspace (for Visual C++ users) or 
   "XalanICU.sln" solution (for Visual Studio .NET users).</p>
<p>For UNIX:</p>
<ol>
  <li>Define the XALAN_USE_ICU environment variable.<br/><br/></li>
  <li>Set the XALANROOT environment variable to the path to to the ICU root (unless you have copied the ICU library to
      /usr/lib).<br/><br/></li> 
  <li><link idref="build_instruct" anchor="unix">Rebuild the Xalan library</link> (&xslt4c-linuxlib; for Linux, &xslt4c-aixlib; for AIX,
      &xslt4c-hplib; for HP-UX 11, and &xslt4c-solarislib; for Solaris).<br/><br/></li>
  <li>Be sure the Xalan library is on the library path (LD_LIBRARY_PATH for Red Hat Linux, LIBPATH for AIX, SHLIB_PATH for 
      HP-UX 11, LD_LIBRARY_PATH for Solaris).</li>
</ol>
<note>The command you use for setting environment variables depends on the shell you are using.<br/>
      For Bourne Shell, K Shell, or Bash use <em>export</em> ENVAR="val"<br/>
      For C Shell, use <em>setenv</em> ENVAR "val"<br/>
      where ENVAR is the environment variable name and val is the environment variable
      setting. You can check the setting of an environment variable with <em>echo</em> $ENVAR<br/>To define XALAN_USE_ICU, 
      set its value to "1".
</note>
<p><em>Number formatting</em></p>
<p>To enable ICU support for the XSLT format-number() function, do the following:</p>
<source>
// Install ICU support for the format-number() function.
FunctionICUFormatNumber::FunctionICUFormatNumberInstaller theInstaller;
</source>

<p><em>Sorting</em></p> 
<p>To enable ICU support for xsl:sort, do the following:</p>
<source>
// Set up a StylesheetExecutionContextDefaultobject
// (named theExecutionContext in the following fragment),
// and install the ICUCollationCompareFunctor.
ICUBridgeCollationCompareFunctortheICUFunctor;
theExecutionContext.installCollationCompareFunctor(&amp;theICUFunctor);
</source>
</s3>
</s2>

<anchor name="capi"/>
<s2 title="Basic XalanTransformer usage pattern with the C API">
<p>We also include a simple C interface for using the XalanTransformer class. See <jump href="apiDocs/XalanCAPI_8h.html">
   XalanTransformer/XalanCAPI.h</jump>. The <link idref="samples" anchor="apachemodulexslt">ApacheModuleXSLT</link> sample 
   illustrates the use of this C API.</p>
<p>Basic strategy:</p>

<s3 title="1. Include the XalanTransformer C API header">
<source>#include &lt;XalanTransformer/XalanCAPI.h&gt;</source>
</s3>
<s3 title="2. Initialize Xalan and Xerces">
<source>XalanInitialize();</source> 
</s3>
<s3 title="3. Create a Xalan transformer">
<source>
XalanHandle xalan = NULL;
xalan = CreateXalanTransformer();
</source>
</s3>
<s3 title="4. Perform each transformation">
<p>  For example:</p>
<source>
const char * xmlfilename = "foo.xml";
const char* xslfilename = "foo.xsl";
const char* outfilename = "foo.out";
int theResult = 0;
theResult = XalanTransformToFile(xmlfilename,
                                 xslfilename,
                                 outfilename,
                                 xalan);
</source>
<note>If the XML input file contains a stylesheet processing instruction that you want to use, use an empty XSLTInputSource 
      for the stylesheet argument.</note>
</s3>                             
    
<s3 title="5. Shut down Xalan">
<source>XalanTerminate();</source>
</s3>
</s2>

<anchor name="cvar"/>
<s2 title="Variations with the XalanTransformer C API">
<p>The <jump href="apiDocs/XalanCAPI_8h.html">Xalan C API</jump> supports approximately the same set of options as the C++ API. 
   In particular, you can</p>
<ul>
  <li>Use stylesheet processing instructions (PI) to indicate the URI of the stylesheet. Supply NULL for the stylesheet argument.<br/><br/></li>
  <li>Set stylesheet parameters. Use the SetStylesheetParam() function.<br/><br/></li>
  <li>Compile stylesheets. Use the CompileStylesheet() method to compile a stylesheet, and the TransformToFileCSS() or TransformToDataCSS() function to use the compiled stylesheet in a transformation.<br/><br/></li>
  <li>Parse XML sources. Use the XalanParseSource() or XalanParseSouceUseXalan() method.<br/><br/></li>
  <li>Place the transformation output in a character array. Use the TransformToData() or TransformToDataCSS() function. After you perform the transformation, use the XalanFreeData() function to free memory allocated for the output data.<br/><br/></li>
  <li>Send the output to a callback function to process blocks of output data as they arrive.</li>
</ul> 
<p>For a sample that sends output in blocks to a callback function, see <link idref="samples" anchor="apachemodulexslt">
   ApacheModuleXSLT</link>.</p>
</s2>

</s1>
