Executing the Transformation PreviousNext

To actually perform the transformation, you need to perform one or more actions.

Selecting XML source data

This step is optional, but if you omit it, then you must name the initial template.

Create an XM_XSLT_URI_SOURCE, passing it the SYSTEM id of your XML text data, as an absolute URI.

If your data source is not XML text, i.e. it is not in a form which an XML parser would recognize, then you will have to create some other descendant of XM_XSLT_SOURCE.

Naming the initial mode

Normally the transformation will start executing in the default mode. If you wish to start the transformation in some other mode, then pass the name of that mode (as an expanded QName, that is, an optional namespace-URI, followed by #, followed by a local name with no intervening space) to set_initial_mode.

Naming the initial template

If you supply XML source data to the transformation, then the initial template will normally be found by matching on the initial context item, that is, the document element of the source data, using the initial mode.

If you do not supply any XML source data, or if you wish to override the normal choice for an initial template, then pass the name of that template (as an expanded QName, that is, an optional namespace-URI followed by #, followed by a local name with no intervening space) to set_initial_template.

Naming the initial context node

If you supply a source document to the transformation, then the initial context node will be chosen as the document node of that document. If you wish another node in the document to be chosen as the initial context node, then call set_initial_context on the transformer, passing the text of an XPath expression to the routine call.

Setting Global Parameters

If your stylesheet has any top-level <xsl:param>s, then you may well wish to set values for them (if any of the parameters are required, then this step is mandatory).

There are three features provided to set the value of a parameter. If, as is common, you wish to supply a string value (type xs:string), then you can call set_string_parameter. This takes two STRINGs as arguments. The first is the name of the parameter, and the second is the value you wish to set.

In the general case, you may pass an XPath expression as the value for a parameter. In this case you call set_xpath_parameter. The arguments are the same as for set_string_parameter, but in this case the value is interpreted as an XPath expression, not a literal string value.

The XPath expression is parsed using the xsl:stylesheet/xsl:transform element of the principal stylesheet module for a static context (so if your XPath expression contains prefixed QNames, then the namespaces will be resolved using the bindings in scope on that element).

The XPath expression is evaluated using a dynamic context based on the document element of the XML source data file, if present.

Finally, you may already have an XPath value (or a node, which can be treated as an XPath value by wrapping it in an XM_XPATH_SINGLETON_NODE object). In this case you can call set_value_parameter.

Defining the output destination

You must define the destination for the output from the transformation. To do this, create an XM_XSLT_TRANSFORMATION_RESULT.

Running the transformation

At this point, all that remains to be done is to call transform. You pass the XM_XSLT_SOURCE representing the XML source data as the first parameter (or Void if you have not supplied any), and the XM_XSLT_TRANSFORMATION_RESULT you defined for the output destination as the second parameter.

Copyright 2004, Colin Adams and others
Last Updated: Sunday, October 31st, 2004