XSLT and XPath function reference in alphabetical order

(Excerpt from “XSLT 2.0 & XPath 2.0” by Frank Bongers, chapter 5, translated from German)

A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P | Q | R | S | T | U | V | W | X | Y | Z

fn:trace

Category:

Error messages and debugging

Origin:

XPath 2.0

Return value:

The input sequence in unchanged form.

Call/Arguments:

fn:trace($inputSequence, $label)

$inputSequence:

An input sequence of any number of items of any type which are passed on unchanged by the function, after it has executed its log function. The empty sequence is permitted.

$label:

Obligatory. A xs:string string which is added in connection with the input values to the log generated by the function.

Purpose of use:

The fn:trace() function is intended as a help for debugging purposes. For example, it can be interposed in the context of the call of another function in order to record during the runtime of the stylesheet (tracing) which values the function actually receives during the call.

Firstly, the fn:trace() function takes over the input values intended for the other function, writes it with a corresponding comment label in a log file and then passes it unchanged to the monitored function:

fn:exampleFunction(

fn:trace($inputValues, 'comment')

)

Since fn:trace() passes on the input values in a transparent way, this corresponds to:

fn:exampleFunction($inputValues)

With several instances of the fn:trace() function, different points of the stylesheet can be monitored at runtime. Since all instances write into the same log file, the $label comment labels have to be suitably selected in order to be able to assign the records accordingly.

In which way the log file is executed and where it is stored, is left to the respective implementation, as well as the order in which the calls of fn:trace() are recorded in it.

The XSLT processor Saxon writes the log in System.err per default. However, a redirecting into another file is possible by a command line command. The values of the input sequence are recorded in string form in case they are atomic values, and in the form of XPath expressions in case they are nodes. An empty input sequence is recorded by the »empty sequence« string.

The implementation of debugging possibilities depends on the manufacturer
It is to be expected that, besides or as an alternative to fn:trace(), also proprietary debugging processes will be provided in the implementations of different manufacturers. These may be, under certain circumstances, more powerful or easier to configure – it should be considered in the individual case, whether these are to be preferred to the standard debugging method.

Function definition:

XPath 1.0:

The function is not available.

XPath 2.0:

fn:trace($value as item()*,

$label as xs:string) as item()*

   

<< back

next >>