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
|
<?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_XMLAddAttribute">
<refmeta>
<refentrytitle>XMLAddAttribute</refentrytitle>
<refmiscinfo>xml</refmiscinfo>
</refmeta>
<refnamediv>
<refname>XMLAddAttribute</refname>
<refpurpose>Add an attribute to the given node of an XML tree document</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis id="fsyn_XMLAddAttribute">
<funcprototype id="fproto_XMLAddAttribute">
<funcdef>integer <function>XMLAddAttribute</function></funcdef>
<paramdef>inout <parameter>source</parameter> any</paramdef>
<paramdef>in <parameter>mode</parameter> integer</paramdef>
<paramdef>in <parameter>attr_name</parameter> any</paramdef>
<paramdef><optional>in <parameter>attr_value</parameter> any</optional></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 id="desc_XMLAddAttribute">
<title>Description</title>
<para>The function modifies the <code>source</code> document by adding an attribute to the current node of
<code>source</code> entity. The <code>source</code> should be an XML tree entity, not "persistent XML"
one, should be an element entity (not attribute, text etc.) and should not be a root entity. Parameters
<code>attr_name</code> and <code>attr_value</code> can be of any types that can be casted to string.
<code>attr_name</code> can be an attribute entity, in this case both the name and the value of
<code>attr_name</code> attribute is used and <code>attr_value</code> code must be omitted.</para>
<para>The <code>mode</code> specifies how to resolve duplicate attribute names, if an <code>source</code>
entity already has an attribute whose name is equal to <code>attr_name</code>. Mode 0 is similar to "insert into":
the function signals an error if an attribute already exists. Mode 1 is similar to "insert soft": the function do
nothing if an attribute already exists and not signalling an error. Mode 2 is similar to "insert replacing": the
function either adds a new attribute or replacing the value of existing attribute.</para>
</refsect1>
<refsect1 id="params_XMLAddAttribute">
<title>Parameters</title>
<refsect2><title>source</title>
<para>The XML tree entity to change.</para>
</refsect2>
<refsect2><title>mode</title>
<para>The mode of resolving duplicate attribute names.</para>
</refsect2>
<refsect2><title>attr_name</title>
<para>The name of a new attribute (or an attribute XML entity that specifies both name and value of an attribute.</para>
</refsect2>
<refsect2><title>attr_value</title>
<para>The value of a new attribute</para>
</refsect2>
</refsect1>
<refsect1 id="ret_XMLAddAttribute"><title>Return Types</title>
<para>The function returns integer that indicate the actual operation performed. The zero value means that there
was no change ("insert soft" when an attribute already exists). The value one means that a new attribute was added,
the value two means that an existing attribute was replaced.</para>
</refsect1>
<!--
<refsect1 id="errors_XMLAddAttribute">
<title>Errors</title>
< !- - In case of non-function-specific errors, i.e. only common
parameter errors are signalled, comment out the table below
otherwise add the unique error values as individual errorcodes - - >
<para>This function can generate the following errors:</para>
<errorcode></errorcode>
</refsect1>
-->
<refsect1 id="examples_XMLAddAttribute">
<title>Examples</title>
<example id="ex_XMLAddAttribute"><title>Different modes of calling XMLAddAttribute</title>
<para>The sample procedure contains three calls of <code>XMLAddAttribute</code> with different values of
<code>mode</code>, for "insert into", "insert soft" and "insert replacing" behaviour. </para>
<screen><![CDATA[
create procedure XMLAddAttribute_demo ()
{
declare DESCRIPTION varchar (33);
declare XMLENTITY, ent any;
result_names (DESCRIPTION, XMLENTITY);
result ('EXAMPLE 1', 'Adding a new attribute');
ent := xpath_eval ('//b', xtree_doc('<a><b attrX="x" attrY="y"/></a>'));
result ('The document to modify:', xpath_eval('/', ent));
result ('An element node to change:', ent);
XMLAddAttribute (ent, 0, 'attrZ', 'z');
result ('The document after modification:', xpath_eval('/', ent));
result ('EXAMPLE 2', 'Failed adding of an (existing) attribute');
ent := xpath_eval ('//b', xtree_doc('<a><b attrX="x" attrY="y"/></a>'));
result ('The document to modify:', xpath_eval('/', ent));
result ('An element node to change:', ent);
XMLAddAttribute (ent, 1, 'attrX', 'xNEW');
result ('The document after modification:', xpath_eval('/', ent));
result ('EXAMPLE 3', 'Successful replacing of an existing attribute');
ent := xpath_eval ('//b', xtree_doc('<a><b attrX="x" attrY="y"/></a>'));
result ('The document to modify:', xpath_eval('/', ent));
result ('An element node to change:', ent);
XMLAddAttribute (ent, 2, 'attrX', 'xNEW');
result ('The document after modification:', xpath_eval('/', ent));
}
Done. -- 00000 msec.
XMLAddAttribute_demo()
DESCRIPTION XMLENTITY
VARCHAR VARCHAR
_______________________________________________________________________________
EXAMPLE 1 Adding a new attribute
The document to modify: <a><b attrX="x" attrY="y" /></a>
An element node to change: <b attrX="x" attrY="y" />
The document after modification: <a><b attrX="x" attrY="y" attrZ="z" /></a>
EXAMPLE 2 Failed adding of an (existing) attribute
The document to modify: <a><b attrX="x" attrY="y" /></a>
An element node to change: <b attrX="x" attrY="y" />
The document after modification: <a><b attrX="x" attrY="y" /></a>
EXAMPLE 3 Successful replacing of an existing attribute
The document to modify: <a><b attrX="x" attrY="y" /></a>
An element node to change: <b attrX="x" attrY="y" />
The document after modification: <a><b attrX="xNEW" attrY="y" /></a>
12 Rows. -- 00000 msec.
]]>
</screen>
</example>
</refsect1>
<refsect1 id="seealso_XMLAddAttribute">
<title>See Also</title>
<para><link linkend="fn_XMLReplace"><function>XMLReplace()</function></link></para>
<para><link linkend="fn_XMLAppendChildren"><function>XMLAppendChildren()</function></link></para>
<para><link linkend="fn_XMLInsertBefore"><function>XMLInsertBefore()</function></link></para>
<para><link linkend="fn_XMLInsertAfter"><function>XMLInsertAfter()</function></link></para>
</refsect1>
</refentry>
|
