17 Using the XSLT and XVM Processors for C

This chapter contains these topics:

XVM Processor
XSLT processor
Using the Demo Files Included with the Software

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:

Create and use an XML meta-context object.
```
xctx = XmlCreate(&err,...);
```
Create and use an XSLT compiler object.
```
comp = XmlXvmCreateComp(xctx);
```

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

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

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

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

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);
```

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

err = XmlXvmSetOutputDom (vm, NULL);

err = XmlXvmSetOutputStream(vm, &xvm_stream);

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

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

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

err = XmlXvmSetBytecodeFile (vm, xslBytecodeFile);

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);

err = XmlXvmTransformDom (vm, xmlDomdoc);

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

Get the output tree fragment (if DOM output is set at step 5).
```
node = XmlXvmGetOutputDom (vm);
```

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.

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:

Create and use an XML meta-context object.
```
xctx = XmlCreate(&err,...);
```

Parse the XSLT stylesheet.

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

Create an XSLT processor for the stylesheet

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

Parse the instance XML document.

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

Set the output (optional). Default is DOM.

err = XmlXslSetOutputStream(xslproc, &stream);

Transform the XML document. This step can be repeated with the same or other XML documents.
```
err = XmlXslProcess (xslproc, xmlDomdoc, FALSE);
```
Get the output (if DOM).
```
node = XmlXslGetOutput(xslproc);
```

Delete objects.

XmlXslDestroy(xslproc);
XmlDestroy(xctx);

XPath Processor Usage Example

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

Create and use an XML meta-context object.
```
xctx = XmlCreate(&err,...);
```

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

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

Create an XPath processor.

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

Parse the XPath expression.

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

Evaluate the XPath expression.

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

Delete the objects.

XmlXPathDestroyCtx (xptproc);
XmlDestroy(xctx);

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.

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
i`den.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