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
Example24.497.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.