Skip Headers

Oracle® XML API Reference 10g Release 1 (10.1) Part No. B10789-01 |
| Contents

## XSLTVM Interface

Table 13-2 summarizes the methods of available through the XSLTVM Interface.

Table 13-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.

### XMLXVM_DEBUG_F

Debug callback function for XSLT VM

Syntax

    #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

See Also: XmlXvmSetDebugFunc

### XmlXvmCreate

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

- `"VMStack", size` sets the size[Kbyte] of the main VM stack; default size is 4K.

- `"NodeStack", size` sets the size[Kbyte] of the node-stack; default size is 16K.

- `"StringStack", size` sets the size[Kbyte] of the string-stack; default size is 64K.

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.

Syntax

    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

Returns

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

See Also: XmlXvmDestroy

### XmlXvmDestroy

Destroys an XSLT virtual machine

Syntax

    void XmlXvmDestroy(
       xmlxvm *vm);

Parameter | In/Out | Description
--- | --- | ---
    vm
    IN
| VM object

See Also: XmlXvmCreate

### XmlXvmEvaluateXPath

Evaluate already-compiled XPath expression

Syntax

    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

Returns

`(xvmobj *)` XPath object

### XmlXvmGetObjectBoolean

Get boolean value of XPath object

Syntax

    boolean XmlXvmGetObjectBoolean(
       xvmobj *obj);

Parameter | In/Out | Description
--- | --- | ---
    obj
    IN
| object

Returns

`(boolean)` value of an XPath object

See Also: XmlXvmGetObjectType, XmlXvmGetObjectNSetNum, XmlXvmGetObjectNSetNode, XmlXvmGetObjectNumber, XmlXvmGetObjectBoolean

### XmlXvmGetObjectNSetNode

Get node from nodeset-type XPath object

Syntax

    xmlnode *XmlXvmGetObjectNSetNode(
       xvmobj *obj,
       ub4 i);

Parameter | In/Out | Description
--- | --- | ---
    obj
    IN
| object
    i
    IN
| node index in nodeset

Returns

`(xmlnode *)` The object type or values.

See Also: XmlXvmGetObjectType, XmlXvmGetObjectNSetNum, XmlXvmGetObjectString, XmlXvmGetObjectNumber, XmlXvmGetObjectBoolean

### XmlXvmGetObjectNSetNum

Get number of nodes in nodeset-type XPath object

Syntax

    ub4 XmlXvmGetObjectNSetNum(
       xvmobj *obj);

Parameter | In/Out | Description
--- | --- | ---
    obj
    IN
| object

Returns

`(ub4)` number of nodes in nodeset

See Also: XmlXvmGetObjectType, XmlXvmGetObjectNSetNode, XmlXvmGetObjectString, XmlXvmGetObjectNumber, XmlXvmGetObjectBoolean

### XmlXvmGetObjectNumber

Get number from XPath object.

Syntax

    double XmlXvmGetObjectNumber(
       xvmobj *obj);

Parameter | In/Out | Description
--- | --- | ---
    obj
    IN
| object

Returns

`(double)` number

See Also: XmlXvmGetObjectType, XmlXvmGetObjectNSetNum, XmlXvmGetObjectNSetNode, XmlXvmGetObjectString, XmlXvmGetObjectBoolean

### XmlXvmGetObjectString

Get string from XPath object.

Syntax

    oratext *XmlXvmGetObjectString(
       xvmobj *obj);

Parameter | In/Out | Description
--- | --- | ---
    obj
    IN
| object

Returns

`(oratext *)` string

See Also: XmlXvmGetObjectType, XmlXvmGetObjectNSetNum, XmlXvmGetObjectNSetNode, XmlXvmGetObjectNumber, XmlXvmGetObjectBoolean

### XmlXvmGetObjectType

Get XPath object type

Syntax

    xmlxvmobjtype XmlXvmGetObjectType(
       xvmobj *obj);

Parameter | In/Out | Description
--- | --- | ---
    obj
    IN
| object

Returns

`(xmlxvmobjtype)` type-code for object

See Also: XmlXvmGetObjectNSetNum, XmlXvmGetObjectNSetNode, XmlXvmGetObjectString, XmlXvmGetObjectNumber, XmlXvmGetObjectBoolean

