PowerBuilder Extension Reference
PBDOM_ELEMENT

Description

Sets the attributes for the DOM element represented by the current PBDOM_ELEMENT object.

Syntax

pbdom_element_name.SetAttributes(pbdom_attribute pbdom_attribute_array[])

Return value

PBDOM_ELEMENT. The PBDOM_ELEMENT object modified.

Throws

EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE -- The internal implementation of this PBDOM_ELEMENT object or one of the PBDOM_ATTRIBUTE array items is null. This exception is rare but can take place if severe memory corruption occurs.

EXCEPTION_INVALID_ARGUMENT -- One of the PBDOM_ATTRIBUTE array items is null.

EXCEPTION_INVALID_NAME -- If two or more PBDOM_ATTRIBUTEs in the array contain the same name and namespace URI.

EXCEPTION_USE_OF_UNNAMED_PBDOM_OBJECT -- One of the PBDOM_ATTRIBUTE array items has not been named.

EXCEPTION_PBDOM_OBJECT_ALREADY_HAS_OWNER -- One of the PBDOM_ATTRIBUTE array items already has an owner PBDOM_ELEMENT object.

Examples

This example demonstrates setting the attributes of a PBDOM_ELEMENT object using an array of PBDOM_ATTRIBUTE objects. It builds a PBDOM_DOCUMENT based on the following XML:

<root xmlns:pre1="http://www.pre.com">
   <child1 pre1:a="123"/>
</root>

The code creates an array of three PBDOM_ATTRIBUTE objects with names a, b, and c, and sets their namespace prefixes and URIs to pre1 and http://www.pre.com. The call to SetAttributes attempts to set the attributes of child1 using the PBDOM_ATTRIBUTEs of this array. When you save PBDOM_DOCUMENT and convert it to an XML document, the result is:

<root xmlns:pre1="http://www.pre.com">
   <child1 pre1:a="456" pre1:b="456" pre1:c="456" />
</root>

Although child1 originally contained the pre1:a attribute, and the PBDOM_ATTRIBUTE array also contained an item with name a within the namespace URI http://www.pre.com, no exception is thrown. The original pre1:a attribute is replaced by the PBDOM_ATTRIBUTE array item with name a within the namespace URI http://www.pre.com.

PBDOM_BUILDER     pbdom_buildr
PBDOM_DOCUMENT    pbdom_doc
PBDOM_ATTRIBUTE   pbdom_attr_array[]
string            Name[]
long              l = 0
string strXML = "<root xmlns:pre1=~"http://www.pre.com~"><child1 pre1:a=~"123~"/></root>"

try
  pbdom_buildr = Create PBDOM_BUILDER
  pbdom_doc = pbdom_buildr.BuildFromString (strXML)
  
  Name[1] = "a"
  Name[2] = "b"
  Name[3] = "c"

  for l = 1 to 3
    pbdom_attr_array[l] = Create PBDOM_ATTRIBUTE
    pbdom_attr_array[l].SetName (Name[l])
    pbdom_attr_array[l].SetNamespace ("pre1", &
      "http://www.pre.com", false)
    pbdom_attr_array[l].SetText("456")
  next 

    pbdom_doc.GetRootElement().GetChildElement &
      ("child1").SetAttributes(pbdom_attr_array)
    pbdom_doc.SaveDocument ("set_attributes.xml")

catch (PBDOM_EXCEPTION except)
  MessageBox ("PBDOM_EXCEPTION", except.GetMessage())
end try

Usage

This method sets the attributes of the DOM element represented by this PBDOM_ELEMENT object. The supplied array should contain only objects of type PBDOM_ATTRIBUTE.

When all objects in the supplied array are legal and before the new attributes are added, all old attributes have their parentage set to null (no parent) and the old attribute list is cleared from this PBDOM_ELEMENT object. This has the effect that any active attribute list (previously obtained with a call to GetAttributes) also changes to reflect the new situation with the old attributes. In addition, all PBDOM_ATTRIBUTEs in the supplied array have their parentage set to this current PBDOM_ELEMENT object.

Passing an empty array clears the existing attributes of this PBDOM_ELEMENT object.

This method fails and an exception is thrown if the PBDOM_ATTRIBUTE array contains two or more PBDOM_ATTRIBUTEs with the same name and namespace URI.

No exception is thrown if this PBDOM_ELEMENT object contains an existing attribute whose name and namespace URI matches one of the PBDOM_ATTRIBUTE array items. All the existing attributes of this PBDOM_ELEMENT object are removed, so it does not matter whether any existing attribute matches any of the PBDOM_ATTRIBUTE items in the array in terms of name and namespace URI.

In the event of an exception, the original attributes of the PBDOM_ELEMENT object remain unchanged, and the PBDOM_ATTRIBUTEs in the supplied array are not altered.

If any PBDOM_ATTRIBUTE has been created to represent any original attribute, it is still valid, but the attribute it represents has been detached from the original owner element. Calling GetOwnerElementObject on this PBDOM_ATTRIBUTE returns a null value.

See also

GetAttribute

GetAttributes

GetAttributeValue

HasAttributes

SetAttribute