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