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.
Calling the fn:error
function raises an application-defined error.
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 |
This function is ·nondeterministic·, ·context-independent·, and ·focus-independent·.
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·.
This function always raises a dynamic error. By default, it raises [err:FOER0000]
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.
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.)
Provides an execution trace intended to be used in debugging queries.
fn:trace ( |
||
$value |
as item()* |
|
) as item()* |
fn:trace ( |
||
$value |
as item()* , |
|
$label |
as xs:string |
|
) as item()* |
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
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·.
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)
.
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.
Returns implementation-dependent information about the current state of execution.
fn:stack-trace () as xs:string |
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.
The function will typically be called to assist in diagnosing dynamic errors.