PowerBuilder Extension Reference
PBDOM_ATTRIBUTE

Description

Sets the local name of the PBDOM_ATTRIBUTE object.

Syntax

pbdom_attribute_name.SetName(string strName)

Return value

Boolean.

Returns true if the local name of the PBDOM_ATTRIBUTE has been changed and false otherwise.

Throws

EXCEPTION_INVALID_NAME -- If the input name is not valid for a local name of a PBDOM_ATTRIBUTE. This happens if the name is an empty string, if the name contains a namespace prefix, or if the name is already the name of an existing attribute of the owning element.

EXCEPTION_MEMORY_ALLOCATION_FAILURE -- Insufficient memory was encountered while executing this method.

Examples

This example shows how to set the local name of a PBDOM_ATTRIBUTE and demonstrates that the namespace information it contains is not affected by a change in name.

The sample code first builds a PBDOM_DOCUMENT from a string that contains XML that has a single root element with a namespace declaration and an attribute a.

The GetAttribute method obtains the attribute a, which does not belong to a namespace, and the returned PBDOM_ATTRIBUTE is tested and should be valid. After a call to SetName, the code confirms the name change and tests that the namespace information remains the same (the namespace prefix and URI are both still empty strings):

PBDOM_BUILDER     pbdom_buildr
PBDOM_DOCUMENT    pbdom_doc
PBDOM_ATTRIBUTE   pbdom_attr
string strXML = "<root xmlns:n1=~"http://www.n.com~" a=~"123~"/>"

try
  pbdom_buildr = Create PBDOM_BUILDER 
  pbdom_doc = pbdom_buildr.BuildFromString (strXML)
  
  pbdom_attr = pbdom_doc.GetRootElement(). &
     GetAttribute("a")
  
  if (IsValid(pbdom_attr)) then
    MessageBox ("Pass", &
      "PBDOM_ATTRIBUTE a is retrieved via the " &
      + "NONAMESPACE GetAttribute() method.")
  else
    MessageBox ("Fail", &
      "PBDOM_ATTRIBUTE should have been retrievable.")
  end if
  
  pbdom_attr.SetName ("b")
  
  if pbdom_attr.GetName() = "b" then
    MessageBox ("Pass", "Name has been changed to b.")
  else
    MessageBox ("Fail", &
      "Name should have been changed to b.")
  end if
  
  if pbdom_attr.GetNamespacePrefix() = "" then
    MessageBox ("Pass", &
      "Namespace Prefix is an empty string.")
  else
    MessageBox ("Fail", "Namespace Prefix is : " &
      + pbdom_attr.GetNamespacePrefix() &
      + " which is incorrect.")
  end if

  if pbdom_attr.GetNamespaceURI() = "" then
    MessageBox ("Pass", &
      "Namespace URI is an empty string.")
  else
    MessageBox ("Fail", "Namespace URI is : " &
      + pbdom_attr.GetNamespaceURI() &
      + " which is incorrect.")
  end if
  
catch(PBDOM_EXCEPTION pbdom_e)
  MessageBox("PBDOM_EXCEPTION", pbdom_e.GetMessage())
end try

Usage

This method sets the local name of the PBDOM_ATTRIBUTE. When a PBDOM_ATTRIBUTE is first created, it has no name and the namespace information is by default set to the NONAMESPACE namespace. (Its NS Prefix and URI are both empty strings.)

The SetName method is used to set the local name of the PBDOM_ATTRIBUTE. The SetNamespace method is used to set the Namespace Prefix and URI of the PBDOM_ATTRIBUTE.

If a PBDOM_ATTRIBUTE is retrieved programmatically from a parsed document, then the name and namespace information of the PBDOM_ATTRIBUTE are inherited from the referred attribute of the parsed document. The name and namespace information of the PBDOM_ATTRIBUTE, however, can still be modified using the SetName and SetNamespace methods.

Note that according to the W3C "Namespaces in XML" specification, when the SetName method is invoked on a PBDOM_ATTRIBUTE, if the PBDOM_ATTRIBUTE (PBDOM_ATTRIBUTE 1) has an owner PBDOM_ELEMENT that contains an existing PBDOM_ATTRIBUTE (PBDOM_ATTRIBUTE 2) with the same name (to be set for PBDOM_ATTRIBUTE 1) and namespace URI as PBDOM_ATTRIBUTE 1, the EXCEPTION_INVALID_NAME exception will be thrown.

See also

GetName

SetOwnerElementObject