17 Using the XSLT and XVM Processors for C

This chapter contains these topics:

Note:

Use the new unified C API for new XDK and Oracle XML DB applications. The old C functions are deprecated and supported only for backward compatibility, but will not be enhanced. They will be removed in a future release.

The new C API is described in Chapter 18, "Using the XML Parser for C".

XVM Processor

The Oracle XVM Package implements the XSL Transformation (XSLT) language as specified in the W3C Recommendation of 16 November 1999. The package includes XSLT Compiler and XSLT Virtual Machine (XVM). The implementation by Oracle of the XSLT compiler and the XVM enables compilation of XSLT (Version 1.0) into bytecode format, which is executed by the virtual machine. XSLT Virtual Machine is the software implementation of a "CPU" designed to run compiled XSLT code. The virtual machine assumes a compiler compiling XSLT stylesheets to a sequence of bytecodes or machine instructions for the "XSLT CPU". The bytecode program is a platform-independent sequence of 2-byte units. It can be stored, cached and run on different XVMs. The XVM uses the bytecode programs to transform instance XML documents. This approach clearly separates compile-time from run-time computations and specifies a uniform way of exchanging data between instructions. The benefits of this approach are:

  • An XSLT stylesheet can be compiled, saved in a file, and re-used often, even on different platforms.

  • The XVM is significantly faster and uses less memory than other XSLT processors.

  • The bytecodes are not language-dependent. There is no difference between code generated from a C or C++ XSLT compiler.

XVM Usage Example

A typical scenario of using the package APIs has the following steps:

  1. Create and use an XML meta-context object.

    xctx = XmlCreate(&err,...);

  2. Create and use an XSLT compiler object.

    comp = XmlXvmCreateComp(xctx);

  3. Compile an XSLT stylesheet or XPath expression and store or cache the resulting bytecode.

    code = XmlXvmCompileFile(comp, xslFile, baseuri, flags, &err);

    or

    code = XmlXvmCompileDom (comp, xslDomdoc, flags, &err);

    or

    code = XmlXvmCompileXPath (comp, xpathexp,  namespaces, &err);

  4. Create and use an XVM object. The explicit stack size setting is needed when XVM terminates with a "Stack Overflow" message or when smaller memory footprints are required. See XmlXvmCreate().

    vm = XmlXvmCreate(xctx, "StringStack", 32, "NodeStack", 24, NULL);

  5. Set the output (optional). Default is a stream.

    err = XmlXvmSetOutputDom (vm, NULL);

    or

    err = XmlXvmSetOutputStream(vm, &xvm_stream);

    or

    err = XmlXvmSetOutputSax(vm, &xvm_callback, NULL);

  6. Set a stylesheet bytecode to the XVM object. Can be repeated with other bytecode.

    len = XmlXvmGetBytecodeLength(code, &err);
err = XmlXvmSetBytecodeBuffer(vm, code, len);

    or

    err = XmlXvmSetBytecodeFile (vm, xslBytecodeFile);

  7. Transform an instance XML document or evaluate a compiled XPath expression. Can be repeated with the same or other XML documents.

    err = XmlXvmTransformFile(vm, xmlFile, baseuri);

    or

    err = XmlXvmTransformDom (vm, xmlDomdoc);

    or

    obj  = (xvmobj*)XmlXvmEvaluateXPath (vm, code, 1, 1, node);

  8. Get the output tree fragment (if DOM output is set at step 5).

    node = XmlXvmGetOutputDom (vm);

  9. Delete the objects.

    XmlXvmDestroy(vm);
XmlXvmDestroyComp(comp);
XmlDestroy(xctx);

Using the XVM Processor Command-Line Utility

The XVM processor is accessed from the command-line this way:

xvm

Usage:

xvm options xslfile xmlfile

xvm options xpath xmlfile



Options:


-c        Compile xslfile. The bytecode is in "xmlfile.xvm".
-ct       Compile xslfile and transform xmlfile.
-t        Transform xmlfile using bytecode from xslfile.
-xc       Compile xpath. The bytecode is in "code.xvm".
-xct      Compile and evaluate xpath with xmlfile.
-xt       Evaluate XPath bytecode from xpath with xmlfile.





Examples:


xvm -ct  db.xsl db.xml
xvm -t   db.xvm db.xml
xvm -xct "doc/employee[15]/family" db.xml







Accessing XVM Processor for C


Oracle XVM Processor for C is part of the standard installation of Oracle Database.




See Also:













XSLT Processor


The Oracle XSL/XPath Package implements the XSL Transformation (XSLT) language as specified in the W3C Recommendation of 16 November 1999. The package includes the XSLT processor and XPath Processor. The Oracle implementation of the XSLT processor follows the more common design approach, which melts 'compiler' and 'processor' into one object.




XSLT Processor Usage Example


