<!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: XPER navigation - Virtuoso Functions Guide" />
<meta name="dc.subject" content="Function: XPER navigation - 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: XPER navigation - 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_xper_right_sibling" />
<img src="../images/misc/logo.jpg" alt="" />
<h1>22. Virtuoso Functions Guide - XPER navigation</h1>
</div>
<div id="navbartop">
<div>
<a class="link" href="functions.html">Chapter Contents</a> | <a class="link" href="fn_xper_locate_words.html" title="xper_locate_words">Prev</a> | <a class="link" href="fn_xpf_extension.html" title="xpf_extension">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 href="fn_XMLUpdate.html">xmlupdate</a>
</div>
<div>
<a class="selected" 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>XPER navigation</h2>
<div class="refpurpose">low-level navigation functions for persistent XMLs, useful for import of huge amounts of XML data</div>
<div class="funcsynopsis">
<span class="funcdef">
<span class="function">xper_left_sibling</span>
</span>
(<span class="paramdef">in <span class="parameter">xper_entity</span>XML_entity</span>);
</div>
<div class="funcsynopsis">
<span class="funcdef">
<span class="function">xper_length</span>
</span>
(<span class="paramdef">in <span class="parameter">xper_entity</span>XML_entity</span>);
</div>
<div class="funcsynopsis">
<span class="funcdef">
<span class="function">xper_parent</span>
</span>
(<span class="paramdef">in <span class="parameter">xper_entity</span>XML_entity</span>);
</div>
<div class="funcsynopsis">
<span class="funcdef">
<span class="function">xper_right_sibling</span>
</span>
(<span class="paramdef">in <span class="parameter">xper_entity</span>XML_entity</span>);
</div>
<div class="funcsynopsis">
<span class="funcdef">
<span class="function">xper_root_entity</span>
</span>
(<span class="paramdef">in <span class="parameter">xper_entity</span>XML_entity</span>);
</div>
<div class="funcsynopsis">
<span class="funcdef">
<span class="function">xper_tell</span>
</span>
(<span class="paramdef">in <span class="parameter">xper_entity</span>XML_entity</span>);
</div>
<div class="refsect1">
<div class="refsect1title">Description</div>
<p>
All these functions work with "persistent XML" (XPER) entities only, signalling errors if
given entity points to "XML tree". They are useful when applications need to read a
huge XML document, especially something like a datasheet dump or event log with a large number
of uniform records, and is required to process all records of the document, e.g. import them into
the database.
</p>
<p>
Consider a real sample of import all data from ODP's content.xml dump which contains more than
2,000,000 descriptions of various Web-sites, and the length of the file is more than 600Mb. The
file has root element named 'RDF' and all descriptions are their children named either 'Topic' or
'ExternalPage'. This code looks suitable for importing these children:</p>
<div>
<pre class="programlisting">
create procedure
import_content_xml ()
{
for select _frag, xpath_eval('local_name()', _frag) as _tag from SOURCE_XML
where NAME='content.xml' and xpath_contains(XPER,'/RDF/*',_frag)
do
{
if (_tag='Topic') import_topic (_frag);
else
{
if (_tag='ExternalPage') import_external (_frag);
else log_import_error (_frag, "Unknown type of record");
}
}
};
-- This should load files like content.xml, and place XPERs into SOURCE_XML table
read_source_xmls();
-- Now SOURCE_XML is filled and data should be imported.
import_content_xml();
import_structure_xml();
import_profiles_xml();
...
</pre>
</div>
<p>
It looks fine and it passes small tests but it will not work on real data!</p>
<p>
First problem is regular checkpoints (every 1 hour by default),
so import_content_xml has no chance to be completed if it takes 1.5 hours of CPU time;
the function checkpoint_interval should be used to temporarily disable these checkpoints.
Then, the length of transaction log become extremely large after switching checkpoints off,
and it is better to insert explicit checkpoints between calls of these functions.
Finally, import_content_xml will change more than 4 gigabytes of data in one transaction.
This would be impossible on any 32-bit platform, because both memory available and address space
become insufficient. Adding intermediate 'commit work' statements inside the loop's body
will not help because both 'commit work' and 'rollback work' statements will close all opened cursors.
Loop 'for select ... from ... do' uses an implicit cursor to iterate the resultset, but the
'commit work' operator will close this cursor and abort the loop.</p>
<p>
Function xper_right_sibling is designed specially to solve the last problem. It allows you
to iterate children of some element without using any cursor at all.
It returns the right child of the entity passed as its argument. If the given entity
is the last child of its parent, the function will return NULL. Similarly, xper_left_sibling will
return the previous child or NULL for the first child, xper_parent will return parent of
entity or NULL for the document's root and xper_root_entity will return the root for any
entity. Using these functions, it is possible to scan the document forward (from left
to right), backward and to "climb up" toward the root of the elements' tree. These
functions are called <strong>XML Navigation Functions</strong> because they are like
the statements "next record", "prev record" etc., used in cursor
like navigation of databases.</p>
<p>
There are no special functions to "go down", e.g. to find first children of
given element, because xpath_eval can do any such movement very quickly.</p>
<p>
Sometimes data import is controlled from some client application. If one operation takes
hours, some sort of "progress bar" becomes very useful, at least to see whether
application works or hangs. xper_length takes an XPER entity and returns whole length of
XPER disk image in bytes. xper_tell takes an XPER entity and returns something like entity's offset
inside the document. Their results may be used by the client application to monitor the progress
and estimate the time until completion. They may be especially useful for debugging purposes,
e.g. to report position of error. Unfortunately "xper_seek" is not possible for
XPERs, unlike typical random access to files.</p>
<p>
Ultimately, the working version of the procedure described above will look like this:</p>
<div>
<pre class="programlisting">
create procedure
import_content_xml ()
{
declare _frag any;
declare _tag any;
declare _nodeid any;
declare _r_id varchar;
declare _about, _title, _description varchar;
declare CurTime varchar;
declare Frags, Inserts, Pos, Length integer;
select _frag1 into _frag from SOURCE_XML
where NAME = 'content.xml' and xpath_contains (XPER, '/RDF/*', _frag1);
if (not isentity(_frag)) signal('42ODP', 'XML source "Content" is empty');
Frags := 0;
Inserts := 0;
Length := xper_length(_frag);
result_names (CurTime, Frags, Pos, Length);
-- It's not the best way to process deadlocks, but it may be better than nothing.
whenever sqlstate '40001' goto next_frag;
next_frag:
-- Server will inform client application about progress after every 10000 records.
if (mod(Frags,10000) = 0)
{
-- Note that if it needs to estimate the time to completion, time should be measured
-- on server side, because results may be returned on batches to reduce network
-- traffic, and it may be a significant delay between call of result function on
-- server and fetch on client side.
CurTime := cast(now() as varchar);
Pos := xper_tell(_frag);
result (CurTime, Frags, Inserts, Pos, Length);
}
_tag := xpath_eval('local-name()', _frag);
if (_tag = 'Topic')
{
import_topic(_frag);
goto advance;
}
if (_tag = 'ExternalPage')
{
import_external(_frag);
goto advance;
}
log_import_error (_frag, "Unknown type of record");
goto nocommit_advance;
advance:
Inserts := Inserts + 1;
-- Note that it may be faster to have 1 commit per 100 or 1000 records in some cases.
commit work;
nocommit_advance:
Frags := Frags + 1;
_frag := xper_right_sibling(_frag);
if (isentity(_frag)) goto next_frag; -- If _frag is NULL, we've completed the import.
CurTime := cast(now() as varchar);
result (CurTime, Frags, Inserts, Length, Length);
};
checkpoint_interval(0);
checkpoint;
read_source_xmls();
checkpoint;
import_content_xml();
checkpoint;
import_structure_xml();
checkpoint;
import_profiles_xml();
checkpoint;
...
checkpoint_interval(60);
</pre>
</div>
</div>
<div class="refsect1">
<div class="refsect1title">Parameters</div>
<div class="refsect2">
<span class="refsect2title">xper_entity – </span>
Persistent XML entity to operate on.</div>
</div>
<div class="refsect1">
<div class="refsect1title">See Also</div>
<p>
<a href="fn_xper_doc.html">xper_doc</a>
</p>
<p>
<a href="fn_xper_cut.html">xper_cut</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
>
748
