1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
|
<?xml version="1.0" encoding="ISO-8859-1"?>
<!--
-
- This file is part of the OpenLink Software Virtuoso Open-Source (VOS)
- project.
-
- Copyright (C) 1998-2018 OpenLink Software
-
- This project is free software; you can redistribute it and/or modify it
- under the terms of the GNU General Public License as published by the
- Free Software Foundation; only version 2 of the License, dated June 1991.
-
- This program is distributed in the hope that it will be useful, but
- WITHOUT ANY WARRANTY; without even the implied warranty of
- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
- General Public License for more details.
-
- You should have received a copy of the GNU General Public License along
- with this program; if not, write to the Free Software Foundation, Inc.,
- 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
-
-
-->
<refentry id="fn_xml_tree_doc">
<refmeta>
<refentrytitle>xml_tree_doc</refentrytitle>
<refmiscinfo>xml</refmiscinfo>
</refmeta>
<refnamediv>
<refname>xml_tree_doc</refname>
<refpurpose>returns an entity object given a tree from xml_tree</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis id="fsyn_xml_tree_doc">
<funcprototype id="fproto_xml_tree_doc">
<funcdef><function>xml_tree_doc</function></funcdef>
<paramdef>in <parameter>tree</parameter> any</paramdef>
<paramdef><optional>in <parameter>base_uri</parameter> varchar</optional></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 id="desc"><title>Description</title>
<para>
This returns an entity object given a tree of the form returned by xml_tree.
</para>
<para>
If it is given a string as an argument, it will automatically generate
the parse tree and use it to make the entity instead requiring you to run the string through
xml_tree first. Note that it is better to use <function><link linkend="fn_xtree_doc">xtree_doc</link></function> or
<function><link linkend="fn_xper_doc">xper_doc</link></function>
for converting source XML text directly to an XML entity.
</para>
<para>
If the argument is an XML tree entity, the function will return it as is, so
e.g. redundant calls of <function>xml_tree_doc</function> will have no effect.
The only thing xml_tree_doc can alter in the returned value is base URI of
the document entity: if <parameter>base_uri</parameter> is provided and is
not NULL, and argument entity has no base URI set then the provided URI
is assigned to the returned entity.
</para>
<para>
Any other type of argument is illegal, including XML persistent entity.
</para>
</refsect1>
<refsect1 id="params"><title>Parameters</title>
<refsect2><title>tree</title>
<para>either an XML tree such as that returned by xml_tree(), or a string of XML data.
If a string is provided then it will automatically generate the parse tree and form an
entity instead of requiring you to run the string through xml_tree() first.</para></refsect2>
<refsect2><title>base_uri</title>
<para>Base URI of the original document, if known.
It will be useful if the document is not "standalone" and some entity references
are relative references to resources located "somewhere near" the
"top-level" document passes as "tree" parameter.</para></refsect2>
</refsect1>
<refsect1 id="ret"><title>Return Types</title><para>XML entity object</para></refsect1>
<refsect1 id="errors_xml_tree_doc"><title>Errors</title>
<table><title>Errors signalled by </title>
<tgroup cols="4">
<thead>
<row><entry>SQL State</entry><entry>Error Code</entry><entry>Error Text</entry><entry>Description</entry></row>
</thead>
<tbody>
<row>
<entry><errorcode></errorcode></entry>
<entry><errorcode></errorcode></entry>
<entry><errorname></errorname></entry>
<entry></entry>
</row>
</tbody>
</tgroup>
</table>
</refsect1>
<refsect1 id="examples"><title>Examples</title>
<example id="ex_xml_tree_doc"><title>Transforming an XML Document</title>
<programlisting>
declare doc_base varchar;
declare doc_tree any;
doc_base := 'virt://WS.WS.SYS_DAV_RES.RES_FULL_PATH.RES_CONTENT:/DAV/docsrc/';
doc_tree := xml_tree_doc(xml_tree(
xml_uri_get(doc_base, 'virtdocs.xml')
), doc_base);
http_value(
xslt('virt://WS.WS.SYS_DAV_RES.RES_FULL_PATH.RES_CONTENT:/DAV/stylesheets/html_chapter.xsl',
doc_tree
)
);
</programlisting>
</example>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para><link linkend="fn_xtree_doc">xtree_doc</link></para>
<para><link linkend="fn_xper_doc">xper_doc</link></para>
<para><link linkend="fn_xml_tree">xml_tree</link></para>
<para><link linkend="fn_xslt">xslt</link></para>
<para><link linkend="fn_xml_uri_get">xml_uri_get</link></para>
</refsect1>
</refentry>
|
