fn: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 [ERRFOER0000]

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