Causes a message to be displayed.
Permitted parent elements: any XSLT element whose content model is sequence-constructor; any literal result element
The content of the message may be specified
using either or both of the
If the value is set to
New in XSLT 3.0. Specifies the error
code associated with the message. The effective value should be an EQName. The
If the value is set
Available in XSLT 1.0 and later versions. Available in all Saxon editions. Available for all platforms.
Notes on the Saxon implementation
The Saxon optimizer attempts to ensure, as far as possible, that calls to
behave in a predictable way: for example a call on
xsl:message within a loop will not be
lifted out of the loop. However, this doesn't work at a distance: if a function calls
and the function is called within a predicate, it is unpredictable how often the function will be called, and
therefore how many messages will be produced.
From Saxon 9.5 the new feature of text value templates is implemented,
which is particularly useful with
xsl:message. For example:
expand-text="yes" can appear on any ancestor element
to enable the feature.
Saxon 9.8 includes a new extension function saxon:message-count() which can be used to count the number of messages that have been issued, either overall or with a specific error code. This can be used, for example, to terminate execution after a certain number of warning conditions have occurred.
By default the message is displayed on the standard error output stream. You can supply your own message handler if you want it handled differently: for details see Message output.
A user-written message handler is called with a
Message object containing
the details of the message. This allows the application to extract:
- The content of the message, as an
- The location of the
xsl:messageinstruction in the stylesheet;
- Any error code that was requested on the
- A boolean value indicating whether
Saxon no longer provides an option to have
xsl:message output notified to the
ErrorListener, as described in the JAXP documentation; but this
can be achieved by writing an appropriate message handler.