XSLT and XPath function reference in alphabetical order

(Excerpt from “XSLT 2.0 & XPath 2.0” by Frank Bongers, chapter 5, translated from German)

A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P | Q | R | S | T | U | V | W | X | Y | Z

fn:error

Category:

Error messages and debugging

Origin:

XPath 2.0

Return value:

None. The function accepts up to three arguments and reports errors to the system environment. However, under no circumstances does it return a value to the location of the call.

Call/Arguments:

fn:error($errorCode?, $description?, $error-object*)

$errorCode:

Optional. As first argument the function accepts a xs:QName QName which indicates the error to be reported.

$description:

Optional. A description of the error as plain text of xs:string type. This description can be passed on to the application environment.

$error-object:

Optional. A series of an unlimited number of items which are used for the further error documentation in addition to the then required second argument $description (for example, with the help of XPath expressions, the values causing the error can be outputted).

Purpose of use:

The behaviour of the fn:error() function may vary by means of the environment within which it is applied (XPath, XQuery, XSLT). However, basically applies that when the function is called up, it does not return a return value (also not the empty sequence!) to the location of the call. But it can send an error message to the system environment via the standard output.

The function exists with different signatures and can therefore be called up optionally with zero up to three arguments. However, the signatures with two or three arguments require for the first argument at least the passing on of an empty sequence.

In order to illustrate the absence of a return value, the formal-semantic type none has been introduced for the description of the function signature. This type is formally considered as a »subtype derived from each type«, which means it does not cause in any context a static type error. As a consequence, the fn:error() function can be used in any context.

Example 1 – calling fn:error() without arguments:

fn:error()

The call without argument corresponds to the passing on of the QName which indicates the error code err:FOER0000, which means an error (explicitly caused by the user), an »unidentified error«. Since the namespace of the err prefix corresponds to the 

www.w3.org/2005/xqt-errors

string, the function passes on to the system environment a 

www.w3.org/2005/xqt-errors

 URI string (added by the fragment identifier) or directly the err:FOER0000 QName indicating the error.

Example 2 – calling fn:error() with one argument:

fn:error( fn:QName( 'http://www.w3.org/2005/xqt-errors',

'err:FOER0000'

)

)

If a single argument is passed on, it has to be a QName. In this example, this is enforced by the fn:QName() function which generates the QName from its two string arguments. The example correponds in the effect to the call without arguments.

Example 3 – calling fn:error() with two arguments:

fn:error( (), 'Not a chance!')

It is formally not permitted to pass on a character string (for instance as individual description of an user-generated error) to the function without, at the same time, also providing a QName as first argument. Attention: – In earlier versions of XPath 2.0 this was different. Therefore, individual applications might still support a string argument. However, in principle this is not correct. As first argument, however, as in the example, the empty sequence may appear. In this case, the function issues the same error code as when calling without argument, which means err:FOER0000, and additionally the character string of the second argument to the environment.

Example 4 – calling fn:error() with three non-empty arguments:

fn:error( xs:QName('error:err0815'),

"Value outside the scope: ",

fn:string($value) )

Here, the function has three arguments from whom the first is an error code. Note that the error prefix has to be bound to a namspace which indicates the error messages of the system environment. Arguments two and three explain the error indicated by the first argument and output the value in question to the system environment.

Example 5 – calling fn:error() in a XPath expression:

if ($input=0)

then fn:error( (),

'argument is zero'

)

else (1 div $input)

The function can be used within a XPath expression in order to report an error in case an undesired variable value appears. Here, the division by 0 is prevented which would otherwise result in the value INF which, however, would actually be no error.

Function definition:

XPath 1.0:

The function is not available.

XPath 2.0:

fn:error() as none

fn:error($error as xs:QName) as none

fn:error($error as xs:QName?,

$description as xs:string) as none

fn:error($error as xs:QName?,

$description as xs:string,

$error-object as item()*) as none

The none type – a formal-semantic type
The none type is an own, formal type defined in the semantics specification for XQuery and XPath (XQuery 1.0 and XPath 2.0 Formal Semantics). However, this type is not really available for the user, but only used in this definition to make clear that the function has no return value at all – also not the empty sequence!

   

<< back

next >>