PowerBuilder Extension Reference
PBDOM_ATTRIBUTE

Description

Sets the namespace for a PBDOM_ATTRIBUTE object based on the specified namespace prefix and URI.

Syntax

pbdom_attribute_name.SetNamespace(string strNamespacePrefix, string stringstrNamespaceUri, boolean bVerifyNamespace)

Return value

Long.

Returns 0 if namespace information was set successfully and -1 if no in-scope namespace matching the input prefix and URI exists.

Throws

EXCEPTION_INVALID_NAME -- If the input namespace prefix or the URI or the combination of prefix and URI is not valid. This occurs if:

EXCEPTION_INVALID_ARGUMENT -- If the input namespace prefix string or the URI string has been set to null.

EXCEPTION_MEMORY_ALLOCATION_FAILURE -- If there is insufficient memory to allocate for internal strings.

EXCEPTION_INTERNAL_XML_ENGINE_ERROR -- If some internal error occurred in the XML engine.

Examples

This example demonstrates how to set the namespace prefix and URI for a PBDOM_ATTRIBUTE. It creates a PBDOM_DOCUMENT based on the following XML document:

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

The namespace http://www.pre.com, which has the prefix pre1, is defined in the root element. The child element child1 has an attribute a that belongs to the declared namespace and an attribute b that does not belong to a namespace.

The example uses GetAttribute to get and store the attribute b in pbdom_attr, then calls SetNamespace on pbdom_attr, specifying the strings "pre1" and "http://www.pre.com" as the prefix and URI, and setting the bVerifyNamespace parameter to true. This tells SetNamespace to check first to see if the owner element of b or the owner element's ancestor elements contain a namespace declaration for the pre1/http://www.pre.com namespace prefix/URI pair.

The search for this prefix/URI pair succeeds because the root element contains such a namespace declaration.

PBDOM_BUILDER   pbdom_buildr
PBDOM_DOCUMENT   pbdom_doc
PBDOM_ATTRIBUTE   pbdom_attr
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_attr = pbdom_doc.GetRootElement().GetChildElement("child1").GetAttribute("b", "", "")
  
  pbdom_attr.SetNamespace("pre1", "http://www.pre.com", true)
  
  MessageBox ("NS Prefix", pbdom_attr.GetNamespacePrefix())
  MessageBox ("NS URI", pbdom_attr.GetNamespaceURI())
  MessageBox ("Name", pbdom_attr.getName())
  MessageBox ("Text", pbdom_attr.getText())
  
  pbdom_doc.SaveDocument ("ns.xml")
  
catch (PBDOM_EXCEPTION pbdom_except)
  MessageBox ("PBDOM_EXCEPTION", pbdom_except.GetMessage())
end try

There is no other attribute inside child1 that has the name b and that also belongs to the http://www.pre.com namespace, so the SetNamespace method succeeds. When serialized, the PBDOM_DOCUMENT looks like this:

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

Usage

This method sets this PBDOM_ATTRIBUTE object's namespace based on the input prefix and URI. The input prefix can be an empty string, but the input URI cannot be an empty string unless the prefix is also an empty string.

If the input prefix and URI are both empty strings, the PBDOM_ATTRIBUTE has no namespace. The bVerifyNamespace parameter tells the method whether to search for an in-scope namespace declaration that matches the input namespace prefix and URI.

As required by the W3C specification on "Namespaces in XML," if the current PBDOM_ATTRIBUTE has an owner PBDOM_ELEMENT that contains an existing PBDOM_ATTRIBUTE that has the same name as the current PBDOM_ATTRIBUTE and the same namespace URI as is to be set for the current PBDOM_ATTRIBUTE, the EXCEPTION_INVALID_NAME exception is thrown.

See also

GetName

GetNamespacePrefix

GetNamespaceUri

GetQualifiedName

SetName