SetAttribute

For this syntax	See
SetAttribute(pbdom_attribute pbdom_attribute_ref)	SetAttribute Syntax 1
SetAttribute(string strName, string strValue)	SetAttribute Syntax 2
SetAttribute(string strName, string strValue, string strNamespacePrefix, string strNamespaceUri, boolean bVerifyNamespace)	SetAttribute Syntax 3

SetAttribute Syntax 1

Description

Adds a predefined PBDOM_ATTRIBUTE object to a PBDOM_ELEMENT object. Any existing attribute with the same name and namespace URI is overwritten.

Syntax

pbdom_element_name.SetAttribute(pbdom_attribute pbdom_attribute_ref)

Argument	Description
pbdom_element_name	The name of a PBDOM_ELEMENT object
pbdom_attribute_ref	The PBDOM_ATTRIBUTE object to be set for this PBDOM_ELEMENT object

Return value

PBDOM_ELEMENT. The PBDOM_ELEMENT object modified to contain the specified PBDOM_ATTRIBUTE.

Throws

EXCEPTION_INVALID_ARGUMENT -- The input PBDOM_ATTRIBUTE is invalid. This can happen if it has not been initialized properly or it is a null object reference.

EXCEPTION_USE_OF_UNNAMED_PBDOM_OBJECT -- The input PBDOM_ATTRIBUTE has not been given a user-defined name.

EXCEPTION_PBDOM_OBJECT_ALREADY_HAS_OWNER -- The input PBDOM_ATTRIBUTE already has an owner element.

Examples

The SetAttribute method is invoked for the following element:
```
<image></image>
```
The SetAttribute method is invoked from the following PowerScript code, where elem_image represents the image element from the preceding XML:
```
attr_src.SetName("src")
attr_src.SetText("logo.gif")
elem_image.SetAttribute(attr_src)
```
The following XML results:
```
<image src="logo.gif"></image>
```
The following example demonstrates the impact of setting a PBDOM_ATTRIBUTE for a PBDOM_ELEMENT object where the PBDOM_ELEMENT object already contains an attribute of the same name and namespace URI as the input PBDOM_ATTRIBUTE.

The example creates a PBDOM_DOCUMENT based on the following document:

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

Then it creates a PBDOM_ATTRIBUTE object and sets its name to a and its prefix and URI to pre2 and http://www.pre.com. The bVerifyNamespace argument is set to false because this PBDOM_ATTRIBUTE has not been assigned an owner PBDOM_ELEMENT object yet, so that the verification for a predeclared namespace would fail. The text value is set to 456.

The child1 element already contains an attribute named a that belongs to the namespace http://www.pre.com, as indicated by the prefix pre1. The new PBDOM_ATTRIBUTE uses the prefix pre2, but it represents the same namespace URI, so setting the new PBDOM_ATTRIBUTE to child1 successfully replaces the existing pre1:a with the new PBDOM_ATTRIBUTE pre2:a.

PBDOM_BUILDER pbdom_buildr
PBDOM_DOCUMENT pbdom_doc
PBDOM_ATTRIBUTE pbdom_attr
string strXML = "<root xmlns:pre1=~"http://www.pre.com~" xmlns:pre2=~"http://www.pre.com~"><child1 pre1:a=~"123~"/></root>"

try
  pbdom_buildr = Create PBDOM_BUILDER
  pbdom_doc = pbdom_buildr.BuildFromString (strXML)
  
  // Create a PBDOM_ATTRIBUTE and set its properties
  pbdom_attr = Create PBDOM_ATTRIBUTE
  pbdom_attr.SetName ("a")
  pbdom_attr.SetNamespace ("pre2", &
     "http://www.pre.com", false)
  pbdom_attr.SetText("456")
  
  // Attempt to obtain the child1 element and 
  // set the new attribute to it
  pbdom_doc.GetRootElement(). &
    GetChildElement("child1").SetAttribute(pbdom_attr)
  
  pbdom_doc.SaveDocument &
     ("pbdom_elem_set_attribute_1.xml")

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

When saved and converted to an XML document, the document looks like the following:

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

Usage

This method allows the caller to add a predefined PBDOM_ATTRIBUTE object to a PBDOM_ELEMENT object. If this PBDOM_ELEMENT object already contains an existing attribute with the same name and namespace URI as the input PBDOM_ATTRIBUTE, the existing attribute is replaced by the input PBDOM_ATTRIBUTE.

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

