<?xml version="1.0" encoding="iso-8859-1"?>
<?xml-stylesheet href="../make-menu.xsl" type="text/xsl"?><html>
   <head>
      <this-is section="using-xquery" page="update" subpage=""/>
      <!--
           Generated at 2011-12-09T20:47:22.916Z--><title>Saxonica: XSLT and XQuery Processing: Using XQuery Update</title>
      <meta name="coverage" content="Worldwide"/>
      <meta name="copyright" content="Copyright Saxonica Ltd"/>
      <meta name="title"
            content="Saxonica: XSLT and XQuery Processing: Using XQuery Update"/>
      <meta name="robots" content="noindex,nofollow"/>
      <link rel="stylesheet" href="../saxondocs.css" type="text/css"/>
   </head>
   <body class="main">
      <h1>Using XQuery Update</h1>
      <p>Saxon-EE supports use of the update extensions to XQuery defined in
<a href="http://www.w3.org/TR/xquery-update-10/" class="bodylink">http://www.w3.org/TR/xquery-update-10/</a>. The
current version supported is the Candidate Recommendation.</p>
      <p>Update is available only in Saxon-EE, and is supported only if explicitly requested. The command line
has an option <code>update:on</code> for this purpose, and all the XQuery APIs have an option to enable
updating, which must be set before compiling the query. If this option is not set, the parser will not recognize
update syntax, and any use of updating expressions will trigger a syntax error.</p>
      <p>It is possible for an update to modify the document supplied as the context item, or a document
read using the <code>doc()</code> or <code>collection()</code> function, or even a document constructed
dynamically by the query itself. When using the various APIs, the general policy is that updated documents
are never written automatically to disk. Instead, the list of updated documents is available to the application
on completion of the query, and the application can decide whether to save the documents to their original
location, or to some other location. Documents that were originally read from disk will have a document URI property
which can be used to decide where to write them back.</p>
      <p>When using XQuery Update from the command line, updated documents will be written back to disk if they
have a known document URI, and if that URI is an updatable location (which in practice means it must be a URI
that uses the <code>file://</code> scheme). For testing purposes, the write-back can be suppressed by using
<code>-update:discard</code>. There is also a <code>-backup</code> option to control whether the old file is
saved under a different name before being overwritten.</p>
      <div class="boxed"
           style="border: solid thin; background-color: #B1CCC7; padding: 2px">Saxon does no locking to prevent multiple threads attempting to update the same document. This is entirely
a user responsibility.</div>
      <p>Most errors that can arise during updating operations (for example, inserting two conflicting attributes) will cause
an exception, with the supplied input document in memory being left in its original state. However, errors detected
during the validation phase (that is, when the updated document is invalid against the schema, assuming revalidation
is requested) are non-recoverable; after such a failure, the state of the document is unpredictable. Generally the (invalid)
updates will have been made, and some of the updates done during schema validation (setting type annotations and default
values) may also have been made.</p>
      <p>Note that updates to a document will fail unless it is implemented using the <b>Linked Tree</b> model.
This can be selected from the command line using <code>-tree:linked</code>, or via configuration settings 
in the API. It is not at present possible to update the Tiny Tree, nor external object models such as DOM, JDOM, or XOM.</p>
      <table width="100%">
         <tr>
            <td>
               <p align="right"><a class="nav" href="callingfunctions.xml">Next</a></p>
            </td>
         </tr>
      </table>
   </body>
</html>