3 Errors and diagnostics

3.1 Raising errors

In this document, as well as in [XQuery 4.1: An XML Query Language] and [XML Path Language (XPath) 4.0], the phrase "an error is raised" is used. Raising an error is equivalent to calling the fn:error function defined in this section with the provided error code. Except where otherwise specified, errors defined in this specification are dynamic errors. Some errors, however, are classified as type errors. Type errors are typically used where the presence of the error can be inferred from knowledge of the type of the actual arguments to a function, for example with a call such as fn:string(fn:abs#1). Host languages may allow type errors to be reported statically if they are discovered during static analysis.

When function specifications indicate that an error is to be raised, the notation "[error code]". os used to specify an error code. Each error defined in this document is identified by an xs:QName that is in the http://www.w3.org/2005/xqt-errors namespace, represented in this document by the err prefix. It is this xs:QName that is actually passed as an argument to the fn:error function. Calling this function raises an error. For a more detailed treatment of error handing, see Section 2.3.3 Handling Dynamic Errors XP31.

The fn:error function is a general function that may be called as above but may also be called from [XQuery 4.1: An XML Query Language] or [XML Path Language (XPath) 4.0] applications with, for example, an xs:QName argument.

3.1.1 fn:error

Summary

Calling the fn:error function raises an application-defined error.

Signatures
fn:error() as none
fn:error(
$code as xs:QName?
) as none
fn:error(
$code as xs:QName?,
$description as xs:string
) as none
fn:error(
$code as xs:QName?,
$description as xs:string,
$error-object as item()* := .
) as none
Properties

This function is ·nondeterministic·, ·context-independent·, and ·focus-independent·.

Rules

This function never returns a value. Instead it always raises an error. The effect of the error is identical to the effect of dynamic errors raised implicitly, for example when an incorrect argument is supplied to a function.

The parameters to the fn:error function supply information that is associated with the error condition and that is made available to a caller that asks for information about the error. The error may be caught either by the host language (using a try/catch construct in XSLT or XQuery, for example), or by the calling application or external processing environment. The way in which error information is returned to the external processing environment is ·implementation-dependent·.

There are three pieces of information that may be associated with an error:

  • The $code is an error code that distinguishes this error from others. It is an xs:QName; the namespace URI conventionally identifies the component, subsystem, or authority responsible for defining the meaning of the error code, while the local part identifies the specific error condition. The namespace URI http://www.w3.org/2005/xqt-errors is used for errors defined in this specification; other namespace URIs may be used for errors defined by the application.

    If the external processing environment expects the error code to be returned as a URI or a string rather than as an xs:QName, then an error code with namespace URI NS and local part LP will be returned in the form NS#LP. The namespace URI part of the error code should therefore not include a fragment identifier.

    If no value is supplied for the $code argument (that is, if the function is called with no arguments or if the first argument is an empty sequence), the effective value of the error code is fn:QName('http://www.w3.org/2005/xqt-errors', 'err:FOER0000').

  • The $description is a natural-language description of the error condition.

    If no value is supplied for the $description argument (that is, if the function is called with less than two arguments), then the effective value of the description is ·implementation-dependent·.

  • The $error-object is an arbitrary value used to convey additional information about the error, and may be used in any way the application chooses.

    If no value is supplied for the $error-object argument (that is, if the function is called with less than three arguments), then the effective value of the error object is ·implementation-dependent·.

Error Conditions

This function always raises a dynamic error. By default, it raises [err:FOER0000]

Notes

The value of the $description parameter may need to be localized.

The type "none" is a special type defined in [XQuery 1.0 and XPath 2.0 Formal Semantics] and is not available to the user. It indicates that the function never returns and ensures that it has the correct static type.

Any QName may be used as an error code; there are no reserved names or namespaces. The error is always classified as a dynamic error, even if the error code used is one that is normally used for static errors or type errors.

Examples

The expression fn:error() raises error FOER0000. (This returns the URI http://www.w3.org/2005/xqt-errors#FOER0000 (or the corresponding xs:QName) to the external processing environment, unless the error is caught using a try/catch construct in the host language.)

The expression fn:error(fn:QName('http://www.example.com/HR', 'myerr:toohighsal'), 'Does not apply because salary is too high') raises error myerr:toohighsal. (This returns http://www.example.com/HR#toohighsal and the xs:string "Does not apply because salary is too high" (or the corresponding xs:QName) to the external processing environment, unless the error is caught using a try/catch construct in the host language.)

3.2 Diagnostic tracing

3.2.1 fn:trace

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 $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·.

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

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.

3.2.2 fn:stack-trace

Summary

Returns implementation-dependent information about the current state of execution.

Signature
fn:stack-trace() as xs:string
Rules

The result of the function is an implementation-dependent string containing diagnostic information about the current state of execution.

The function is non-deterministic: multiple calls will typically produce different results.

Notes

The function will typically be called to assist in diagnosing dynamic errors.