See also

SetAttribute Syntax 2

SetAttribute Syntax 3

SetAttributes

SetAttribute Syntax 2

Description

Adds a PBDOM_ATTRIBUTE object and its value to a PBDOM_ELEMENT object. Any existing attribute with the same name and namespace URI is overwritten.

Syntax

pbdom_element_name.SetAttribute(string strName, string strValue)

Argument	Description
pbdom_element_name	The name of a PBDOM_ELEMENT object
strName	The name of the PBDOM_ATTRIBUTE to be added
strValue	The value of the PBDOM_ATTRIBUTE to be added

Return value

PBDOM_ELEMENT. The PBDOM_ELEMENT object modified to contain the specified PBDOM_ATTRIBUTE with the specified value.

Throws

EXCEPTION_INVALID_ARGUMENT -- One or both of the input strings are invalid. This can happen if either or both strings have not been initialized properly or are null.

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

EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE -- This PBDOM_ELEMENT object's internal implementation is null. The occurrence of this exception is rare but can take place if severe memory corruption occurs.

EXCEPTION_INVALID_NAME -- An invalid name for the attribute is supplied.

EXCEPTION_INVALID_STRING -- An invalid string for the attribute value is supplied.

Examples

The SetAttribute method is invoked for the following XML element:
```
<code>0789725045</code>
```
The SetAttribute method is invoked from the following PowerScript statement, where elem_code represents the code element:
```
elem_code.SetAttribute("type", "ISBN")
```
The following XML element results:
```
<code type="ISBN">0789725045</code>
```
The following example demonstrates the effect of setting an attribute for a PBDOM_ELEMENT object when the PBDOM_ELEMENT object already contains an attribute of the same name. The example creates a PBDOM_DOCUMENT based on the following document:
```
<root xmlns:pre1="http://www.pre.com">
   <child1 pre1:a="123" b="456"/>
</root>
```
The child1 element already contains an attribute named b with value 456. Calling the SetAttribute method with name b and value 789 creates a new attribute for child1 that replaces the original b attribute.
```
PBDOM_BUILDER     pbdom_buildr
PBDOM_DOCUMENT   pbdom_doc
string strXML = "<root xmlns:pre1=~"http://www.pre.com~" ><child1 pre1:a=~"123~" b=~"456~"/></root>"

try
  pbdom_buildr = Create PBDOM_BUILDER
  pbdom_doc = pbdom_buildr.BuildFromString (strXML)
  pbdom_doc.GetRootElement(). &
    GetChildElement("child1").SetAttribute("b", "789")
catch (PBDOM_EXCEPTION except)
  MessageBox ("PBDOM_EXCEPTION", except.GetMessage())
end try
```
After the PBDOM_DOCUMENT object is saved and converted to XML, the XML document looks like the following:
```
<root xmlns:pre1="http://www.pre.com">
   <child1 pre1:a="123" b="789"/>
</root>
```

Usage

This method allows the caller to add an attribute/value pair to a PBDOM_ELEMENT object. If the PBDOM_ELEMENT object already contains an existing attribute that has the same name as the input name and that belongs to no namespace, the original attribute is removed from this PBDOM_ELEMENT object and a new one (corresponding to the specified attribute name and value) is created and set in its place.

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

See also

SetAttribute Syntax 1

SetAttribute Syntax 3

SetAttributes

SetAttribute Syntax 3

Description

Adds an attribute/value pair to a PBDOM_ELEMENT object. The attribute namespace is specified, and any existing attribute of the same name and namespace URI is removed.

Syntax

pbdom_element_name.SetAttribute(string strName, string strValue, string strNamespacePrefix, string strNamespaceUri, boolean bVerifyNamespace)

Argument	Description
pbdom_element_name	The name of a PBDOM_ELEMENT object
strName	The name of the PBDOM_ATTRIBUTE to be added
strValue	The value of the PBDOM_ATTRIBUTE to be added
strNamespacePrefix	The prefix of the namespace to which the PBDOM_ATTRIBUTE belongs
strNamespaceUri	The URI of the namespace to which the PBDOM_ATTRIBUTE belongs
bVerifyNamespace	Specifies whether or not the method should verify the existence of an in-scope namespace declaration for the given prefix and URI

