saxonica.com

saxon:result-document()

This function is available only in Saxon-EE

saxon:result-document($href as xs:string, $content as item()*, $format as element(xsl:output))

This function takes three arguments:

  1. $href is a URI identifying the destination of the serialized result document. Generally speaking, the file:/ URI scheme works and other schemes usually don't. If the URI is relative, it is interpreted relative to the base output URI which is the destination of the principal output of the query, and which defaults to the current directory (not the stylesheet directory). When the -t option is used on the command line, the actual destination of output files is reported as a message on System.err.

  2. $content is a sequence of items which makes up the content of the new document, it is processed in the same way as the content sequence passed to the document{} constructor in XQuery, or the xsl:document instruction in XSLT.

  3. $format is used to define serialization properties; its value is an xsl:output element conforming to the rules defined in the XSLT specification. This element may be constructed dynamically, and may therefore be used to decide all the serialization properties dynamically.

For example, the function may be used as follows in XQuery. This example has the effect of writing each <country> element to a separate file: 


declare namespace saxon="http://saxon.sf.net/";
declare namespace xsl="http://www.w3.org/1999/XSL/Transform";
let $input :=
  <data>
    <country name="Austria">Vienna</country>
    <country name="France">Paris</country>
    <country name="Germany">Berlin</country>
  </data>
return
<log> {
  for $c in $input/country return
    let $href := concat($c/@name, '.xml')
    return (
      saxon:result-document($href, $c, 
          <xsl:output method="xml" indent="yes"/>),
      <done href="{$href}"/>
    )
} </log>    
}</out>

The function returns no result (technically, it returns an empty sequence). Because it is called only for its side-effects, some care is needed in how it is used. Generally, the safe approach is to call it in a position where, if it did produce output, the output would form part of the result of the query. It is implemented internally using the xsl:result-document instruction from XSLT, and must follow the same constraints. For example, an error will be reported if it is called while evaluating a variable or a function, or if you try to write and read the same document within a single query.

Next