Skip Headers
Oracle® Database XML C API Reference
11g Release 2 (11.2)

Part Number E10770-02
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub
CAXML00900

16 Package XSLTVM APIs for C

Package XSLTVM implements the XSL Transformation (XSLT) language as specified in W3C Recommendation 16 November 1999. The XSLTVM package contains two interfaces.

This chapter contains the following sections:

See Also:

CAXML6314

Using XSLTVM

XSLT Virtual Machine is the software implementation of a "CPU" designed to run compiled XSLT code. A concept of virtual machine assumes a compiler compiling XSLT stylesheets to a sequence of byte codes or machine instructions for the "XSLT CPU". The byte-code program is a platform-independent sequence of 2-byte units. It can be stored, cached and run on different XSLTVM. The XSLTVM uses the bytecode programs to transform instance XML documents. This approach clearly separates compile (design)-time from run-time computations and specifies a uniform way of exchanging data between instructions.

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

  1. Create/Use an XML meta context object.

    xctx = XmlCreate(,...);

  2. Create/Use an XSLT Compiler object.

    comp = XmlXvmCreateComp(xctx);

  3. Compile an XSLT stylesheets and cache the result bytecode.

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

  4. Create/Use an XSLTVM object. The explicit stack size setting are needed when XSLTVM terminates with "... Stack Overflow" message or when smaller memory footprints are required (see XmlXvmCreate).

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

  5. Set a stylesheet bytecode to the XSLTVM object.

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

  6. Transform an instance XML document.

    err = XmlXvmTransformFile(vm, xmlFile, baseuri);

  7. Clean.

    XmlXvmDestroy(vm);

    XmlXvmDestroyComp(comp);

    XmlDestroy(xctx);

CAXML6315

XSLTC Interface

Table 16-1 summarizes the methods available through the XSLTVM Interface.

CAXML6316Table 16-1 Summary of XSLTC Methods; XSLTVM Package

Function Summary

XmlXvmCompileBuffer()

Compile an XSLT stylesheet from buffer into bytecode.

XmlXvmCompileDom()

Compile an XSLT stylesheet from DOM into bytecode.

XmlXvmCompileFile()

Compile an XSLT stylesheet from file into bytecode.

XmlXvmCompileURI()

Compile XSLT stylesheet from URI into byte code.

XmlXvmCompileXPath()

Compile an XPath expression.

XmlXvmCreateComp()

Create an XSLT compiler.

XmlXvmDestroyComp()

Destroy an XSLT compiler object.

XmlXvmGetBytecodeLength()

Returns the bytecode length.


CAXML6317

XmlXvmCompileBuffer()

Compile an XSLT stylesheet from buffer into bytecode. Compiler flags could be one or more of the following:

The generated bytecode resides in a compiler buffer which is freed when next stylesheet is compiled or when compiler object is deleted. Hence, if the bytecode is to be reused it should be copied into another location.

CAXML6318Syntax

ub2 *XmlXvmCompileBuffer(
   xmlxvmcomp *comp,
   oratext *buffer,
   ub4 length, 
   oratext *baseURI,
   xmlxvmflag flags,
   xmlerr *error);
Parameter In/Out Description
comp
IN
compiler object
buffer
IN
pointer to buffer containing stylesheet document
length
IN
length of the stylesheet document in bytes
baseuri
IN
base URI of the document
flags
IN
flags for the current compilation
error
OUT
returned error code

CAXML6319Returns

(ub2 *) bytecode or NULL on error

CAXML6320

XmlXvmCompileDom()

Compile an XSLT stylesheet from DOM into bytecode. Compiler flags could be one or more of the following:

The generated bytecode resides in a compiler buffer which is freed when next stylesheet is compiled or when compiler object is deleted. Hence, if the bytecode is to be reused it should be copied into another location.

CAXML6321Syntax

ub2 *XmlXvmCompileDom(
   xmlxvmcomp *comp,
   xmldocnode *root,
   xmlxvmflag flags,
   xmlerr *error);
Parameter In/Out Description
comp
IN
compiler object
rooot
IN
root element of the stylesheet DOM
flags
IN
flags for the current compilation
error
OUT
returned error code

