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
|
1 |
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 |
|
strValue |
The value of the PBDOM_ATTRIBUTE to be |
|
strNamespacePrefix |
The prefix of the namespace to which the |
|
strNamespaceUri |
The URI of the namespace to which the |
|
bVerifyNamespace |
Specifies whether or not the method should verify |
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:1<code>0789725045</code>The SetAttribute method is invoked from the following
PowerScript statement, where elem_code represents the code
element:1elem_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:123<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.12345678910111213PBDOM_BUILDER pbdom_buildrPBDOM_DOCUMENT pbdom_docstring strXML = "<root xmlns:pre1=~"http://www.pre.com~" xmlns:pre2=~"http://www.pre.com~"><child1 pre1:a=~"123~"/></root>"trypbdom_buildr = Create PBDOM_BUILDERpbdom_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