### 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).

Syntax

    xmlfragnode *XmlXvmGetOutputDom(
       xmlxvm *vm);

Parameter | In/Out | Description
--- | --- | ---
    vm
    IN
| VM object

Returns

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

See Also: XmlXvmSetOutputDom

### XmlXvmResetParams

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

Syntax

    void XmlXvmResetParams(
       xmlxvm *vm);

Parameter | In/Out | Description
--- | --- | ---
    vm
    IN
| VM object

### 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`.

Syntax

    xmlerr XmlXvmSetBaseURI(
       xmlxvm *vm,
       oratext *baseuri);

Parameter | In/Out | Description
--- | --- | ---
    vm
    IN
| VM object
    baseuri
    IN
| VM base URI for reading and writing documents

Returns

`(xmlerr)` error code.

### 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.

Syntax

    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

Returns

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

See Also: XmlXvmSetBytecodeFile, XmlXvmSetBytecodeURI

### 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.

Syntax

    xmlerr XmlXvmSetBytecodeFile(
       xmlxvm *vm,
       oratext *path);

Parameter | In/Out | Description
--- | --- | ---
    vm
    IN
| XSLT VM context
    path
    IN
| path of bytecode file

Returns

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

See Also: XmlXvmSetBytecodeURI, XmlXvmSetBytecodeBuffer

### 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.

Syntax

    xmlerr XmlXvmSetBytecodeURI(
       xmlxvm *vm,
       oratext *uri);

Parameter | In/Out | Description
--- | --- | ---
    vm
    IN
| XSLT VM context
    uri
    IN
| path of bytecode file

Returns

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

See Also: XmlXvmSetBytecodeFile, XmlXvmSetBytecodeBuffer

### 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`.

Syntax

    #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

Returns

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

### 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.

Syntax

    xmlerr XmlXvmSetOutputDom(
       xmlxvm *vm,
       xmldocnode *doc);

Parameter | In/Out | Description
--- | --- | ---
    vm
    IN
| VM object
    doc
    IN
| empty document

Returns

`(xmlerr)` error code

### 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).

Syntax

    xmlerr XmlXvmSetOutputEncoding(
       xmlxvm *vm,
       oratext *encoding);

Parameter | In/Out | Description
--- | --- | ---
    vm
    IN
| VM object
    encoding
    IN
| ``output encoding

Returns

`(xmlerr)` error code.

### 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.

Syntax

    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

Returns

`(xmlerr)` error code

### 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.

Syntax

    xmlerr XmlXvmSetOutputStream(
       xmlxvm *vm,
       xmlostream *ostream);

Parameter | In/Out | Description
--- | --- | ---
    vm
    IN
| VM object
    ostream
    IN
| stream object

Returns

`(xmlerr)` error code.

### 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.

Syntax

    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

Returns

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

### XmlXvmTransformBuffer

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

Syntax

    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

Returns

`(xmlerr)` error code.

See Also: XmlXvmTransformFile, XmlXvmTransformURI, XmlXvmTransformDom

### XmlXvmTransformDom

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

Syntax

    xmlerr XmlXvmTransformDom(
       xmlxvm *vm,
       xmldocnode *root);

Parameter | In/Out | Description
--- | --- | ---
    vm
    IN
| VM object
    root
    IN
| root element of XML document's DOM

Returns

`(xmlerr)` error code.

See Also: XmlXvmTransformFile, XmlXvmTransformURI, XmlXvmTransformBuffer

### XmlXvmTransformFile

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

Syntax

    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

Returns

`(xmlerr)` error code

See Also: XmlXvmTransformURI, XmlXvmTransformBuffer, XmlXvmTransformDom

### XmlXvmTransformURI

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

Syntax

    xmlerr XmlXvmTransformURI(
       xmlxvm *vm,
       oratext *uri);

Parameter | In/Out | Description
--- | --- | ---
    vm
    IN
| VM object
    uri
    IN
| URI of XML document to transform

Returns

`(xmlerr)` error code.

See Also: XmlXvmTransformFile, XmlXvmTransformBuffer, XmlXvmTransformDom