XPath/XQuery trace function

Summary

Provides an execution trace intended to be used in debugging queries.

Signatures

fn:trace(
$value as item()*
) as item()*
fn:trace(
$value as item()*,
$label as xs:string
) as item()*

Properties

This function is deterministic, context-independent, and focus-independent.

Rules

The function returns the value of $value, unchanged.

In addition, the values of $value, converted to an xs:string, and $label (if supplied) may be directed to a trace data set. The destination of the trace output is implementation-defined. The format of the trace output is implementation-dependent. The ordering of output from calls of the fn:trace function is implementation-dependent.

Examples

Consider a situation in which a user wants to investigate the actual value passed to a function. Assume that in a particular execution, $v is an xs:decimal with value 124.84. Writing fn:trace($v, 'the value of $v is:') will put the strings "124.84" and "the value of $v is:" in the trace data set in implementation dependent order.

Notes

Sometimes there is a need to output trace information unrelated to a specific value. In such cases it can be useful to set $value to an empty string or an empty sequence, and to compute the value of the $label argument: fn:trace((), "Processing item " || $i).