# 22. Virtuoso Functions Guide - document-literal

Chapter Contents | Prev | Next
Keyword Search:
www.openlinksw.com
docs.openlinksw.com
Book Home
Contents
Preface
Virtuoso Functions Guide
Administration
Aggregate Functions
Array Manipulation
BPEL APIs
Backup
Compression
Cursor
Date & Time Manipulation
Debug
Dictionary Manipulation
Encoding & Decoding
File Manipulation
Free Text
Hashing / Cryptographic
LDAP
Locale
Mail
Miscellaneous
Number
Remote SQL Data Source
Replication
SOAP
SQL
String
Transaction
Type Mapping
UDDI
User Defined Types & The CLR
Virtuoso Java PL API
Virtuoso Server Extension Interface (VSEI)
Web Server & Internet
XML
XPATH & XQUERY
and
append
assign
avg
boolean
ceiling
concat
contains
count
create-attribute
create-comment
create-element
create-pi
current
distinct
doc
document
document-literal
empty
ends-with
every
except
false
filter
floor
fn:collection
for
format-number
function-available
generate-id
id
if
intersect
is_after()
is_before()
key
lang
last
let
list()
local-name
max
min
name
namespace-uri
normalize-space
not
number
or
position
processxquery
processxslt
processxsql
progn()
replace()
round
serialize
shallow
some
starts-with
string
string-length
substring
substring-after
substring-before
sum
system-property
text_contains()
translate
true
tuple()
union
unordered
unparsed-entity-uri
urlify
xmlview
Functions Index

## document-literal

Parses given XML text and returns the resulting XML data.
node-set document-literal ( document_text varchar, [cache_uri varchar], [parser_mode integer], [content_encoding varchar], [content_language varchar], [dtd_validator_config varchar]);
Description

The function tries to parse an XML text as if it is obtained from a location specified by cache_uri. On success, it returns the root entity of the "XML Tree" document; the result is identical to the entity created by xtree_doc() Virtuoso/PL function.

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 cache_uri specifies the URI used as a key if the parsed document is cached. If cache_uri is not specified or the specified value is equal to an empty string, then no caching is performed. If the specified cache_uri 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.

The cache_uri 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.

The document_text argument may be a sequence, not a single string. In this case a node-set is returned as if document-literal 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.

Note that the document-literal is not a part of XPATH 1.0 or XQuery 1.0 standard library.

Parameters
document_text – well formed XML or HTML text
cache_uri – 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.
parser_mode – 0, 1 or 2; 0 - XML parser mode, 1 - HTML parser mode, 2 - 'dirty HTML' mode (with quiet recovery after any syntax error)
content_encoding – string with content encoding type of document_text; valid are 'ASCII', 'ISO', 'UTF8', 'ISO8859-1', 'LATIN-1' etc., defaults are 'UTF-8' for XML mode and 'LATIN-1' for HTML mode.
content_language – string with language tag of content of document_text; valid names are listed in IETF RFC 1766, default is 'x-any' (it means 'mix of words from various human languages')
dtd_validator_config – 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 Configuration Options of the DTD Validator for details.
Return Types

Node-set

Errors

SQLState | Error Code | Error Text | Description
--- | --- | --- | ---
XP001 | XPF15 | Too many arguments passed to XPATH function document-literal() | The number of parameters may vary only from 1 to 6.

Examples
Simple reading of a standalone XML document

Read a short document from string

    document-literal("Hello")

Simple reading of a non-standalone document

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'

    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' )

See Also

document()

xtree_doc()

xper_doc()