CAXML6322Returns

(ub2 *) bytecode or NULL on error

CAXML6323

XmlXvmCompileFile()

Compile XSLT stylesheet from file into bytecode. Compiler flags could be one or more of the following:

The generated bytecode resides in a compiler buffer which is freed when next stylesheet is compiled or when compiler object is deleted. Hence, if the bytecode is to be reused it should be copied into another location.

CAXML6324Syntax

ub2 *XmlXvmCompileFile(
   xmlxvmcomp *comp, 
   oratext *path,
   oratext *baseURI,
   xmlxvmflag flags,
   xmlerr *error);
Parameter In/Out Description
comp
IN
compiler object
path
IN
path of XSL stylesheet file
baseuri
IN
base URI of the document
flags
IN
flags for the current compilation
error
OUT
returned error code

CAXML6325Returns

(ub2 *) bytecode or NULL on error

CAXML6326

XmlXvmCompileURI()

Compile XSLT stylesheet from URI into bytecode. Compiler flags could be one or more of the following:

The generated bytecode resides in a compiler buffer which is freed when next stylesheet is compiled or when compiler object is deleted. Hence, if the bytecode is to be reused it should be copied into another location.

CAXML6327Syntax

ub2 *XmlXvmCompileURI(
   xmlxvmcomp *comp, 
   oratext *uri, 
   xmlxvmflag flags, 
   xmlerr *error);
Parameter In/Out Description
comp
IN
compiler object
uri
IN
URI of the file that contains the XSL stylesheet
flags
IN
flags for the current compilation
error
OUT
returned error code

CAXML6328Returns

(ub2 *) bytecode or NULL on error

CAXML6329

XmlXvmCompileXPath()

Compiles an XPath expression. The optional pfxmap is used to map namespace prefixes to URIs in the XPath expression. It is an array of prefix, URI values, ending in NULL, and so on.

CAXML6330Syntax

ub2 *XmlXvmCompileXPath(
   xmlxvmcomp *comp, 
   oratext *xpath,
   oratext **pfxmap,
   xmlerr *error);
Parameter In/Out Description
comp
IN
compiler object
xpath
IN
XPath expression
pfxmap
IN
array of prefix-URI mappings
error
OUT
returned error code

CAXML6331Returns

(ub2 *) XPath expression bytecode or NULL on error

CAXML6332

XmlXvmCreateComp()

Create an XSLT compiler object. The XSLT compiler is used to compile XSLT stylesheets into bytecode.

CAXML6333Syntax

xmlxvmcomp *XmlXvmCreateComp(
   xmlctx *xctx);
Parameter In/Out Description
xctx
IN
XML context

CAXML6334Returns

(xmlxvmcomp *) XSLT compiler object, or NULL on error

CAXML6335

XmlXvmDestroyComp()

Destroys an XSLT compiler object

CAXML6336Syntax

void XmlXvmDestroyComp(
   xmlxvmcomp *comp);
Parameter In/Out Description
comp
IN
XSLT compiler object

CAXML6337

XmlXvmGetBytecodeLength()

The bytecode length is needed when the bytecode is to be copied or when it is set into XSLTVM.

CAXML6338Syntax

ub4 XmlXvmGetBytecodeLength(
   ub2 *bytecode,
   xmlerr *error);
Parameter In/Out Description
bytecode
IN
bytecode buffer
error
OUT
returned error code

CAXML6339Returns

(ub4) The bytecode length in bytes.

CAXML6340

XSLTVM Interface

Table 16-2 summarizes the methods available through the XSLTVM Interface.

CAXML6341Table 16-2 Summary of XSLTVM Methods; Package XSLTVM

Function Summary

XMLXVM_DEBUG_F()

XMLXSLTVM debug function.

XmlXvmCreate()

Create an XSLT virtual machine.

XmlXvmDestroy()

Destroys an XSLT virtual machine.

XmlXvmEvaluateXPath()

Evaluate already-compiled XPath expression.

XmlXvmGetObjectBoolean()

Get boolean value of XPath object.

