Calling the fn:error
function raises an application-defined error.
fn:error
( none
fn:error
( $code
as xs:QName?
none
fn:error
( $code
as xs:QName?
,$description
as xs:string
none
fn:error
( $code
as xs:QName?
,$description
as xs:string
,$error-object
as item()*
none
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.
The expression fn:error()
returns .
The expression fn:error(fn:QName('http://www.example.com/HR', 'myerr:toohighsal'),
'Does not apply because salary is too high')
returns .
This function always raises a dynamic error. By default, it raises
The value of the $description
parameter may need to be localized.
The type none is a special type defined in 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.