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
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
|
<?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_XMLELEMENT">
<refmeta>
<refentrytitle>XMLELEMENT</refentrytitle>
<refmiscinfo>xml</refmiscinfo>
</refmeta>
<refnamediv>
<refname>XMLELEMENT</refname>
<refpurpose>Creates XML element</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis id="fsyn_XMLELEMENT">
<funcprototype id="fproto_XMLELEMENT">
<funcdef><function>XMLELEMENT</function></funcdef>
<paramdef><parameter>tag_name</parameter> varchar</paramdef>
<paramdef><optional><parameter>list_of_attributes</parameter> sequence</optional></paramdef>
<paramdef><optional><parameter>child_or_attribute1</parameter> any</optional></paramdef>
<paramdef><optional><parameter>child_or_attribute2</parameter> any</optional></paramdef>
<paramdef><optional><parameter>...</parameter></optional></paramdef>
<paramdef><optional><parameter>child_or_attributeN</parameter> any</optional></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 id="desc_XMLELEMENT"><title>Description</title>
<para>
<function>XMLELEMENT</function> takes an element name for identifier, an optional collection of attributes for the element,
and arguments that make up the element's content.
It returns a XML element. The second parameter may be omitted and at that time the
rest parameters may be present. If one of the arguments is a call of the <function>xpath_eval</function> returning
an attribute value, then this value would be added to element's content (not to element's attributes).
</para>
</refsect1>
<refsect1 id="XMLELEMENT"><title>Parameters</title>
<refsect2><title>tag_name</title>
<para>name of the element, it must be valid XML element name </para>
</refsect2>
<refsect2><title>list_of_attributes</title>
<para>a vector returned by <function>XMLATTRIBUTES</function> function. If the vector is NULL, then no attribute is created.</para>
</refsect2>
<refsect2><title>child_or_attributeI</title>
<para>a string, or name of a column, or concatenation of the names and/or strings, or a vector returned by
<function>XMLELEMENT</function>, <function>XMLFOREST</function>,
<function>XMLCONCAT</function>, or <function>XMLAGG</function> functions,
or an entity object returned by
corresponding functions (e.g. <function>xtree_doc</function> or <function>xquery_eval</function>).
If the entity object is an attribute entity, then it is joined
to the list of the element's attributes. If a parameter is NULL, then no child element or attribute is created for
that parameter.
</para>
</refsect2>
</refsect1>
<refsect1 id="errors_XMLELEMENT">
<title>Errors</title>
<table><title>Errors signalled by <function>XMLELEMENT</function></title>
<tgroup cols="4">
<thead>
<row>
<entry>SQLState</entry><entry>Error Code</entry><entry>Error Text</entry><entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><errorcode>22003</errorcode></entry>
<entry><errorcode>SR354</errorcode></entry>
<entry><errorname>Too few arguments for XMLELEMENT</errorname></entry>
<entry>There must be at least one argument</entry>
</row>
</tbody>
</tgroup>
</table>
</refsect1>
<refsect1 id="XMLELEMENT"><title>Examples</title>
<example id="ex_XMLELEMENT"><title>XMLELEMENT() with a single argument</title>
<para>
<function>XMLELEMENT</function> creates an 'Title' element without content.
</para>
<screen>
select XMLELEMENT ('Title') from "Demo"."demo"."Employees";
callret
VARCHAR
_______________________________________________________________________________
<Title />
<Title />
. . .
9 Rows. -- 2 msec.
</screen>
</example>
<example id="ex_XMLELEMENT"><title>XMLELEMENT() with content</title>
<para>The following example produces an 'Emp' element with three attributes
(the 'region' attribute is calculated by <function>xquery_eval</function>)
and five nested subelements </para>
<screen>
select XMLELEMENT ('Emp',
XMLATTRIBUTES ( "EmployeeID" AS "EmpID", "Title"),
XMLELEMENT ('Name', "FirstName" || ' ' || "LastName" ),
xquery_eval('//@region', xtree_doc ('<a region="WA"></a>')),
XMLFOREST ("PostalCode", "City" as "city"),
XMLCONCAT (XMLELEMENT ('HomePhone', "HomePhone"),
XMLELEMENT ('BirthDate', "BirthDate")))
from "Demo"."demo"."Employees"
where "EmployeeID"=1;
callret
VARCHAR
_______________________________________________________________________________
<Emp EmpID="1" Title="Sales Representative" region="WA">
<Name>Nancy Davolio</Name>
<city>Seattle</city>
<PostalCode>98122</PostalCode>
<HomePhone>(206) 555-9857</HomePhone>
<BirthDate>1948-12-08</BirthDate>
</Emp>
</screen>
</example>
<example id="ex_XMLELEMENT"><title>XMLELEMENT() with the aggregate function XMLAGG()</title>
<para>
This example produces 'Emp' elements, with the list of the 'Name' of all employees.
</para>
<screen>
select XMLELEMENT ('Emp',
XMLAGG (XMLELEMENT('Name', "FirstName", ' ', "LastName")))
from "Demo"."demo"."Employees";
callret
VARCHAR
_______________________________________________________________________________
<Emp>
<Name>Nancy Davolio</Name>
<Name>Andrew Fuller</Name>
<Name>Janet Leverling</Name>
<Name>Margaret Peacock</Name>
<Name>Steven Buchanan</Name>
<Name>Michael Suyama</Name>
<Name>Robert King</Name>
<Name>Laura Callahan</Name>
<Name>Anne Dodsworth</Name>
</Emp>
</screen>
</example>
</refsect1>
<refsect1 id="seealso_XMLELEMENT"><title>See Also</title>
<para><link linkend="fn_XMLAGG">XMLAGG()</link></para>
<para><link linkend="fn_XMLATTRIBUTES">XMLATTRIBUTE()</link></para>
<para><link linkend="fn_XMLCONCAT">XMLCONCAT()</link></para>
<para><link linkend="fn_XMLFOREST">XMLFOREST()</link></para>
</refsect1>
</refentry>
|