XmlXvmGetObjectNSetNode()

Get node from nodeset type XPathobject.

XmlXvmGetObjectNSetNum()

Get number of nodes in nodeset type XPathobject.

XmlXvmGetObjectNumber()

Get number from XPath object.

XmlXvmGetObjectString()

Get string from XPath object.

XmlXvmGetObjectType()

Get XPath object type.

XmlXvmGetOutputDom()

Returns the output DOM.

XmlXvmResetParams()

Resets the stylesheet top level text parameters.

XmlXvmSetBaseURI()

Sets the base URI for the XLTVM.

XmlXvmSetBytecodeBuffer()

Set the compiled bytecode.

XmlXvmSetBytecodeFile()

Set the compiled byte code from file.

XmlXvmSetBytecodeURI()

Set the compiled bytecode.

XmlXvmSetDebugFunc()

Set a callback function for debugging.

XmlXvmSetOutputDom()

Sets the XSLTVM to output document node.

XmlXvmSetOutputEncoding()

Sets the encoding for the XSLTVM output.

XmlXvmSetOutputSax()

Sets XSLTVM to output SAX.

XmlXvmSetOutputStream()

Set the XSLTVM output to a user-defined stream.

XmlXvmSetTextParam()

Set the stylesheet top-level text parameter.

XmlXvmTransformBuffer()

Run compiled XSLT stylesheet on XML document in memory.

XmlXvmTransformDom()

Run compiled XSLT stylesheet on XML document as DOM.

XmlXvmTransformFile()

Run compiled XSLT stylesheet on XML document in file.

XmlXvmTransformURI()

Run compiled XSLT stylesheet on XML document from URI.


CAXML6342

XMLXVM_DEBUG_F()

Debug callback function for XSLT VM.

CAXML6343Syntax

#define XMLXVM_DEBUG_F(func, line, file, obj, n)
void func(
   ub2 line,
   oratext *file,
   xvmobj *obj,
   ub4 n)
Parameter In/Out Description
line
IN
source stylesheet line number
file
IN
stylesheet filename
obj
IN
current VM object
n
IN
index of current node

CAXML6344

XmlXvmCreate()

Create an XSLT virtual machine. Zero or more of the following XSLTVM properties could be set by using this API:

If the stack size is not specified the default size is used. The explicit stack size setting is needed when XSLTVM terminates with "Stack Overflow" message or when smaller memory footprints are required.

CAXML6345Syntax

xmlxvm *XmlXvmCreate(
   xmlctx *xctx, 
   list);
Parameter In/Out Description
xctx
IN
XML context
list
IN
NULL-terminated list of properties to set; can be empty

CAXML6346Returns

(xmlxvm *) XSLT virtual machine object, or NULL on error

See Also:

XmlXvmDestroy()
CAXML6347

XmlXvmDestroy()

Destroys an XSLT virtual machine

CAXML6348Syntax

void XmlXvmDestroy(
   xmlxvm *vm);
Parameter In/Out Description
vm
IN
VM object

See Also:

XmlXvmCreate()
CAXML6349

XmlXvmEvaluateXPath()

Evaluate already-compiled XPath expression

CAXML6350Syntax

xvmobj *XmlXvmEvaluateXPath(
   xmlxvm *vm, 
   ub2 *bytecode, 
   ub4 ctxpos,
   ub4 ctxsize,
   xmlnode *ctxnode);
Parameter In/Out Description
vm
IN
XSLTVM object
bytecode
IN
XPath expression bytecode
ctxpos
IN
current context position
ctxsize
IN
current context size
ctxnode
IN
current context node

CAXML6351Returns

(xvmobj *) XPath object

CAXML6352

XmlXvmGetObjectBoolean()

Get boolean value of XPath object

CAXML6353Syntax

boolean XmlXvmGetObjectBoolean(
   xvmobj *obj);
Parameter In/Out Description
obj
IN
object

CAXML6354Returns

(boolean) value of an XPath object

CAXML6355

XmlXvmGetObjectNSetNode()

Get node from nodeset-type XPath object

CAXML6356Syntax

