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 parameter 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.
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.
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.