xsl:message

Causes a message to be displayed.

Category: instruction
Content: sequence-constructor
Permitted parent elements: any XSLT element whose content model is sequence-constructor; any literal result element

Attributes

`select?`	`expression`	The content of the message may be specified using either or both of the `select` attribute and the enclosed sequence constructor. If a `select` attribute is used, then the value must be an XPath expression, and the effect is the same as if a single `xsl:copy-of` element with this `select` attribute were added to the start of the sequence constructor.
`terminate?`	`{ boolean }`	If the value is set to `yes`, processing of the stylesheet is terminated after issuing the message. The default is `no`. This attribute may be supplied as an attribute value template.
`error-code?`	`{ eqname }`	New in XSLT 3.0. Specifies the error code associated with the message. The effective value should be an EQName. The default is `Q{http://www.w3.org/2005/xqt-errors}XTMM9000`.
`saxon:time?`	`boolean`	If the value is set to `yes`, a timestamp is added at the start of the message. The default is `no`. Requires Saxon-PE or Saxon-EE. For details see saxon:time.

Saxon availability

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 xsl:message 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 xsl:message 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:

<xsl:message expand-text="yes">Id: {@id} Age: {@age} Status: {@status}</xsl:message>

The attribute 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.

Details

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 XdmNode;
The location of the xsl:message instruction in the stylesheet;
Any error code that was requested on the xsl:message instruction;
A boolean value indicating whether terminate="yes" was requested.

Saxon no longer provides an option to have xsl:message output notified to the JAXP ErrorListener, as described in the JAXP documentation; but this can be achieved by writing an appropriate message handler.

Links to W3C specifications

XSLT 3.0 Specification