xmlnode *XmlXvmGetObjectNSetNode(
   xvmobj *obj,
   ub4 i);
Parameter In/Out Description
obj
IN
object
i
IN
node index in nodeset

CAXML6357Returns

(xmlnode *) The object type or values.

CAXML6358

XmlXvmGetObjectNSetNum()

Get number of nodes in nodeset-type XPath object

CAXML6359Syntax

ub4 XmlXvmGetObjectNSetNum(
   xvmobj *obj);
Parameter In/Out Description
obj
IN
object

CAXML6360Returns

(ub4) number of nodes in nodeset

CAXML6361

XmlXvmGetObjectNumber()

Get number from XPath object.

CAXML6362Syntax

double XmlXvmGetObjectNumber(
   xvmobj *obj);
Parameter In/Out Description
obj
IN
object

CAXML6363Returns

(double) number

CAXML6364

XmlXvmGetObjectString()

Get string from XPath object.

CAXML6365Syntax

oratext *XmlXvmGetObjectString(
   xvmobj *obj);
Parameter In/Out Description
obj
IN
object

CAXML6366Returns

(oratext *) string

CAXML6367

XmlXvmGetObjectType()

Get XPath object type

CAXML6368Syntax

xmlxvmobjtype XmlXvmGetObjectType(
   xvmobj *obj);
Parameter In/Out Description
obj
IN
object

CAXML6369Returns

(xmlxvmobjtype) type-code for object

CAXML6370

XmlXvmGetOutputDom()

Returns the root node of the result DOM tree (if any). XmlXvmSetOutputDom has to be used before transformation to set the VM to output a DOM tree (the default VM output is a stream).

CAXML6371Syntax

xmlfragnode *XmlXvmGetOutputDom(
   xmlxvm *vm);
Parameter In/Out Description
vm
IN
VM object

CAXML6372Returns

(xmlfragnode *) output DOM, or NULL in a case of SAX or Stream output.

CAXML6373

XmlXvmResetParams()

Resets the stylesheet top-level parameters with their default values.

CAXML6374Syntax

void XmlXvmResetParams(
   xmlxvm *vm);
Parameter In/Out Description
vm
IN
VM object

CAXML6375

XmlXvmSetBaseURI()

Sets the base URI for the XSLTVM. The baseuri is used by VM to the compose the path XML documents to be loaded for transformation using document or XmlXvmTransformFile.

CAXML6376Syntax

xmlerr XmlXvmSetBaseURI(
   xmlxvm *vm, 
   oratext *baseuri);
Parameter In/Out Description
vm
IN
VM object
baseuri
IN
VM base URI for reading and writing documents

CAXML6377Returns

(xmlerr) error code.

CAXML6378

XmlXvmSetBytecodeBuffer()

Set the compiled bytecode from buffer. Any previously set bytecode is replaced. An XML transformation can't be performed if the stylesheet bytecode is not set. The VM doesn't copy the bytecode into internal buffer, hence the it shouldn't be freed before VM finishes using it.

CAXML6379Syntax

xmlerr XmlXvmSetBytecodeBuffer(
   xmlxvm *vm, 
   ub2 *buffer, 
   size_t buflen);
Parameter In/Out Description
vm
IN
XSLT VM context
buffer
IN
user's buffer
buflen
IN
size of buffer, in bytes

CAXML6380Returns

(xmlerr) numeric error code, XMLERR_OK [0] on success

CAXML6381

XmlXvmSetBytecodeFile()

Set the compiled bytecode from file. Any previously set bytecode is replaced. An XML transformation can't be performed if the stylesheet bytecode is not set.

CAXML6382Syntax

xmlerr XmlXvmSetBytecodeFile(
   xmlxvm *vm,
   oratext *path);
Parameter In/Out Description
vm
IN
XSLT VM context
path
IN
path of bytecode file

CAXML6383Returns

(xmlerr) numeric error code, XMLERR_OK [0] on success

CAXML6384

XmlXvmSetBytecodeURI()

Set the compiled bytecode from URI. Any previously set bytecode is replaced. An XML transformation can't be performed if the stylesheet bytecode is not set.

