19 Using the XSLT and XVM Processors for C

This chapter explains how to use the Extensible Stylesheet Language Transformation (XSLT) and XSLT Virtual Machine (XVM) processors for C.

Topics:

Note:

Use the unified C application programming interface (API) for Oracle XML Developer's Kit (XDK) and Oracle XML DB applications. Older, nonunified C functions are deprecated and supported only for backward compatibility. They will be removed in a future release.

The unified C API is described in Chapter 20, "Using the XML Parser for C".

XSLT XVM Processor

The Oracle XVM Package includes the XSLT Compiler and the XVM. This package implements the XSLT language as specified in the World Wide Web Consortium (W3C) Recommendation of 16 November 1999.

Implementing the XSLT compiler and the XVM enables compilation of XSLT (Version 1.0) into bytecode format, which is executed by the virtual machine. XVM is the software implementation of a "CPU" designed to run compiled XSLT code. The virtual machine assumes a compiler compiling XSLT style sheets 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 Extensible Markup Language (XML) documents. This approach clearly separates compile-time from runtime computations and specifies a uniform way of exchanging data between instructions.

The benefits of this approach are:

  • An XSLT style sheet can be compiled, saved in a file, and reused 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 these 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 style sheet 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 style sheet 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 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 melds "compiler" and "processor" into one object.




XSLT Processor Usage Example


A typical scenario of using the package APIs has these 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 Document Object Model (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 these 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 19-1 lists the command line options.




Table 19-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 Simple API for XML (SAX) encoding.








-f




File—interpret as filespec, not Universal Resource Identifier (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




White Space—preserve all white space.








-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 show how to use the XSLT for C.


Table 19-2 lists the files in that directory:




Table 19-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




Style sheet that can be used with XSLSample








cleo.xml




XML version of Shakespeare's play








XVMSample.c




Sample usage of XVM and compiler. It takes two file names as input—XML file and XSLT style sheet file.








XVMXPathSample.c




Sample usage of XVM 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 document explains 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 style sheet:


XSLSample xmlfile xslss