<!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: create-element - Virtuoso Functions Guide" /> <meta name="dc.subject" content="Function: create-element - 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: create-element - 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="xpf_create_element" /> <img src="../images/misc/logo.jpg" alt="" /> <h1>22. Virtuoso Functions Guide - create-element</h1> </div> <div id="navbartop"> <div> <a class="link" href="functions.html">Chapter Contents</a> | <a class="link" href="xpf_create_comment.html" title="create-comment">Prev</a> | <a class="link" href="xpf_create_pi.html" title="create-pi">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 href="functions.html#xml">XML</a> </div> <div> <a class="selected" href="functions.html#XPATH">XPATH & XQUERY</a> </div> <div class="selected"> <div> <a href="xpf_and.html">and</a> </div> <div> <a href="xpf_append.html">append</a> </div> <div> <a href="xpf_assign.html">assign</a> </div> <div> <a href="xpf_avg.html">avg</a> </div> <div> <a href="xpf_boolean.html">boolean</a> </div> <div> <a href="xpf_ceiling.html">ceiling</a> </div> <div> <a href="xpf_concat.html">concat</a> </div> <div> <a href="xpf_contains.html">contains</a> </div> <div> <a href="xpf_count.html">count</a> </div> <div> <a href="xpf_create_attribute.html">create-attribute</a> </div> <div> <a href="xpf_create_comment.html">create-comment</a> </div> <div> <a class="selected" href="xpf_create_element.html">create-element</a> </div> <div> <a href="xpf_create_pi.html">create-pi</a> </div> <div> <a href="xpf_current.html">current</a> </div> <div> <a href="xpf_distinct.html">distinct</a> </div> <div> <a href="xpf_doc.html">doc</a> </div> <div> <a href="xpf_document.html">document</a> </div> <div> <a href="xpf_document_literal.html">document-literal</a> </div> <div> <a href="xpf_empty.html">empty</a> </div> <div> <a href="xpf_ends_with.html">ends-with</a> </div> <div> <a href="xpf_every.html">every</a> </div> <div> <a href="xpf_except.html">except</a> </div> <div> <a href="xpf_false.html">false</a> </div> <div> <a href="xpf_filter.html">filter</a> </div> <div> <a href="xpf_floor.html">floor</a> </div> <div> <a href="xpf_collection.html">fn:collection</a> </div> <div> <a href="xpf_for.html">for</a> </div> <div> <a href="xpf_format_number.html">format-number</a> </div> <div> <a href="xpf_function_available.html">function-available</a> </div> <div> <a href="xpf_generate_id.html">generate-id</a> </div> <div> <a href="xpf_id.html">id</a> </div> <div> <a href="xpf_if.html">if</a> </div> <div> <a href="xpf_intersect.html">intersect</a> </div> <div> <a href="xpf_is_after.html">is_after()</a> </div> <div> <a href="xpf_is_before.html">is_before()</a> </div> <div> <a href="xpf_key.html">key</a> </div> <div> <a href="xpf_lang.html">lang</a> </div> <div> <a href="xpf_last.html">last</a> </div> <div> <a href="xpf_let.html">let</a> </div> <div> <a href="xpf_list.html">list()</a> </div> <div> <a href="xpf_local_name.html">local-name</a> </div> <div> <a href="xpf_max.html">max</a> </div> <div> <a href="xpf_min.html">min</a> </div> <div> <a href="xpf_name.html">name</a> </div> <div> <a href="xpf_namespace_uri.html">namespace-uri</a> </div> <div> <a href="xpf_normalize_space.html">normalize-space</a> </div> <div> <a href="xpf_not.html">not</a> </div> <div> <a href="xpf_number.html">number</a> </div> <div> <a href="xpf_or.html">or</a> </div> <div> <a href="xpf_position.html">position</a> </div> <div> <a href="xpf_processXQuery.html">processxquery</a> </div> <div> <a href="xpf_processXSLT.html">processxslt</a> </div> <div> <a href="xpf_processXSQL.html">processxsql</a> </div> <div> <a href="xpf_progn.html">progn()</a> </div> <div> <a href="xpf_replace.html">replace()</a> </div> <div> <a href="xpf_round.html">round</a> </div> <div> <a href="xpf_serialize.html">serialize</a> </div> <div> <a href="xpf_shallow.html">shallow</a> </div> <div> <a href="xpf_some.html">some</a> </div> <div> <a href="xpf_starts_with.html">starts-with</a> </div> <div> <a href="xpf_string.html">string</a> </div> <div> <a href="xpf_string_length.html">string-length</a> </div> <div> <a href="xpf_substring.html">substring</a> </div> <div> <a href="xpf_substring_after.html">substring-after</a> </div> <div> <a href="xpf_substring_before.html">substring-before</a> </div> <div> <a href="xpf_sum.html">sum</a> </div> <div> <a href="xpf_system_property.html">system-property</a> </div> <div> <a href="xpf_text_contains.html">text_contains()</a> </div> <div> <a href="xpf_translate.html">translate</a> </div> <div> <a href="xpf_true.html">true</a> </div> <div> <a href="xpf_tuple.html">tuple()</a> </div> <div> <a href="xpf_union.html">union</a> </div> <div> <a href="xpf_unordered.html">unordered</a> </div> <div> <a href="xpf_unparsed_entity_uri.html">unparsed-entity-uri</a> </div> <div> <a href="xpf_urlify.html">urlify</a> </div> <div> <a href="xpf_xmlview.html">xmlview</a> </div> </div> <br /> <div> <a href="functionidx.html">Functions Index</a> </div> <br /> </div> <div id="text"> <h2>create-element</h2> <div class="refpurpose">Creates an element with specified name, attributes and children</div> <div class="funcsynopsis"> <span class="funcdef">node <span class="function">create-element</span> </span> (<span class="paramdef"> <span class="parameter">head</span> sequence</span>, <span class="paramdef"> <span class="parameter">child1</span> any</span>, <span class="paramdef"> <span class="parameter">child2</span> any</span>, <span class="paramdef"> <span class="parameter">...</span> </span>, <span class="paramdef"> <span class="parameter">childN</span> any</span>); </div> <div class="refsect1"> <div class="refsect1title">Description</div> <p> This is an internal XQUERY function and you will probably never need to call it explicitly. It is not a part of library of standard XQUERY 1.0 functions. </p> <p> This function creates a new "XML Tree" element whose name is a string-value of the first item of <span class="computeroutput">head</span> sequence, with attributes and children specified by the rest of <span class="computeroutput">head</span> sequence and by the list of arguments <span class="computeroutput">child1</span>, <span class="computeroutput">child2</span>, ... <span class="computeroutput">childN</span>. </p> First of all, a new element will be created, without attributes or children. The name of element will be taken from the first item of the head sequence. Then attributes will be created from the second and third items of head, from fourth and fifth and so on. In every pair of items will specify name and value of some attribute. Non-string items will be converted to strings first. It is an error to specify the same attribute name twice in head sequence. <p> </p> When the "opening tag" of the element is prepared, children are added, in the same order as they are specified by arguments child1, child2, ... childN. If the value of some argument is a sequences (e.g. a node-set), items of the sequence are added as separate children in the same order as they are in the sequence. Nodes are added "as-is", numbers, strings and other "scalar" values are converted to strings first and these strings are converted into PCDATA (text) children. <p> </p> "Attribute descriptor" objects are not converted to children elements; if descriptor item is found, one attribute in the opening tag of the created element is added or changed and the descriptor is removed from the list of children. <p> </p> When all children are prepared, some normalization is performed. If there are two or more adjacent PCDATA (text) children, they are replaced with one PCDATA children whose text is a concatenation of texts of all that children. <p> </p> </div> <div class="refsect1"> <div class="refsect1title">Parameters</div> <div class="refsect2"> <span class="refsect2title">head – </span> Name of the element or a sequence of name and attributes of the element.</div> <div class="refsect2"> <span class="refsect2title">childI – </span> Children node or sequence of children node.</div> </div> <div class="refsect1"> <div class="refsect1title">Return Types</div> <p>Node</p> </div> <div class="refsect1"> <div class="refsect1title">Errors</div> <table class="data"> <tr> <th class="data">SQLState</th> <th class="data">Error Code</th> <th class="data">Error Text</th> <th class="data">Description</th> </tr> <tr> <td class="data"> <a name="errXP001" /> <span class="errorcode">XP001</span> </td> <td class="data"> <a name="errXPFC0" /> <span class="errorcode">XPFC0</span> </td> <td class="data"> <span class="errorname">At least one argument (name of element to be created) must be passed to create-element XPATH function.</span> </td> <td class="data">create-element is called without arguments.</td> </tr> <tr> <td class="data"> <a name="errXP001" /> <span class="errorcode">XP001</span> </td> <td class="data"> <a name="errXPFC1" /> <span class="errorcode">XPFC1</span> </td> <td class="data"> <span class="errorname">No name of element in the first argument of create-element XPATH function.</span> </td> <td class="data">The head sequence is empty.</td> </tr> <tr> <td class="data"> <a name="errXP001" /> <span class="errorcode">XP001</span> </td> <td class="data"> <a name="errXPFC2" /> <span class="errorcode">XPFC2</span> </td> <td class="data"> <span class="errorname">Last attribute has no value specified in the first argument of create-element XPATH function.</span> </td> <td class="data">The head sequence is of even length.</td> </tr> <tr> <td class="data"> <a name="errXP001" /> <span class="errorcode">XP001</span> </td> <td class="data"> <a name="errXPFC3" /> <span class="errorcode">XPFC3</span> </td> <td class="data"> <span class="errorname">Unsupported type of element of the first argument of create-element XPATH function.</span> </td> <td class="data">Current version may create name and attributes of elements only from strings, entities and numbers.</td> </tr> <tr> <td class="data"> <a name="errXP001" /> <span class="errorcode">XP001</span> </td> <td class="data"> <a name="errXPFC4" /> <span class="errorcode">XPFC4</span> </td> <td class="data"> <span class="errorname">Duplicate attribute names in first argument of create-element XPATH function.</span> </td> <td class="data">Duplicate attribute names may appear in attribute descriptors but not in the head argument.</td> </tr> <tr> <td class="data"> <a name="errXP001" /> <span class="errorcode">XP001</span> </td> <td class="data"> <a name="errXPFC5" /> <span class="errorcode">XPFC5</span> </td> <td class="data"> <span class="errorname">First argument of create-element XPATH function must be string, symbol or sequence of them.</span> </td> <td class="data">The function was unable to prepare name of element.</td> </tr> <tr> <td class="data"> <a name="errXP001" /> <span class="errorcode">XP001</span> </td> <td class="data"> <a name="errXPFC6" /> <span class="errorcode">XPFC6</span> </td> <td class="data"> <span class="errorname">Error in XPATH user extension function or internal error: sequence argument is not flat in create-element XPATH function.</span> </td> <td class="data">A value of XQUERY "sequence" type should not contain other sequences as its items, i.e. it must be "flat".</td> </tr> <tr> <td class="data"> <a name="errXP001" /> <span class="errorcode">XP001</span> </td> <td class="data"> <a name="errXPFC7" /> <span class="errorcode">XPFC7</span> </td> <td class="data"> <span class="errorname">Invalid special entity found in argument of create-element XPATH function.</span> </td> <td class="data">An invalid object (probably built by XPATH extension function) is specified as child entity.</td> </tr> <tr> <td class="data"> <a name="errXP001" /> <span class="errorcode">XP001</span> </td> <td class="data"> <a name="errXPFCA" /> <span class="errorcode">XPFCA</span> </td> <td class="data"> <span class="errorname">Persistent XML entities are not fully supported by create-element XPATH function.</span> </td> <td class="data">The function creates "XML Tree" element, "Persistent XML" entity can not become a children of "XML Tree".</td> </tr> <tr> <td class="data"> <a name="errXP001" /> <span class="errorcode">XP001</span> </td> <td class="data"> <a name="errXPFCB" /> <span class="errorcode">XPFCB</span> </td> <td class="data"> <span class="errorname">Unsupported type of argument in create-element XPATH function.</span> </td> <td class="data">Some argument or some item of an argument may not be converted to a string or a node, so a children may not be created.</td> </tr> </table> <br /> </div> <div class="refsect1"> <div class="refsect1title">Examples</div> <a name="xpf_ex_create_element" /> <div class="example"> <div class="exampletitle" /> <p>Two following XQUERY expressions are equivalent:</p> <div> <pre class="screen"> <H1>{'Hello, '}<B>{'world'}</B></H1> create-element('H1', 'Hello, ', create-element('B', 'world')) </pre> </div> </div> </div> <div class="refsect1"> <div class="refsect1title">See Also</div> <p> <a href="xpf_create_attribute.html">create-attribute()</a> </p> <p> <a href="xpf_create_comment.html">create-comment()</a> </p> <p> <a href="xpf_create_pi.html">create-pi()</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>