Name
XMLAddAttribute — Add an attribute to the given node of an XML tree document
Synopsis
integer
XMLAddAttribute
(
|
inout source any , |
| in mode integer , | |
| in attr_name any , | |
in
attr_value
any
); |
Description
The function modifies the source document by adding
an attribute to the current node of source entity.
The source 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
attr_name and attr_value can be of any
types that can be casted to string. attr_name can be
an attribute entity, in this case both the name and the value of
attr_name attribute is used and
attr_value code must be omitted.
The mode specifies how to resolve duplicate attribute
names, if an source entity already has an attribute
whose name is equal to attr_name . 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.
Parameters
source
The XML tree entity to change.
mode
The mode of resolving duplicate attribute names.
attr_name
The name of a new attribute (or an attribute XML entity that specifies both name and value of an attribute.
attr_value
The value of a new attribute
Return Types
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.
Examples
Example 24.537. Different modes of calling XMLAddAttribute
The sample procedure contains three calls of
XMLAddAttribute with different values of
mode , for "insert into", "insert soft" and "insert
replacing" behaviour.
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.