<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
<head profile="http://internetalchemy.org/2003/02/profile">
<link rel="foaf" type="application/rdf+xml" title="FOAF" href="http://www.openlinksw.com/dataspace/uda/about.rdf" />
<link rel="schema.dc" href="http://purl.org/dc/elements/1.1/" />
<meta name="dc.title" content="Function: XMLUpdate - Virtuoso Functions Guide" />
<meta name="dc.subject" content="Function: XMLUpdate - Virtuoso Functions Guide" />
<meta name="dc.creator" content="OpenLink Software Documentation Team ; " />
<meta name="dc.copyright" content="OpenLink Software, 1999 - 2009" />
<link rel="top" href="index.html" title="OpenLink Virtuoso Universal Server: Documentation" />
<link rel="search" href="/doc/adv_search.vspx" title="Search OpenLink Virtuoso Universal Server: Documentation" />
<link rel="parent" href="functions.html" title="Chapter Contents" />
<link rel="prev" href="appendixa.html" title="Appendix" />
<link rel="next" href="functions.html#.html" title="" />
<link rel="shortcut icon" href="../images/misc/favicon.ico" type="image/x-icon" />
<link rel="stylesheet" type="text/css" href="doc.css" />
<link rel="stylesheet" type="text/css" href="/doc/translation.css" />
<title>Function: XMLUpdate - Virtuoso Functions Guide</title>
<meta http-equiv="Content-Type" content="text/xhtml; charset=UTF-8" />
<meta name="author" content="OpenLink Software Documentation Team ; " />
<meta name="copyright" content="OpenLink Software, 1999 - 2009" />
<meta name="keywords" content="" />
<meta name="GENERATOR" content="OpenLink XSLT Team" />
</head>
<body>
<div id="header">
<a name="fn_XMLUpdate" />
<img src="../images/misc/logo.jpg" alt="" />
<h1>22. Virtuoso Functions Guide - XMLUpdate</h1>
</div>
<div id="navbartop">
<div>
<a class="link" href="functions.html">Chapter Contents</a> | <a class="link" href="fn_xmlsql_update.html" title="xmlsql_update">Prev</a> | <a class="link" href="fn_xpath_eval.html" title="xpath_eval">Next</a>
</div>
</div>
<div id="currenttoc">
<form method="post" action="/doc/adv_search.vspx">
<div class="search">Keyword Search: <br />
<input type="text" name="q" /> <input type="submit" name="go" value="Go" />
</div>
</form>
<div>
<a href="http://www.openlinksw.com/">www.openlinksw.com</a>
</div>
<div>
<a href="http://docs.openlinksw.com/">docs.openlinksw.com</a>
</div>
<br />
<div>
<a href="index.html">Book Home</a>
</div>
<br />
<div>
<a href="contents.html">Contents</a>
</div>
<div>
<a href="preface.html">Preface</a>
</div>
<br />
<div>
<a class="selected" href="functions.html">Virtuoso Functions Guide</a>
</div>
<br />
<div>
<a href="functions.html#admin">Administration</a>
</div>
<div>
<a href="functions.html#aggr">Aggregate Functions</a>
</div>
<div>
<a href="functions.html#array">Array Manipulation</a>
</div>
<div>
<a href="functions.html#bpel">BPEL APIs</a>
</div>
<div>
<a href="functions.html#backup">Backup</a>
</div>
<div>
<a href="functions.html#compression">Compression</a>
</div>
<div>
<a href="functions.html#cursors">Cursor</a>
</div>
<div>
<a href="functions.html#time">Date & Time Manipulation</a>
</div>
<div>
<a href="functions.html#debug">Debug</a>
</div>
<div>
<a href="functions.html#dict">Dictionary Manipulation</a>
</div>
<div>
<a href="functions.html#encoding">Encoding & Decoding</a>
</div>
<div>
<a href="functions.html#file">File Manipulation</a>
</div>
<div>
<a href="functions.html#ft">Free Text</a>
</div>
<div>
<a href="functions.html#hash">Hashing / Cryptographic</a>
</div>
<div>
<a href="functions.html#ldap">LDAP</a>
</div>
<div>
<a href="functions.html#localization">Locale</a>
</div>
<div>
<a href="functions.html#mail">Mail</a>
</div>
<div>
<a href="functions.html#misc">Miscellaneous</a>
</div>
<div>
<a href="functions.html#number">Number</a>
</div>
<div>
<a href="functions.html#phrz">Phrases</a>
</div>
<div>
<a href="functions.html#rdf">RDF data</a>
</div>
<div>
<a href="functions.html#rmt">Remote SQL Data Source</a>
</div>
<div>
<a href="functions.html#repl">Replication</a>
</div>
<div>
<a href="functions.html#soap">SOAP</a>
</div>
<div>
<a href="functions.html#sql">SQL</a>
</div>
<div>
<a href="functions.html#string">String</a>
</div>
<div>
<a href="functions.html#txn">Transaction</a>
</div>
<div>
<a href="functions.html#type">Type Mapping</a>
</div>
<div>
<a href="functions.html#uddi">UDDI</a>
</div>
<div>
<a href="functions.html#udt">User Defined Types & The CLR</a>
</div>
<div>
<a href="functions.html#vad">VAD</a>
</div>
<div>
<a href="functions.html#jvmpl">Virtuoso Java PL API</a>
</div>
<div>
<a href="functions.html#bif">Virtuoso Server Extension Interface (VSEI)</a>
</div>
<div>
<a href="functions.html#ws">Web & Internet</a>
</div>
<div>
<a class="selected" href="functions.html#xml">XML</a>
</div>
<div class="selected">
<div>
<a href="fn_XMLAGG.html">xmlagg</a>
</div>
<div>
<a href="fn_XMLATTRIBUTES.html">xmlattributes</a>
</div>
<div>
<a href="fn_XMLAddAttribute.html">xmladdattribute</a>
</div>
<div>
<a href="fn_XMLAppendChildren.html">xmlappendchildren</a>
</div>
<div>
<a href="fn_XMLCONCAT.html">xmlconcat</a>
</div>
<div>
<a href="fn_XMLELEMENT.html">xmlelement</a>
</div>
<div>
<a href="fn_XMLFOREST.html">xmlforest</a>
</div>
<div>
<a href="fn_XMLInsertAfter.html">xmlinsertafter</a>
</div>
<div>
<a href="fn_XMLInsertBefore.html">xmlinsertbefore</a>
</div>
<div>
<a href="fn_XMLReplace.html">xmlreplace</a>
</div>
<div>
<a href="fn_XMLType.XMLType.html">xmltype.xmltype</a>
</div>
<div>
<a href="fn_XMLType.createNonSchemaBasedXML.html">xmltype.createnonsch...</a>
</div>
<div>
<a href="fn_XMLType.createSchemaBasedXML.html">xmltype.createschema...</a>
</div>
<div>
<a href="fn_XMLType.createXML.html">xmltype.createxml</a>
</div>
<div>
<a href="fn_XMLType.existsNode.html">xmltype.existsnode</a>
</div>
<div>
<a href="fn_XMLType.extract.html">xmltype.extract</a>
</div>
<div>
<a href="fn_XMLType.getClobVal.html">xmltype.getclobval</a>
</div>
<div>
<a href="fn_XMLType.getNamespace.html">xmltype.getnamespace</a>
</div>
<div>
<a href="fn_XMLType.getNumVal.html">xmltype.getnumval</a>
</div>
<div>
<a href="fn_XMLType.getRootElement.html">xmltype.getrooteleme...</a>
</div>
<div>
<a href="fn_XMLType.getSchemaURL.html">xmltype.getschemaurl</a>
</div>
<div>
<a href="fn_XMLType.getStringVal.html">xmltype.getstringval</a>
</div>
<div>
<a href="fn_XMLType.isFragment.html">xmltype.isfragment</a>
</div>
<div>
<a href="fn_XMLType.isSchemaBased.html">xmltype.isschemabase...</a>
</div>
<div>
<a href="fn_XMLType.isSchemaValid.html">xmltype.isschemavali...</a>
</div>
<div>
<a href="fn_XMLType.isSchemaValidated.html">xmltype.isschemavali...</a>
</div>
<div>
<a href="fn_XMLType.schemaValidate.html">xmltype.schemavalida...</a>
</div>
<div>
<a href="fn_XMLType.setSchemaValidated.html">xmltype.setschemaval...</a>
</div>
<div>
<a href="fn_XMLType.toObject.html">xmltype.toobject</a>
</div>
<div>
<a href="fn_XMLType.transform.html">xmltype.transform</a>
</div>
<div>
<a class="selected" href="fn_XMLUpdate.html">xmlupdate</a>
</div>
<div>
<a href="fn_xper_right_sibling.html">xper navigation</a>
</div>
<div>
<a href="fn_createXML.html">createxml</a>
</div>
<div>
<a href="fn_isentity.html">isentity</a>
</div>
<div>
<a href="fn_serialize_to_UTF8_xml.html">serialize_to_utf8_xm...</a>
</div>
<div>
<a href="fn_tidy_html.html">tidy_html</a>
</div>
<div>
<a href="fn_tidy_list_errors.html">tidy_list_errors</a>
</div>
<div>
<a href="fn_updateXML.html">updatexml</a>
</div>
<div>
<a href="fn_xml_add_system_path.html">xml_add_system_path</a>
</div>
<div>
<a href="fn_xml_auto.html">xml_auto</a>
</div>
<div>
<a href="fn_xml_auto_dtd.html">xml_auto_dtd</a>
</div>
<div>
<a href="fn_xml_auto_schema.html">xml_auto_schema</a>
</div>
<div>
<a href="fn_xml_create_tables_from_mapping_schema_decl.html">xml_create_tables_fr...</a>
</div>
<div>
<a href="fn_xml_cut.html">xml_cut</a>
</div>
<div>
<a href="fn_xml_doc_output_option.html">xml_doc_output_optio...</a>
</div>
<div>
<a href="fn_xml_get_system_paths.html">xml_get_system_paths</a>
</div>
<div>
<a href="fn_xml_load_mapping_schema_decl.html">xml_load_mapping_sch...</a>
</div>
<div>
<a href="fn_xml_load_schema_decl.html">xml_load_schema_decl</a>
</div>
<div>
<a href="fn_xml_namespace_scope.html">xml_namespace_scope</a>
</div>
<div>
<a href="fn_xml_persistent.html">xml_persistent</a>
</div>
<div>
<a href="fn_xml_set_ns_decl.html">xml_set_ns_decl</a>
</div>
<div>
<a href="fn_xml_template.html">xml_template</a>
</div>
<div>
<a href="fn_xml_tree.html">xml_tree</a>
</div>
<div>
<a href="fn_xml_tree_doc.html">xml_tree_doc</a>
</div>
<div>
<a href="fn_xml_tree_doc_media_type.html">xml_tree_doc_media_t...</a>
</div>
<div>
<a href="fn_xml_uri_get.html">xml_uri_get</a>
</div>
<div>
<a href="fn_xml_validate_dtd.html">xml_validate_dtd</a>
</div>
<div>
<a href="fn_xml_validate_schema.html">xml_validate_schema</a>
</div>
<div>
<a href="fn_xml_view_dtd.html">xml_view_dtd</a>
</div>
<div>
<a href="fn_xml_view_schema.html">xml_view_schema</a>
</div>
<div>
<a href="fn_xmlsql_update.html">xmlsql_update</a>
</div>
<div>
<a href="fn_xpath_eval.html">xpath_eval</a>
</div>
<div>
<a href="fn_xper_cut.html">xper_cut</a>
</div>
<div>
<a href="fn_xper_doc.html">xper_doc</a>
</div>
<div>
<a href="fn_xper_locate_words.html">xper_locate_words</a>
</div>
<div>
<a href="fn_xpf_extension.html">xpf_extension</a>
</div>
<div>
<a href="fn_xpf_extension_remove.html">xpf_extension_remove</a>
</div>
<div>
<a href="fn_xquery_eval.html">xquery_eval</a>
</div>
<div>
<a href="fn_xslt.html">xslt</a>
</div>
<div>
<a href="fn_xslt_format_number.html">xslt_format_number</a>
</div>
<div>
<a href="fn_xslt_sheet.html">xslt_sheet</a>
</div>
<div>
<a href="fn_xslt_stale.html">xslt_stale</a>
</div>
<div>
<a href="fn_xte_head.html">xte_head</a>
</div>
<div>
<a href="fn_xte_node.html">xte_node</a>
</div>
<div>
<a href="fn_xte_node_from_nodebld.html">xte_node_from_nodebl...</a>
</div>
<div>
<a href="fn_xte_nodebld_acc.html">xte_nodebld_acc</a>
</div>
<div>
<a href="fn_xte_nodebld_final.html">xte_nodebld_final</a>
</div>
<div>
<a href="fn_xte_nodebld_init.html">xte_nodebld_init</a>
</div>
<div>
<a href="fn_xtree_doc.html">xtree_doc</a>
</div>
</div>
<div>
<a href="functions.html#XPATH">XPATH & XQUERY</a>
</div>
<br />
<div>
<a href="functionidx.html">Functions Index</a>
</div>
<br />
</div>
<div id="text">
<h2>XMLUpdate</h2>
<div class="refpurpose">Create a changed copy of given document by replacing some nodes.</div>
<div class="funcsynopsis">
<span class="funcdef">any <span class="function">XMLUpdate</span>
</span>
(<span class="paramdef">inout <span class="parameter">source</span> any</span>,
<span class="paramdef">in <span class="parameter">path1</span> varchar</span>,
<span class="paramdef">in <span class="parameter">replacement1</span> any</span>,
<span class="paramdef">in <span class="parameter">path2</span> varchar</span>,
<span class="paramdef">in <span class="parameter">replacement2</span> any</span>,
<span class="paramdef">
<span class="parameter">...</span>
</span>,
<span class="paramdef">in <span class="parameter">pathN</span> varchar</span>,
<span class="paramdef">in <span class="parameter">replacementN</span> any</span>);
</div>
<div class="refsect1">
<div class="refsect1title">Description</div>
<p>The function takes of the XML document referenced by
<span class="computeroutput">source</span> XML tree entity, makes a copy of that document;
then it modifies the copy by finding fragments that are values of
<span class="computeroutput">path1</span>, <span class="computeroutput">path2</span>, ..., <span class="computeroutput">pathN</span> XPATH expressions and replacing them with
values specified by <span class="computeroutput">replacement1</span>, <span class="computeroutput">replacement2</span>, ...,<span class="computeroutput">replacementN</span>;
the modified copy is returned as the result of the function call.
</p>
<p>Every <span class="computeroutput">pathI</span> should be a string that is a correct XPATH expression.
Every such expression is evaluated according to the rules for XPATH expressions in XSLT (attribute entities are not cast to their string values).
The context node is <span class="computeroutput">source</span>, context size and position are both equal to 1.
</p>
<p>Every <span class="computeroutput">replacementI</span> may be an XML tree entity, a NULL or a value of some other type that will be converted to varchar before use.
</p>
<p>For simplicity, consider the case when there is only one <span class="computeroutput">path1</span> XPATH expression parameter and only one
<span class="computeroutput">replacement1</span>. First of all, a copy of the document of the <span class="computeroutput">source</span> XML tree entity is created.
Then <span class="computeroutput">path1</span> is evaluated.</p>
<p>If the result of evaluation is not an XML entity then no replacement is made and
the copy of the source document is returned unchanged.
If the result is an XML entity that is not in the source document (e.g. an entity returned by the call of document(...) function.)
then no replacement is made either.
</p>
<p>
If the result of evaluation is an XML entity in the source document then the function finds a node in the copied document that is a copy of
the node in the source that is returned by XPATH evaluation. This node in the copied document will be referred to as a "highlighted" node.
</p>
<p>
If the result of evaluation is an attribute entity then the value of the attribute in the highlighted node is changed.
If <span class="computeroutput">replacement1</span> is NULL then the attribute is removed at all, otherwise its value is set to the string value of
the <span class="computeroutput">replacement1</span>.
</p>
<p>
If the result of evaluation is not an attribute entity but a entity then the highlighted node is replaced with the value of <span class="computeroutput">replacement1</span>.
The method of replacement depends on the type of the replacement value.
If <span class="computeroutput">replacement1</span> is NULL then the highlighted node is simply removed from the result; if the node is the root or a
single child of the root then function immediately returns NULL instead of an XML entity (because XML document can not be totally empty),
otherwise the parent of the highlighted node will simply have one child less.
If <span class="computeroutput">replacement1</span> is an non-empty string then the highlighted node is
replaced with a new text node whose string value is equal to <span class="computeroutput">replacement1</span>.
If <span class="computeroutput">replacement1</span> is an empty string then the effect is exactly the same as in case of NULL because the string value of a text node can not be empty.
If <span class="computeroutput">replacement1</span> is an XML entity that is a root entity of some document then the highlighted node is replaced with a sequence of copies of all children of that root.
If <span class="computeroutput">replacement1</span> is an XML entity of some other sort (XML element, text, comment etc.) then the that is not a root entity of some document then the highlighted node is replaced with a sequence of copies of all children of that root.
</p>
<p>
After editing the copied document, some normalization may happen. The modified document may contain adjacent text nodes; every sequence of such nodes
is replaced with one text node whose string value is a concatenation of string values of that nodes. E.g. if the highlighted node is an element <a/>
that resides between two text nodes "text1" and "text2" and the highlighted node is removed, then these text nodes become neighbors;
normalization will replace them with a single text node "text1text2"
</p>
<p>
Now consider the case of more than one replacement made in one function call. If more than one pair of XPATH expression and replacement is given then
the function first finds all highlighted nodes, all together, then it performs all replacements, then it performs an normalization.
It is very important to understand that the order of making replacements has nothing to do with the order of pairs of parameters in the function call.
If some highlighted node is an ancestor of some other highlighted node then the effect of the replacement of the descendant highlighted node is void:
the descendant is replaced first; then the ancestor is replaced as a whole, no matter if some of its descendants are modified.
If a node is the result of two different XPATH expressions ("highlighted more than once"), the order of parameters in the function call
is used to resolve ambiguity: the last pair of parameters will have a higher priority.
</p>
</div>
<div class="refsect1">
<div class="refsect1title">Parameters</div>
<div class="refsect2">
<span class="refsect2title">source – </span>
A source XML tree entity. It is an error to pass persistent XML entity as an argument.
</div>
<div class="refsect2">
<span class="refsect2title">pathI – </span>
A text of XPATH expression to be used in order to find nodes to replace.
</div>
<div class="refsect2">
<span class="refsect2title">replacementI – </span>
A replacement value for XML nodes found by <span class="computeroutput">pathI</span>; it may be NULL or XML tree entity or a string r anything else but not an persistent XML entity.
</div>
</div>
<div class="refsect1">
<div class="refsect1title">Return Types</div>
<p>If the <span class="computeroutput">source</span> parameter is an XML tree entity then the function returns an XML tree entity that points to the root of the modified copy of the source document or a NULL.
If the <span class="computeroutput">source</span> is an instance of XMLType then a non-schema based instance of XMLType is created from the resulting XML tree entity.
</p>
</div>
<div class="refsect1">
<div class="refsect1title">Examples</div>
<a name="ex_XMLUpdate_1" />
<div class="example">
<div class="exampletitle">A simple replacement of one element with other</div>
<p>The call of function <span class="computeroutput">XMLUpdate</span> replaces element 'c' with a copy of element 'replacement'.</p>
<div>
<pre class="screen">
select XMLUpdate (xtree_doc('<a><b><q/>-<c>Hello</c>-</b></a>'), '//c', xtree_doc('<replacement/>'))
callret
VARCHAR
_______________________________________________________________________________
<a><b><q />-<replacement />-</b></a>
</pre>
</div>
</div>
<a name="ex_XMLUpdate_2" />
<div class="example">
<div class="exampletitle">Two replacements in parallel</div>
<p>Elements titled 'c1' and 'c3' are replaced with text nodes.</p>
<div>
<pre class="screen">
select XMLUpdate (xtree_doc('<a><b><c1>Hello1</c1><c2>Hello2</c2><c3>Hello3</c3></b></a>'), '//c1', 'world1', '//c3', 'world3')
callret
VARCHAR
_______________________________________________________________________________
<a><b>world1<c2>Hello2</c2>world3</b></a>
</pre>
</div>
</div>
</div>
<div class="refsect1">
<div class="refsect1title">See Also</div>
<p>
<a href="fn_XMLReplace.html">XMLReplace</a>
</p>
<p>
<a href="fn_XMLAddAttribute.html">XMLAddAttribute</a>
</p>
<p>
<a href="fn_XMLAppendChildren.html">XMLAppendChildren</a>
</p>
<p>
<a href="fn_XMLInsertBefore.html">XMLInsertBefore</a>
</p>
<p>
<a href="fn_XMLInsertAfter.html">XMLInsertAfter</a>
</p>
<p>
<a href="fn_xslt.html">xslt</a>
</p>
</div>
</div>
<div id="footer">
<div>Copyright© 1999 - 2009 OpenLink Software All rights reserved.</div>
<div id="validation">
<a href="http://validator.w3.org/check/referer">
<img src="http://www.w3.org/Icons/valid-xhtml10" alt="Valid XHTML 1.0!" height="31" width="88" />
</a>
<a href="http://jigsaw.w3.org/css-validator/">
<img src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!" height="31" width="88" />
</a>
</div>
</div>
</body>
</html>
distrib
>
Fedora
>
14
>
x86_64
>
media
>
updates
>
by-pkgid
>
71d40963b505df4524269198e237b3e3
>
files
>
140