CAXML6385Syntax

xmlerr XmlXvmSetBytecodeURI(
   xmlxvm *vm,
   oratext *uri);
Parameter In/Out Description
vm
IN
XSLT VM context
uri
IN
path of bytecode file

CAXML6386Returns

(xmlerr) numeric error code, XMLERR_OK [0] on success

CAXML6387

XmlXvmSetDebugFunc()

The user callback function is invoked by VM every time the execution reaches a new line in the XSLT stylesheet. The VM passes to the user the stylesheet file name, the line number, the current context nodes-set and the current node index in the node-set. IMPORTANT - the stylesheet has to be compiled with flag XMLXVM_DEBUG.

CAXML6388Syntax

#define XMLXVM_DEBUG_FUNC(func)
void func (ub2 line, oratext *filename, xvmobj *obj, ub4 n)
xmlerr XmlXvmSetDebugFunc(
   xmlxvm *vm,
   XMLXVM_DEBUG_FUNC(debugcallback));
Parameter In/Out Description
vm
IN
XSLT VM context
func
IN
callback function

CAXML6389Returns

(xmlerr) numeric error code, XMLERR_OK [0] on success

CAXML6390

XmlXvmSetOutputDom()

Sets the XSLTVM to output DOM. If xmldocnode==NULL, then the result DOM tree belongs to the VM object and is deleted when a new transformation is performed or when the VM object is deleted. If the result DOM tree is to be used for longer period of time then an xmldocnode has to be created and set to the VM object.

CAXML6391Syntax

xmlerr XmlXvmSetOutputDom(
   xmlxvm *vm,
   xmldocnode *doc);
Parameter In/Out Description
vm
IN
VM object
doc
IN
empty document

CAXML6392Returns

(xmlerr) error code

CAXML6393

XmlXvmSetOutputEncoding()

Sets the encoding for the XSLTVM stream output. If the input (data) encoding is different from the one set by this APIs then encoding conversion is performed. This APIs overrides the encoding set in the XSLT stylesheet (if any).

CAXML6394Syntax

xmlerr XmlXvmSetOutputEncoding(
   xmlxvm *vm, 
   oratext *encoding);
Parameter In/Out Description
vm
IN
VM object
encoding
IN
output encoding

CAXML6395Returns

(xmlerr) error code.

CAXML6396

XmlXvmSetOutputSax()

Set XSLTVM to output SAX. If the SAX callback interface object is provided the VM outputs the result document in a form of SAX events using the user specified callback functions.

CAXML6397Syntax

xmlerr XmlXvmSetOutputSax(
   xmlxvm *vm,
   xmlsaxcb *saxcb, 
   void *saxctx);
Parameter In/Out Description
vm
IN
VM object
saxcb
IN
SAX callback object
saxctx
IN
SAX context

CAXML6398Returns

(xmlerr) error code

CAXML6399

XmlXvmSetOutputStream()

Set the XSLTVM output to a user-defined stream. The default XSLTVM output is a stream. This APIs overrides the default stream with user specified APIs for writing.

CAXML6400Syntax

xmlerr XmlXvmSetOutputStream(
   xmlxvm *vm,
   xmlostream *ostream);
Parameter In/Out Description
vm
IN
VM object
ostream
IN
stream object

CAXML6401Returns

(xmlerr) error code.

CAXML6402

XmlXvmSetTextParam()

Set the stylesheet top-level text parameter. The parameter value set in the XSLT stylesheet is overwritten. Since the top-level parameters are reset with stylesheet values after each transformation, this APIs has to be called again.

CAXML6403Syntax

xmlerr XmlXvmSetTextParam(
   xmlxvm *vm,
   oratext *name,
   oratext *value);
Parameter In/Out Description
vm
IN
VM object
name
IN
name of top-level parameter
value
IN
value of top-level parameter

CAXML6404Returns

(xmlerr) error code, XMLERR_SUCC [0] on success.

CAXML6405

XmlXvmTransformBuffer()

Run compiled XSLT stylesheet on XML document in memory. The compiled XSLT stylesheet (bytecode) should be set using XmlXvmSetBytecodeXXX prior to this call.

