PBDOM_ELEMENT:
SetAttribute Syntax 3 method
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
|
1 |
<span>pbdom_element_name.</span>SetAttribute(string <span>strName</span>, string <span>strValue</span>, string <span>strNamespacePrefix</span>, string <span>strNamespaceUri</span>, boolean <span>bVerifyNamespace</span>) |
|
Argument |
Description |
|---|---|
|
pbdom_element_name |
The name of a PBDOM_ELEMENT |
|
strName |
The name of the PBDOM_ATTRIBUTE |
|
strValue |
The value of the PBDOM_ATTRIBUTE |
|
strNamespacePrefix |
The prefix of the namespace to which |
|
strNamespaceUri |
The URI of the namespace to which the PBDOM_ATTRIBUTE |
|
bVerifyNamespace |
Specifies whether or not the method should |
Return Values
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:
|
1 |
<code>0789725045</code> |
The SetAttribute method is invoked from
the following PowerScript statement, where elem_code represents
the code element:
|
1 |
elem_code.SetAttribute("type", "ISBN", "ns", & "http://www.books.com/codes", false) |
The following XML element results:
|
1 |
<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:
|
1 |
<root xmlns:pre1="http://www.pre.com" xmlns:pre2="http://www.pre.com"><br>   <child1 pre1:a="123"/><br></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.
|
1 |
PBDOM_BUILDER     pbdom_buildr<br>PBDOM_DOCUMENT   pbdom_doc<br>string strXML = "<root xmlns:pre1=~"http://www.pre.com~" xmlns:pre2=~"http://www.pre.com~"><child1 pre1:a=~"123~"/></root>"<br> <br>try<br>  pbdom_buildr = Create PBDOM_BUILDER<br>  pbdom_doc = pbdom_buildr.BuildFromString (strXML)<br> <br>  <br>   |
|
1 |
pbdom_doc.GetRootElement().GetChildElement("child1").SetAttribute("a", "456", "pre2", "http://www.pre.com", true)<br>  <br>catch (PBDOM_EXCEPTION pbdom_except)<br>  MessageBox ("PBDOM_EXCEPTION", pbdom_except.GetMessage())<br>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.