[Exist-commits] SF.net SVN: exist: [3726] trunk/eXist-1.0/webapp/update_ext.xml

[<wol...@us...>]

Revision: 3726
Author:   wolfgang_m
Date:     2006-06-24 14:45:08 -0700 (Sat, 24 Jun 2006)
ViewCVS:  http://svn.sourceforge.net/exist/?rev=3726&view=rev

Log Message:
-----------
Added a warning that XQuery update expressions will only have an effect on persistent documents, not on
temporary in-memory fragments.

Modified Paths:
--------------
    trunk/eXist-1.0/webapp/update_ext.xml
Modified: trunk/eXist-1.0/webapp/update_ext.xml
===================================================================
--- trunk/eXist-1.0/webapp/update_ext.xml	2006-06-24 21:25:57 UTC (rev 3725)
+++ trunk/eXist-1.0/webapp/update_ext.xml	2006-06-24 21:45:08 UTC (rev 3726)
@@ -26,6 +26,21 @@
             XUpdate instructions to a corresponding XQuery expression. Until the
             W3C working group starts its work on an official update 
             specification, the basic syntax follows the proposal by Patrick Lehti.</para>
+        <important>
+            <para>The XQuery update extension has been designed to simplify updates on 
+                <emphasis>persistent</emphasis> documents stored in the database. However, it is 
+                not suitable for updating temporary document fragments constructed within the XQuery, 
+                i.e. you can't use it to modify the results returned by a query. For example, the following
+                query has no visible effect because it operates on an in-memory fragment:
+            </para>
+            
+            <synopsis><![CDATA[let $doc := <root><a/></root>
+return (update insert <b/> into $doc/a, $doc)]]></synopsis>
+            
+            <para>The query just ignores the update and returns the constructed root element (it would 
+                probably be less confusing if the query would just throw an exception. We may have to change 
+                that ...)</para>
+        </important>
         <para>All update statements start with the keyword "update", followed by
             an update action. Available actions are: "insert", "delete", "replace", 
             "value" and "rename". The return type of the expression is <option>empty()</option>.
@@ -63,6 +78,7 @@
             {$address/city, $address/email}
         </address>]]></programlisting>
         </example>
+        
         <section>
             <title>Insert</title>
             <synopsis>update insert expr ( into | following | preceding )


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.