CAXML6406Syntax

xmlerr XmlXvmTransformBuffer(
   xmlxvm *vm,
   oratext *buffer,
   ub4 length,
   oratext *baseURI);
Parameter In/Out Description
vm
IN
VM object
buffer
IN
NULL-terminated buffer that contains the XML document
length
IN
length of the XML document
baseURI
IN
base URI of XML document

CAXML6407Returns

(xmlerr) error code.

CAXML6408

XmlXvmTransformDom()

Run compiled XSLT stylesheet on XML document as DOM. The compiled XSLT stylesheet (bytecode) should be set using XmlXvmSetBytecodeXXX prior to this call.

CAXML6409Syntax

xmlerr XmlXvmTransformDom(
   xmlxvm *vm,
   xmldocnode *root);
Parameter In/Out Description
vm
IN
VM object
root
IN
root element of XML document's DOM

CAXML6410Returns

(xmlerr) error code.

CAXML6411

XmlXvmTransformFile()

Run compiled XSLT stylesheet on XML document in file. The compiled XSLT stylesheet (bytecode) should be set using XmlXvmSetBytecodeXXX prior to this call.

CAXML6412Syntax

xmlerr XmlXvmTransformFile(
   xmlxvm *vm,
   oratext *path,
   oratext *baseURI);
Parameter In/Out Description
vm
IN
VM object
path
IN
path of XML document to transform
baseURI
IN
base URI of XML document

CAXML6413Returns

(xmlerr) error code

CAXML6414

XmlXvmTransformURI()

Run compiled XSLT stylesheet on XML document from URI. The compiled XSLT stylesheet (bytecode) should be set using XmlXvmSetBytecodeXXX prior to this call.

CAXML6415Syntax

xmlerr XmlXvmTransformURI(
   xmlxvm *vm, 
   oratext *uri);
Parameter In/Out Description
vm
IN
VM object
uri
IN
URI of XML document to transform

CAXML6416Returns

(xmlerr) error code.

Reader Comment

   

Comments, corrections, and suggestions are forwarded to authors every week. By submitting, you confirm you agree to the terms and conditions. Use the OTN forums for product questions. For support or consulting, file a service request through My Oracle Support.

Hide Navigation

Quick Lookup

Database Library · Master Index · Master Glossary · Book List · Data Dictionary · SQL Keywords · Initialization Parameters · Advanced Search · Error Messages

Main Categories

This Page

  • Using XSLTVM
  • XSLTC Interface
    • XmlXvmCompileBuffer()
    • XmlXvmCompileDom()
    • XmlXvmCompileFile()
    • XmlXvmCompileURI()
    • XmlXvmCompileXPath()
    • XmlXvmCreateComp()
    • XmlXvmDestroyComp()
    • XmlXvmGetBytecodeLength()
  • XSLTVM Interface
    • XMLXVM_DEBUG_F()
    • XmlXvmCreate()
    • XmlXvmDestroy()
    • XmlXvmEvaluateXPath()
    • XmlXvmGetObjectBoolean()
    • XmlXvmGetObjectNSetNode()
    • XmlXvmGetObjectNSetNum()
    • XmlXvmGetObjectNumber()
    • XmlXvmGetObjectString()
    • XmlXvmGetObjectType()
    • XmlXvmGetOutputDom()
    • XmlXvmResetParams()
    • XmlXvmSetBaseURI()
    • XmlXvmSetBytecodeBuffer()
    • XmlXvmSetBytecodeFile()
    • XmlXvmSetBytecodeURI()
    • XmlXvmSetDebugFunc()
    • XmlXvmSetOutputDom()
    • XmlXvmSetOutputEncoding()
    • XmlXvmSetOutputSax()
    • XmlXvmSetOutputStream()
    • XmlXvmSetTextParam()
    • XmlXvmTransformBuffer()
    • XmlXvmTransformDom()
    • XmlXvmTransformFile()
    • XmlXvmTransformURI()

This Document

New and changed documents:
RSS Feed HTML RSS Feed PDF