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
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 receiver if you want it handled differently. This must
be a class that implements the Receiver interface. The content of
the message is in general an XML fragment. You can supply the
Receiver using the
-m option on the command line,
setMessageEmitter() method of the Controller class.
The sequence of calls to this
Receiver is as follows: there is a
open() call at the start of the transformation, and a single
close() call at the end; and each evaluation of an
xsl:message instruction starts with a
startDocument() call and ends with
startDocument() event has a
terminate="yes" was specified, and the
locationId on calls such as
characters() can be used to identify the location in the
stylesheet where the message data originated (this is achieved by passing the
locationId in a call to
getLineNumber() on the same object).
From Saxon 9.8, if the
xsl:message instruction defines an error code,
this code will be notified to the
Receiver by means of a processing instruction
event. The name of the processing-instruction is
error-code; the string value
is the error code as an
processingInstruction() event occurs
immediately after the
Select the class MessageWarner to have
xsl:message output notified to the
ErrorListener, as described in the JAXP documentation.