A typical scenario of using the package APIs has the following steps:


    

  1. 

    Create and use an XML meta-context object.
    

    xctx = XmlCreate(&err,...);

    2. 

  2. 

    Parse the XSLT stylesheet.
    

    xslDomdoc = XmlLoadDom(xctx, &err, "file", xslFile, "base_uri", baseuri, NULL);

    3. 

  3. 

    Create an XSLT processor for the stylesheet
    

    xslproc = XmlXslCreate (xctx, xslDomdoc, baseuri, &err);

    4. 

  4. 

    Parse the instance XML document.
    

    xmlDomdoc = XmlLoadDom(xctx, &err, "file", xmlFile,  "base_uri", baseuri, NULL);

    5. 

  5. 

    Set the output (optional). Default is DOM.
    

    err = XmlXslSetOutputStream(xslproc, &stream);

    6. 

  6. 

    Transform the XML document. This step can be repeated with the same or other XML documents.
    

    err = XmlXslProcess (xslproc, xmlDomdoc, FALSE);

    7. 

  7. 

    Get the output (if DOM).
    

    node = XmlXslGetOutput(xslproc);

    8. 

  8. 

    Delete objects.
    

    XmlXslDestroy(xslproc);
XmlDestroy(xctx);

    9. 








XPath Processor Usage Example


A typical scenario of using the package APIs has the following steps:


    

  1. 

    Create and use an XML meta-context object.
    

    xctx = XmlCreate(&err,...);

    2. 

  2. 

    Parse the XML document or get the current node from already existing DOM.
    

    node = XmlLoadDom(xctx, &err, "file", xmlFile,  "base_uri", baseuri, NULL);

    3. 

  3. 

    Create an XPath processor.
    

    xptproc = XmlXPathCreateCtx(xctx, NULL, node, 0, NULL);

    4. 

  4. 

    Parse the XPath expression.
    

    exp = XmlXPathParse (xptproc, xpathexpr, &err);

    5. 

  5. 

    Evaluate the XPath expression.
    

    obj = XmlXPathEval(xptproc, exp, &err);

    6. 

  6. 

    Delete the objects.
    

    XmlXPathDestroyCtx (xptproc);
XmlDestroy(xctx);

    7. 









Using the C XSLT Processor Command-Line Utility


You can call the C Oracle XSLT processor as an executable by invoking bin/xsl:


xsl [switches] stylesheet instance
or
xsl -f [switches] [document filespec]



If no style sheet is provided, no output is generated. If there is a style sheet, but no output file, output goes to stdout.


Table 17-1 lists the command line options.




Table 17-1 XSLT Processor for C: Command Line Options






Option
Description








-B BaseUri




Set the Base URI for XSLT processor: BaseUri of http://pqr/xsl.txt resolves pqr.txt to http://pqr/pqr.txt








-e encoding




Specify default input file encoding (-ee to force).








-E encoding




Specify DOM or SAX encoding.








-f




File - interpret as filespec, not URI.








-G xptrexprs




Evaluates XPointer schema examples given in a file.








-h




Help - show this usage. (Use -hh for more options.)








-hh




Show complete options list.








-i n




Number of times to iterate the XSLT processing.








-l language




Language for error reporting.








-o XSLoutfile




Specifies output file of XSLT processor.








-v




Version - display parser version then exit.








-V var value




Test top-level variables in C XSLT.








-w




Whitespace - preserve all whitespace.








-W




Warning - stop parsing after a warning.















Accessing Oracle XSLT processor for C


Oracle XSLT processor for C is part of the standard installation of Oracle Database.




See Also:













Using the Demo Files Included with the Software


$ORACLE_HOME/xdk/demo/c/parser/ directory contains several XML applications to illustrate how to use the XSLT for C.


Table 17-2 lists the files in that directory:




Table 17-2 XSLT for C Demo Files






Sample File Name
Description








XSLSample.c




Source for XSLSample program








XSLSample.std




Expected output from XSLSample








class.xml




XML file that can be used with XSLSample








iden.xsl




Stylesheet that can be used with XSLSample








cleo.xml




XML version of Shakespeare's play








XVMSample.c




Sample usage of XSLT Virtual Machine and compiler. It takes two filenames as input - XML file and XSLT stylesheet file.








XVMXPathSample.c




Sample usage of XSLT Virtual Machine and compiler. It takes XML file name and XPath expression as input. Generates the result of the evaluated XPath expression.








XSLXPathSample.c




Sample usage of XSL/XPath processor. It takes XML file name and XPath expression as input. Generates the result of the evaluated XPath expression.













Building the C Demo Programs for XSLT


Change directories to the demo directory and read the README file. This will explain how to build the sample programs according to your operating system.


Here is the usage of XSLT processor sample XSLSample, which takes two files as input, the XML file and the XSLT stylesheet:


XSLSample xmlfile xslss