saxon:catch

This instruction is always used together with saxon:try. It is used to catch dynamic errors occurring within a saxon:try instruction, and to return an alternative result when an error occurs.

The parent instruction must be saxon:try. A saxon:try element must have at least one saxon:catch child element (there may be several), and the saxon:catch children must come last, except perhaps for any xsl:fallback children.

There is a mandatory attribute errors defining which errors are caught. Every error code is identified by a QName. The attribute is a whitespace-separated list of NameTests which are used to match this QName. Each NameTest may be in the form * (match all names), *:local (match local within any namespace), err:* (match all names in namespace err, or err:ABCD9867 (match a specific error code). The most common namespace, used by all system-defined errors, is http://www.w3.org/2005/xqt-errors, for which the conventional prefix is err:.

The value to be returned by the saxon:catch element may be calculated in an XPath expression in the select attribute, or in instructions forming the body of the saxon:catch element.

Within the select expression, or within the body of the saxon:catch element, the following variables are available. The namespace prefix err in this names must be bound to the namespace URI http://www.w3.org/2005/xqt-errors.

Variable

Type

Value

err:code

xs:QName

The error code

err:description

xs:string

A description of the error condition

err:value

item()*

Value associated with the error. For an error raised by calling the error function, this is the value of the third argument (if supplied). For an error raised by evaluating xsl:message with terminate="yes", this is the document node at the root of the tree containing the XML message body.

err:module

xs:string?

The URI (or system ID) of the stylesheet module containing the instruction where the error occurred; an empty sequence if the information is not available.

err:line-number

xs:integer?

The line number within the stylesheet module of the instruction where the error occurred; an empty sequence if the information is not available.

err:column-number

xs:integer?

The column number within the stylesheet module of the instruction where the error occurred; an empty sequence if the information is not available.

The catch block can throw a new error by calling the error() function.

Variables declared within the saxon:try block are not visible within the saxon:catch block.

For examples, see saxon:try.