Return value

Long.

Returns 0 if no namespace verification error occurs and -1 if no in-scope namespace declaration exists for the given prefix and URI settings.

Throws

EXCEPTION_INVALID_ARGUMENT -- If any of the arguments is invalid. This can happen if any of the input strings has been set to null using the PowerScript SetNull function.

EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE -- This PBDOM_ELEMENT object's internal implementation is null. The occurrence of this exception is rare but can take place if severe memory corruption occurs.

EXCEPTION_INVALID_NAME -- The input namespace prefix or the URI, or their combination, is not valid. This will happen if:

The namespace prefix is an empty string and the URI is not an empty string. If both are empty strings, the NONAMESPACE namespace is being specified and this prefix/URI combination is correct.
The namespace prefix is xmlns and the URI is not http://www.w3.org/2000/xmlns/. This namespace prefix/URI pair is unique and exclusive and cannot be used separately. The use of this pair signifies a namespace declaration.
The namespace prefix string is invalid. That is, it does not conform to the W3C "Namespaces in XML" specifications for the name of a prefix.
The namespace URI string is invalid. That is, it does not conform to the W3C specifications for a URI string.

EXCEPTION_MEMORY_ALLOCATION_FAILURE -- If there has been any memory allocation failure during this method call.

Examples

The SetAttribute method is invoked for the following XML element:
```
<code>0789725045</code>
```
The SetAttribute method is invoked from the following PowerScript statement, where elem_code represents the code element:
```
elem_code.SetAttribute("type", "ISBN", "ns", & "http://www.books.com/codes", false)
```
The following XML element results:
```
<code ns:type="ISBN">0789725045</code>
```
The following example demonstrates the effect of setting an attribute with a particular name and namespace URI for an element that already contains an existing attribute with the same name and namespace URI. It creates a PBDOM_DOCUMENT based on the following XML:
```
<root xmlns:pre1="http://www.pre.com" xmlns:pre2="http://www.pre.com">
   <child1 pre1:a="123"/>
</root>
```
The child1 element already contains an attribute named a that belongs to the namespace http://www.pre.com, as indicated by the pre1 prefix. The call to SetAttribute attempts to set an attribute for child1 with the same name, a, but with the namespace prefix pre2.

The last parameter, bVerifyNamespace, is set to true. This tells the SetAttribute method to check first to see if an in-scope namespace declaration for pre2 and http://www.pre.com exists. An in-scope declaration for this namespace prefix/URI pair does exist, and so the verification succeeds.

The original pre1:a attribute is removed from the child1 element and a new attribute pre2:a, belonging to the same namespace and with the value 456, is created and set in its place. The new attribute replaces the original attribute, instead of being set as an additional attribute, because both attributes have the same URI.
```
PBDOM_BUILDER     pbdom_buildr
PBDOM_DOCUMENT   pbdom_doc
string strXML = "<root xmlns:pre1=~"http://www.pre.com~" xmlns:pre2=~"http://www.pre.com~"><child1 pre1:a=~"123~"/></root>"

try
  pbdom_buildr = Create PBDOM_BUILDER
  pbdom_doc = pbdom_buildr.BuildFromString (strXML)

pbdom_doc.GetRootElement().GetChildElement("child1").SetAttribute("a", "456", "pre2", "http://www.pre.com", true)
  
catch (PBDOM_EXCEPTION pbdom_except)
  MessageBox ("PBDOM_EXCEPTION", pbdom_except.GetMessage())
end try
```

Usage

This method allows the caller to add an attribute/value pair to a PBDOM_ELEMENT object.

The parameter bVerifyNamespace, when set to true, instructs the method to perform a thorough search up the DOM node tree, starting at the current PBDOM_ELEMENT object, to check for an in-scope namespace declaration for the given prefix and URI. If a namespace declaration is not found, no attribute is created. If a namespace declaration is found, an attribute is created.

If the bVerifyNamespace parameter is set to false, no verification search is performed, and the method always returns 0.

If the PBDOM_ELEMENT object already contains an existing attribute that has the same name as the input name and the same namespace URI as the input namespace URI, the original attribute is replaced with a new one with the same name and URI.

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

See also

SetAttribute Syntax 1

SetAttribute Syntax 2

SetAttributes