<!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: document-literal - Virtuoso Functions Guide" />
<meta name="dc.subject" content="Function: document-literal - 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: document-literal - 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_document_literal" />
<img src="../images/misc/logo.jpg" alt="" />
<h1>22. Virtuoso Functions Guide - document-literal</h1>
</div>
<div id="navbartop">
<div>
<a class="link" href="functions.html">Chapter Contents</a> | <a class="link" href="xpf_document.html" title="document">Prev</a> | <a class="link" href="xpf_empty.html" title="empty">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 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 class="selected" 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>document-literal</h2>
<div class="refpurpose">Parses given XML text and returns the resulting XML data.</div>
<div class="funcsynopsis">
<span class="funcdef">node-set <span class="function">document-literal</span>
</span>
(<span class="paramdef">
<span class="parameter">document_text</span> varchar</span>,
<span class="paramdefoptional">[<span class="optional">cache_uri</span> varchar]</span>,
<span class="paramdefoptional">[<span class="optional">parser_mode</span> integer]</span>,
<span class="paramdefoptional">[<span class="optional">content_encoding</span> varchar]</span>,
<span class="paramdefoptional">[<span class="optional">content_language</span> varchar]</span>,
<span class="paramdefoptional">[<span class="optional">dtd_validator_config</span> varchar]</span>);
</div>
<div class="refsect1">
<div class="refsect1title">Description</div>
<p>
The function tries to parse an XML text as if it is obtained from a location
specified by <span class="computeroutput">cache_uri</span>. On success, it returns
the root entity of the "XML Tree" document; the result is identical to
the entity created by <a href="fn_xtree_doc.html">xtree_doc()</a> Virtuoso/PL function.
</p>
<p>
When XPath processor parses a document, it saves it in a temporary cache.
If a cached document is accessed again then no actual retrieval or parsing is made and
a cached value is returned.
The cache persists till the end of execution of a XPath query
or till the end of the XSLT transformation
if the XPath expression is a part of XSLT stylesheet.
The <span class="computeroutput">cache_uri</span> specifies the URI used as a key if the parsed document is cached.
If <span class="computeroutput">cache_uri</span> is not specified or the specified value is equal to an empty string,
then no caching is performed.
If the specified <span class="computeroutput">cache_uri</span> is not equal to an empty string
then it should distinct from URIs of other XML resources that are sources of the
XPath query, to prevent confusion.
</p>
<p>
The <span class="computeroutput">cache_uri</span> is also used by XML parser
as a base URI to resolve relative URIs of external entities, so it is a good idea to
specify some absolute URI if the parsed text is not a "standalone" document.
</p>
<p>
The <span class="computeroutput">document_text</span> argument may be a sequence, not a single string.
In this case a node-set is returned as if <span class="computeroutput">document-literal</span> is applied to
string-value of every element of the sequence.
It is obvious that caching should not be used
if there's a chance that the sequence may have more than one distinct element.
</p>
<p>
Note that the <span class="computeroutput">document-literal</span> is not a part of XPATH 1.0
or XQuery 1.0 standard library.
</p>
</div>
<div class="refsect1">
<div class="refsect1title">Parameters</div>
<div class="refsect2">
<span class="refsect2title">document_text – </span>
well formed XML or HTML text</div>
<div class="refsect2">
<span class="refsect2title">cache_uri – </span>
The URI that is used to
resolve all relative URIs (i.e. to convert them into absolute in order to locate and load subdocuments) and
to change 'local' absolute references to relative when in HTML mode.</div>
<div class="refsect2">
<span class="refsect2title">parser_mode – </span>
0, 1 or 2; 0 - XML parser mode, 1 - HTML parser mode, 2 - 'dirty HTML'
mode (with quiet recovery after any syntax error)</div>
<div class="refsect2">
<span class="refsect2title">content_encoding – </span>
string with content encoding type of <span class="computeroutput">document_text</span>; valid are 'ASCII', 'ISO',
'UTF8', 'ISO8859-1', 'LATIN-1' etc., defaults are 'UTF-8' for XML mode and 'LATIN-1' for
HTML mode.</div>
<div class="refsect2">
<span class="refsect2title">content_language – </span>
string with language tag of content of <span class="computeroutput">document_text</span>; valid names are listed in
IETF RFC 1766, default is 'x-any' (it means 'mix of words from various human languages')</div>
<div class="refsect2">
<span class="refsect2title">dtd_validator_config – </span>
configuration string for DTD validator, default is "Include=ERROR IdCache=ENABLE" meaning that DTD
should be read but validation should be disabled; errors on including subdocuments should be
reported as errors and thus should abort the processing; a dictionary of element's IDs should be created
in order to support XQuery 'pointer operator'.
See <a href="xmlschema.html#dtd_config">Configuration Options of the DTD Validator</a> for details.</div>
</div>
<div class="refsect1">
<div class="refsect1title">Return Types</div>
<p>Node-set</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="errXPF15" />
<span class="errorcode">XPF15</span>
</td>
<td class="data">
<span class="errorname">Too many arguments passed to XPATH function document-literal()</span>
</td>
<td class="data">The number of parameters may vary only from 1 to 6.</td>
</tr>
</table>
<br />
</div>
<div class="refsect1">
<div class="refsect1title">Examples</div>
<a name="xpf_ex_document_literal1" />
<div class="example">
<div class="exampletitle">Simple reading of a standalone XML document</div>
<p>Read a short document from string</p>
<div>
<pre class="screen">document-literal("Hello")</pre>
</div>
</div>
<a name="xpf_ex_document_literal2" />
<div class="example">
<div class="exampletitle">Simple reading of a non-standalone document</div>
<p>Read a non-standalone document from local mirror but access its subdocuments as if it is retrieved directly from
'http://www.example.com/sales/prices.xml', so e.g. the subdocument that is referenced as 'termsandconditions.xml' is
retrieved from 'http://www.example.com/sales/termsandconditions.xml'</p>
<div>
<pre class="screen">
document-literal('
<!DOCTYPE price-list SYSTEM "http://www.example.com/dtd/sales.dtd" [
<!ENTITY t_and_c SYSTEM "termsandconditions.xml">
<!ENTITY prices_oct2002 SYSTEM "prices/2002/oct.xml">
]>
<price-list>
&t_and_c;
&prices_oct2002;
</price-list>
',
'http://webcache.localdomain/examplesales/prices.xml' )
</pre>
</div>
</div>
</div>
<div class="refsect1">
<div class="refsect1title">See Also</div>
<p>
<a href="xpf_document.html">document()</a>
</p>
<p>
<a href="fn_xtree_doc.html">xtree_doc()</a>
</p>
<p>
<a href="fn_xper_doc.html">xper_doc()</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
>
1035
