PowerBuilder Extension Reference
PBDOM_ATTRIBUTE Class

Description

Adds the input PBDOM_OBJECT as a child of the PBDOM_ATTRIBUTE.

Syntax

pbdom_attribute_name.AddContent( pbdom_object pbdom_object_ref)

Return value

PBDOM_OBJECT. The PBDOM_ATTRIBUTE modified.

Throws

EXCEPTION_INAPPROPRIATE_USE_OF_PBDOM_OBJECT  -- If the input PBDOM_OBJECT is not a PBDOM_TEXT or PBDOM_ENTITYREFERENCE object.

EXCEPTION_USE_OF_UNNAMED_OBJECT  -- If the input PBDOM_OBJECT has not been given a user-defined name.

Usage

pbdom_object_ref must be a reference to a PBDOM_TEXT or PBDOM_ENTITYREFERENCE object.

See also

GetContent

InsertContent

RemoveContent

SetContent

Description

Creates a clone of the PBDOM_ATTRIBUTE object.

Syntax

pbdom_attribute_name.Clone(boolean bDeep)

Return value

PBDOM_OBJECT. A clone of this PBDOM_ATTRIBUTE returned as a PBDOM_OBJECT.

Throws

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

EXCEPTION_USE_OF_UNNAMED_PBDOM_OBJECT  -- If this PBDOM_ATTRIBUTE does not have or has not been assigned a user-defined name.

Examples

This example creates a PBDOM_DOCUMENT from the string <abc My_Attr="An Attribute"/>, gets the attribute from the root element, and creates a shallow clone and a deep clone from it. For the shallow clone, an empty string is returned in the message box. For the deep clone, the string An Attribute is returned:

PBDOM_BUILDER     pbdom_buildr
PBDOM_DOCUMENT    pbdom_doc
PBDOM_ATTRIBUTE   pbdom_attr
PBDOM_ATTRIBUTE   pbdom_attr_clone_deep
PBDOM_ATTRIBUTE   pbdom_attr_clone_shallow
string strXML = "<abc My_Attr=~"An Attribute~"/>"

TRY
  pbdom_buildr = Create PBDOM_BUILDER
  pbdom_doc = pbdom_buildr.BuildFromString(strXML)
  pbdom_attr = pbdom_doc.GetRootElement(). &
     GetAttribute("My_Attr")
  pbdom_attr_clone_shallow = pbdom_attr.Clone(false)
  MessageBox ("Shallow Attribute Clone Text", &
     pbdom_attr_clone_shallow.GetText())
  pbdom_attr_clone_deep = pbdom_attr.Clone(true)
  MessageBox ("Deep Attribute Clone Text", &
     pbdom_attr_clone_deep.GetText())

CATCH (PBDOM_EXCEPTION pbdom_except)
  MessageBox ("PBDOM_EXCEPTION", &
     pbdom_except.GetMessage())
END TRY

Usage

The Clone method creates and returns a duplicate of the current PBDOM_ATTRIBUTE.

If a shallow clone is requested, this method clones the original PBDOM_ATTRIBUTE together with its namespace information values. The subtree of child PBDOM_TEXT and/or PBDOM_ENTITYREFERENCE objects is not cloned.

If a deep clone is requested, this method additionally recursively clones the subtree under the PBDOM_ATTRIBUTE. This subtree consists of a combination of PBDOM_TEXT and PBDOM_ENTITYREFERENCE objects that are the legal children of a PBDOM_ATTRIBUTE.

A PBDOM_ATTRIBUTE clone has no parent. However, the clone resides in the same PBDOM_DOCUMENT as its original, and if the original PBDOM_ATTRIBUTE is standalone, the clone is standalone.

Description

Detaches a PBDOM_ATTRIBUTE from its owner PBDOM_OBJECT, a PBDOM_ELEMENT.

Syntax

pbdom_attribute_name.Detach()

Return value

PBDOM_OBJECT. The PBDOM_ATTRIBUTE object detached from its owner object.

Throws

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

Examples

The Detach method can be used to manipulate an XML document as follows:

PBDOM_BUILDER          pbdombuilder_new
PBDOM_DOCUMENT         pbdom_doc
PBDOM_ATTRIBUTE        pbdom_attr
PBDOM_ELEMENT          pbdom_elem
string strXML = "<abc  My_Attr=~"My Attribute Value~"><data>Data</data></abc>"


TRY
  pbdombuilder_new = Create PBDOM_Builder
  pbdom_doc = pbdombuilder_new.BuildFromString (strXML)

  pbdom_attr = pbdom_doc.GetRootElement(). &
     GetAttribute("My_Attr")
  pbdom_attr.Detach()

  pbdom_elem = pbdom_doc.GetRootElement(). &
     GetChildElement("data")
  pbdom_elem.SetAttribute (pbdom_attr)

  Destroy pbdombuilder_new
  Destroy pbdom_doc

CATCH (PBDOM_Exception except)
   MessageBox ("Exception Occurred", except.Text)
END TRY

Here, the PBDOM_Builder BuildFromString method is used to create the following PBDOM_DOCUMENT object, pbdom_doc, using an XML string:

<abc  My_Attr="My Attribute Value">
   <data>Data </data>
</abc>

The GetAttribute method is used to obtain the attribute from the root element of pbdom_doc. This value is assigned to the PBDOM_ATTRIBUTE object pbdom_attr. The pbdom_attr object is detached from its parent element, and the data element is obtained from pbdom_doc using the GetChildElement method. The data element is then assigned to the PBDOM_ELEMENT object pbdom_elem. The attribute assigned to pbdom_attr is assigned to pbdom_elem, yielding the following modified pbdom_doc:

<abc>
   <data My_Attr="My Attribute Value">Data</data>
</abc>

Usage

If the PBDOM_ATTRIBUTE object has no owner PBDOM_ELEMENT, the Detach method does nothing.

Description

Tests for equality between the supplied PBDOM_OBJECT and the PBDOM_ATTRIBUTE from which the method is invoked.

Syntax

pbdom_attribute_name.Equals(pbdom_object pbdom_object_ref)

Return value

Boolean.

Returns true if the current PBDOM_ATTRIBUTE is equivalent to the input PBDOM_OBJECT and false otherwise.

Throws

EXCEPTION_USE_OF_UNNAMED_PBDOM_OBJECT  -- If this PBDOM_ATTRIBUTE does not have or has not been assigned a user-defined name.

EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE  -- if the input PBDOM_OBJECT is not a reference to an object derived from PBDOM_OBJECT.

Examples

A newly created PBDOM_ATTRIBUTE is cloned, and a reference to this clone is assigned to pbdom_attr_2. The Equals method tests for equality between the cloned PBDOM_ATTRIBUTE pbdom_attr_clone and the reference to it, pbdom_attr_2. A message box displays the result returned from the Equals method.

Here the Equals method returns true.

Usage

Note that the clone of a PBDOM_ATTRIBUTE is not considered equal to itself.

Description

Obtains the value of a PBDOM_ATTRIBUTE object in boolean form.

Syntax

pbdom_attribute_name.GetBooleanValue()

Return value

Boolean.

The following table lists the PBDOM_ATTRIBUTE string values that are accepted as boolean and the corresponding return values from the GetBooleanValue method.

Strings are treated without case sensitivity. If no conversion can occur, the GetBooleanValue method throws an exception.

Throws

EXCEPTION_DATA_CONVERSION -- If data conversion fails.

Examples

The GetBooleanValue can be used to evaluate a PBDOM_ATTRIBUTE object as follows:

PBDOM_BUILDER          pbombuilder_new
PBDOM_DOCUMENT         pbdom_doc
PBDOM_ATTRIBUTE        pbdom_attr
string strXML = "<abc My_Boolean_Attribute =~"on~"><data An_Attribute=~"Some Text~">Data</data></abc>"

TRY
  pbdombuilder_new = Create PBDOM_Builder
  pbdom_doc = pbdombuilder_new.BuildFromString (strXML)

  pbdom_attr = pbdom_doc.GetRootElement(). &
     GetAttribute("My_Boolean_Attribute")

  MessageBox ("Boolean Value", &
     string(pbdom_attr.GetBooleanValue()))


  Destroy pbdombuilder_new
  Destroy pbdom_doc
CATCH (PBDOM_Exception except)
  MessageBox ("Exception Occurred", except.Text)
END TRY

The BuildFromString method is used to create a PBDOM_DOCUMENT object, pbdom_doc, using an XML string. The attribute value of the root element of pbdom_doc is assigned to the PBDOM_ATTRIBUTE object pbdom_attr. The attribute value, on, is evaluated with the GetBooleanValue method. A message box reports the return value of the GetBooleanValue method.

See also

SetBooleanValue

Description

Returns an array of PBDOM_OBJECT objects that are the children of the PBDOM_ATTRIBUTE. The children of a PBDOM_ATTRIBUTE can be only PBDOM_TEXT or PBDOM_ENTITYREFERENCE objects.

Syntax

pbdom_attribute_name.GetContent(ref pbdom_object pbdom_object_array[ ])

Return value

Boolean.

This method always returns true.

See also

AddContent

InsertContent

RemoveContent

SetContent

Description

Returns the value of a PBDOM_ATTRIBUTE object as type Date.

Syntax

pbdom_attribute_name.GetDateValue(string strDateFormat)

The value of the strDateFormat parameter can use slashes or colons as delimiters. The following table illustrates characters with special meaning in strDateFormat.

Return value

Date.

Throws

EXCEPTION_DATA_CONVERSION -- If data conversion fails.

See also

SetDateValue

Description

Returns the value of a PBDOM_ATTRIBUTE object as type DateTime.

Syntax

pbdom_attribute_name.GetDateTimeValue(stringstrDateFormat, string strTimeFormat)

The value of the strDateFormat parameter can use slashes or colons as delimiters. The following table illustrates characters that have special meaning in strDateFormat.

The value of the strTimeFormat parameter can use slashes or colons as delimiters. The following table illustrates characters that have special meaning in strTimeFormat.

Return value

DateTime.

Throws

EXCEPTION_DATA_CONVERSION -- If data conversion fails.

See also

SetDateTimeValue

Description

Returns the value of a PBDOM_ATTRIBUTE object in double form.

Syntax

pbdom_attribute_name.GetDoubleValue()

Return value

Double.

Throws

EXCEPTION_DATA_CONVERSION -- If data conversion fails.

Usage

Throws exception_data_conversion if the method fails to convert data.

See also

SetDoubleValue

Description

Returns the value of a PBDOM_ATTRIBUTE object as type int.

Syntax

pbdom_attribute_name.GetIntValue()

Return value

Int.

Throws

EXCEPTION_DATA_CONVERSION -- If data conversion fails.

See also

SetIntValue

Description

Returns the value of a PBDOM_ATTRIBUTE object as type long.

Syntax

pbdom_attribute_name.GetLongValue()

Return value

Long.

Throws

EXCEPTION_DATA_CONVERSION -- If data conversion fails.

See also

SetLongValue

Description

Retrieves the local name of the PBDOM_ATTRIBUTE object.

Syntax

pbdom_attribute_name.GetName()

Return value

String.

Throws

EXCEPTION_USE_OF_UNNAMED_PBDOM_OBJECT  -- If this PBDOM_ATTRIBUTE does not have or has not been assigned a user-defined name.

Examples

The namespace prefix is not part of the return string.

Usage

For an XML attribute that appears in the form [namespace_prefix]:[attribute_name], the local attribute name is attribute_name. Where the XML attribute has no namespace prefix, the local name is simply the attribute name.

Use the GetNamespacePrefix method to obtain the namespace prefix for a PBDOM_ATTRIBUTE object. Use the GetQualifiedName method to obtain the fully qualified name for a PBDOM_ATTRIBUTE object.

See also

GetNamespacePrefix

GetNamespaceUri

GetQualifiedName

SetName

SetNamespace

Description

Obtains the namespace prefix of a PBDOM_ATTRIBUTE object. The GetNamespacePrefix method returns an empty string if the PBDOM_ATTRIBUTE has no namespace.

Syntax

pbdom_attribute_name.GetNamespacePrefix()

Return value

String

For a PBDOM_ATTRIBUTE object that has the form [namespacePrefix]:[attributeName], the namespace prefix is [namespacePrefix].

See also

GetNamespaceUri

GetQualifiedName

SetName

SetNamespace

Description

Obtains the namespace URI of a PBDOM_ATTRIBUTE object. The GetNamespaceUri method returns an empty string if the PBDOM_ATTRIBUTE has no namespace.

Syntax

pbdom_attribute_name.GetNamespaceUri()

Return value

String.

See also

GetNamespacePrefix

GetQualifiedName

SetName

SetNamespace

Description

Returns a long integer code that indicates the class of the current PBDOM_OBJECT.

Syntax

pbdom_object_name.GetObjectClass()

Return value

Long.

GetObjectClass returns a long integer code that indicates the class of the current PBDOM_OBJECT. If pbdom_object_name is a PBDOM_ATTRIBUTE, the returned value is 5.

Examples

This example illustrates polymorphism: pbdom_obj is declared as PBDOM_OBJECT but instantiated as PBDOM_ATTRIBUTE. A message box returns the result of the GetObjectClass method invoked for PBDOM_ATTRIBUTE. Here the result is 5, indicating that pbdom_obj is a PBDOM_ATTRIBUTE object.

PBDOM_OBJECT pbdom_obj

pbdom_obj = Create PBDOM_ATTRIBUTE
MessageBox ("Class", &
   string(pbdom_obj.GetObjectClass()))

Usage

This method can be used for diagnostic purposes to dynamically determine the type of a PBDOM_OBJECT at runtime.

See also

GetObjectClassString

Description

Returns a string form of the class of the PBDOM_OBJECT.

Syntax

pbdom_object_name.GetObjectClassString()

Return value

String.

GetObjectClassString returns a string that indicates the class of the current PBDOM_OBJECT. If pbdom_object_name is a PBDOM_ATTRIBUTE, the returned string is "pbdom_attribute".

Examples

The GetObjectClass method returns a string specific to the class of the object from which the method is invoked.

This example illustrates polymorphism: pbdom_obj is declared as PBDOM_OBJECT but instantiated as PBDOM_ATTRIBUTE. A message box returns the result of the GetObjectClassString method invoked for PBDOM_ATTRIBUTE. Here the result is pbdom_attribute, indicating that pbdom_obj is a PBDOM_ATTRIBUTE object.

PBDOM_OBJECT pbdom_obj

pbdom_obj = Create PBDOM_ATTRIBUTE
MessageBox ("Class", pbdom_obj.GetObjectClassString())

Usage

This method can be used for diagnostic purposes to dynamically determine the actual type of a PBDOM_OBJECT at runtime.

See also

GetObjectClass

Description

Returns the PBDOM_DOCUMENT object that owns the PBDOM_ATTRIBUTE.

Syntax

pbdom_attribute_name.GetOwnerDocumentObject()

Return value

PBDOM_DOCUMENT. The PBDOM_DOCUMENT that owns the PBDOM_ATTRIBUTE object from which the GetOwnerDocumentObject method is invoked.

A return value of null indicates the PBDOM_ATTRIBUTE object is not owned by any PBDOM_DOCUMENT.

Examples

The GetOwnerDocumentObject method can be used to identify the PBDOM_DOCUMENT object that owns a PBDOM_ATTRIBUTE object.

Here, the BuildFromString method is used to create the following PBDOM_DOCUMENT object, pbdom_doc, using an XML string:

<abc  My_Attr="My Attribute Value">
   <data>Data </data>
</abc>

The GetAttribute method is used to obtain the attribute from the root element of pbdom_doc. This value is assigned to the PBDOM_ATTRIBUTE object pbdom_attr. The GetOwnerDocumentObject method is used to obtain the pbdom_doc that owns pbdom_attr. The result of the GetOwnerDocumentObject method is assigned to the PBDOM_DOCUMENT object pbdom_doc_2. Then pbdom_doc_2 is compared to pbdom_doc using the Equals method, and the result is displayed in a message box.

PBDOM_Builder pbdombuilder_new
pbdom_document pbdom_doc
pbdom_document pbdom_doc_2
PBDOM_ATTRIBUTE pbdom_attr
string strXML = "<abc  My_Attr=~"My Attribute  Value~"><data>Data </data></abc>"

TRY
  pbdombuilder_new = Create PBDOM_Builder
  pbdom_doc = pbdombuilder_new.BuildFromString (strXML)

  pbdom_attr = pbdom_doc.GetRootElement(). &
     GetAttribute("My_Attr")
  pbdom_doc_2 = pbdom_attr.GetOwnerDocumentObject()

  if (pbdom_doc.Equals(pbdom_doc_2)) then
     MessageBox ("Equals", "pbdom_doc equals " &
       + "pbdom_attr.GetOwnerDocumentObject()")
  end if

  Destroy pbdombuilder_new

CATCH (PBDOM_Exception except)
  MessageBox ("Exception Occurred", except.Text)
END TRY

See also

GetOwnerElementObject

SetOwnerElementObject

Description

Returns the owner PBDOM_ELEMENT of this PBDOM_ATTRIBUTE. If there is no owner element, null is returned.

Syntax

pbdom_attribute_name.GetOwnerElementObject( )

Return value

PBDOM_ELEMENT. The owner PBDOM_ELEMENT of this PBDOM_ATTRIBUTE or null if this PBDOM_ATTRIBUTE has no owner element.

Throws

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

Examples

This example creates a PBDOM_DOCUMENT from a string strXML in which the abc root element contains one attribute, My_Attr. The code gets this attribute, calls GetOwnerElementObject on it to obtain the owner element, then calls GetName to return the string abc. Finally, it sets My_Attr as an attribute of the child element Data:

PBDOM_BUILDER     pbdombuilder_new
PBDOM_DOCUMENT    pbdom_doc
PBDOM_ATTRIBUTE   pbdom_attr
PBDOM_ELEMENT     pbdom_elem
string strXML = "<abc  My_Attr=~"My Attribute Value~"><data>Data</data></abc>"

TRY
  pbdombuilder_new = Create PBDOM_Builder
  pbdom_doc = pbdombuilder_new.BuildFromString (strXML)

  // Get the attribute
  pbdom_attr = pbdom_doc.GetRootElement(). &
     GetAttribute("My_Attr")

  MessageBox ("pbdom_attr Owner Element Name", &
     pbdom_attr.GetOwnerElementObject().GetName())

  pbdom_attr.Detach()

  pbdom_elem = pbdom_doc.GetRootElement(). &
     GetChildElement("data")
  pbdom_elem.SetAttribute (pbdom_attr)

  MessageBox ("pbdom_attr Owner Element Name", &
     pbdom_attr.GetOwnerElementObject().GetName())

  Destroy pbdombuilder_new
  Destroy pbdom_doc

CATCH (PBDOM_Exception except)
  MessageBox ("Exception Occurred", except.Text)
END TRY

See also

SetOwnerElementObject

Description

Obtains the qualified name of a PBDOM_ATTRIBUTE. The GetQualifiedName method returns the local name for a PBDOM_ATTRIBUTE that has no namespace.

Syntax

pbdom_attribute_name.GetQualifiedName()

Return value

String.

Usage

For a PBDOM_ATTRIBUTE object that has the form [namespacePrefix]:[attributeName], the qualified name for the PBDOM_ATTRIBUTE consists of the entire name, [namespacePrefix], and [attributeName].

To obtain the local name of the PBDOM_ATTRIBUTE, use the GetName method.

To obtain the namespace prefix for the PBDOM_ATTRIBUTE, use the GetNamespacePrefix method.

See also

GetName

GetNamespacePrefix

GetNamespaceUri

SetName

SetNamespace

Description

Returns the value of a PBDOM_ATTRIBUTE object as type real.

Syntax

pbdom_attribute_name.GetRealValue()

Return value

Real.

Throws

EXCEPTION_DATA_CONVERSION -- If data conversion fails.

Usage

GetRealValue is the exact counterpart of the JDOM getFloatValue method.

See also

SetRealValue

Description

Returns the text value of the PBDOM_ATTRIBUTE object.

Syntax

pbdom_attribute_name.GetText()

Return value

String.

Throws

EXCEPTION_USE_OF_UNNAMED_PBDOM_OBJECT  -- If this PBDOM_ATTRIBUTE does not have or has not been assigned a user-defined name.

Examples

Usage

This method returns the actual textual value of this PBDOM_ATTRIBUTE, including all text within the quotation marks. If there are any PBDOM_ENTITYREFERENCE objects included within the PBDOM_ATTRIBUTE, the PBDOM_ENTITYREFERENCE object's name is returned together with the leading ampersand ('&') character plus the terminating semicolon character (';').

See also

GetTextNormalize

GetTextTrim

SetText

Description

Returns the text data contained within a PBDOM_ATTRIBUTE object with surrounding whitespace characters removed and internal whitespace characters replaced by a single space.

Syntax

pbdom_attribute_name.GetTextNormalize()

Return value

String.

Examples

Usage

Surrounding whitespace characters are removed from the returned text data, and internal whitespace characters are normalized to a single space. The GetTextNormalize method returns an empty string if no text value exists for the PBDOM_ATTRIBUTE or if the text value contains only whitespace characters.

If this PBDOM_ATTRIBUTE contains any PBDOM_ENTITYREFERENCE objects, the name of the PBDOM_ENTITYREFERENCE object is returned as part of the normalized string.

JDOM does not provide a getTextNormalize method for its Attribute class.

See also

GetText

GetTextTrim

SetText

Description

Returns the text data contained within a PBDOM_ATTRIBUTE object with surrounding spaces removed.

Syntax

pbdom_attribute_name.GetTextTrim()

Return value

String.

Examples

Usage

Surrounding whitespace characters are removed from the returned text data. The GetTextTrim method returns an empty string if no text value exists for the PBDOM_ATTRIBUTE or if the text value contains only whitespace characters.

If this PBDOM_ATTRIBUTE contains any PBDOM_ENTITYREFERENCE objects, the name of the PBDOM_ENTITYREFERENCE object is returned as part of the trimmed string.

See also

GetText

GetTextNormalize

SetText

Description

Returns the value of a PBDOM_ATTRIBUTE object as type Time.

Syntax

pbdom_attribute_name.GetTimeValue(string strTimeFormat)

The value of the strTimeFormat parameter can use slashes or colons as delimiters. The following table illustrates characters that have special meaning in strTimeFormat.

Return value

Time.

Throws

EXCEPTION_DATA_CONVERSION -- If data conversion fails.

See also

SetTimeValue

Description

Returns the value of a PBDOM_ATTRIBUTE object as type Uint.

Syntax

pbdom_attribute_name.GetUintValue()

Return value

Uint.

Throws

EXCEPTION_DATA_CONVERSION -- If data conversion fails.

See also

SetUintValue

Description

Returns the value of a PBDOM_ATTRIBUTE object as type Ulong.

Syntax

pbdom_attribute_name.GetUlongValue()

Return value

Ulong.

Throws

EXCEPTION_DATA_CONVERSION -- If data conversion fails.

See also

SetUlongValue

Description

Determines whether this PBDOM_ATTRIBUTE object contains any child PBDOM_OBJECTs.

Syntax

pbdom_attribute_name.HasChildren()

Return value

Boolean.

Returns true if this PBDOM_ATTRIBUTE contains child objects and false otherwise.

Throws

EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE  -- This PBDOM_OBJECT object is not associated with a derived PBDOM_OBJECT class object.

Examples

This example creates a PBDOM_DOCUMENT from a string. The XML document in the string already contains a root element named root that contains an attribute attr that contains an empty string. It then represents attr as a PBDOM_ATTRIBUTE object and calls its HasChildren method, which returns true because a PBDOM_ATTRIBUTE always contains at least one child object. After a call to GetContent, the message box shows that attr contains only one child, a PBDOM_TEXT that represents the empty string:

PBDOM_BUILDER pbdom_buildr
PBDOM_DOCUMENT pbdom_doc
PBDOM_ATTRIBUTE pbdom_attr
string strXML = "<root attr=~"~"></root>"

try
  pbdom_buildr = Create PBDOM_BUILDER 
  pbdom_doc = pbdom_buildr.BuildFromString(strXML)
  
  pbdom_attr = pbdom_doc.GetRootElement(). &
     GetAttribute("attr")
  
  if (pbdom_attr.HasChildren()) then
    PBDOM_OBJECT pbdom_obj_array[]
    long l = 0
    
    pbdom_attr.GetContent(pbdom_obj_array)
    
    for l = 1 to UpperBound (pbdom_obj_array)
      MessageBox ("Attr Child Object", &
         pbdom_obj_array[l].GetObjectClassString())
    next
    
  end if
  
catch (pbdom_exception pbdom_e)
  MessageBox ("PBDOM_EXCEPTION", pbdom_e.GetMessage())
end try

Usage

This method checks to see if this PBDOM_ATTRIBUTE object contains any child PBDOM_OBJECTs and returns true if it does. Note that according to the W3C DOM specification, a DOM Attribute Node can contain only Text and Entity Reference Nodes, therefore a PBDOM_ATTRIBUTE object can contain only PBDOM_TEXT and PBDOM_ENTITYREFERENCE objects.

Even if a PBDOM_ATTRIBUTE object's text value is an empty string, it always contains at least one PBDOM_TEXT object that represents the empty string.

Description

Inserts a PBDOM_OBJECT as a child of the PBDOM_ATTRIBUTE at a position specified by a referenced PBDOM_OBJECT.

Syntax

pbdom_attribute_name.InsertContent(pbdom_object pbdom_object_new, pbdom_object pbdom_object_ref)

Return value

PBDOM_OBJECT. The PBDOM_ATTRIBUTE returned as a PBDOM_OBJECT.

Throws

EXCEPTION_USE_OF_UNNAMED_PBDOM_OBJECT  -- The PBDOM_OBJECT to be inserted is nameable and has not been given a user-defined name.

EXCEPTION_PBDOM_OBJECT_ALREADY_HAS_PARENT  -- The PBDOM_OBJECT to be inserted already has a parent.

EXCEPTION_INAPPROPRIATE_USE_OF_PBDOM_OBJECT  -- The PBDOM_OBJECT to be inserted is not valid to be inserted as a child of this PBDOM_ATTRIBUTE.

EXCEPTION_WRONG_PARENT_ERROR  -- The reference PBDOM_OBJECT is not a child of this PBDOM_ATTRIBUTE.

Examples

This example adds an attribute to the root element with the name my_attr and text content "attribute text". It then creates a PBDOM_ENTITYREFERENCE object named ent_ref and inserts it before the attribute's current content. Testing the new content of the attribute should return "&ent_ref;attribute text";

Consider the following code :


PBDOM_DOCUMENT          pbdom_doc
PBDOM_ATTRIBUTE         pbdom_attr
PBDOM_ENTITYREFERENCE   pbdom_entref
PBDOM_OBJECT            pbdom_obj_array[]

try
  pbdom_doc = Create PBDOM_DOCUMENT
  pbdom_entref = Create PBDOM_ENTITYREFERENCE

  // Create a new document object.
  pbdom_doc.NewDocument ("root")
  // Add an attribute "my_attr" to the root element.
  pbdom_doc.GetRootElement().SetAttribute("my_attr", &
     "attribute text")
  // Set the name of the PBDOM_ENTITYREFERENCE.
  pbdom_entref.SetName ("ent_ref")
  
  // Get the existing contents of my_attr
  pbdom_doc.GetRootElement().GetAttribute("my_attr").&
     GetContent(pbdom_obj_array)

// Insert the entity reference to the root element's
// my_attr attribute before the attribute text.
  pbdom_doc.GetRootElement().GetAttribute("my_attr").&
     InsertContent(pbdom_entref, pbdom_obj_array[1])

  // Test the text contents of "my_attr"
  if pbdom_doc.GetRootElement(). &
     GetAttribute("my_attr").GetText() = &
     "&ent_ref;attribute text" then
     MessageBox ("Pass", &
        "GetText() on my_attr is correct.")
  else
    MessageBox ("Fail", &
        "GetText() on my_attr is incorrect.")
  end if

  
catch (pbdom_exception pbdom_except)
  MessageBox ("PBDOM_EXCEPTION", &
     pbdom_except.GetMessage())
end try

Usage

This method inserts the input PBDOM_OBJECT as a child at a specific position (before the reference PBDOM_OBJECT). Currently, only a PBDOM_TEXT and a PBDOM_ENTITYREFERENCE object can be inserted as a child of a PBDOM_ATTRIBUTE.

If the reference PBDOM_OBJECT is null, the PBDOM_OBJECT to be inserted is inserted at the end of this PBDOM_ATTRIBUTE object's list of children.

See also

AddContent

GetContent

RemoveContent

SetContent

Description

Determines whether the current PBDOM_ATTRIBUTE object is the ancestor of another PBDOM_OBJECT.

Syntax

pbdom_attribute_name.IsAncestorObjectOf(pbdom_object pbdom_object_ref)

Return value

Boolean.

Returns true if this PBDOM_ATTRIBUTE is the ancestor of the input PBDOM_PBOBJECT and false otherwise.

Throws

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

Usage

This method checks to see whether the current PBDOM_ATTRIBUTE is the ancestor object of the input PBDOM_OBJECT. According to the W3C DOM specification, only a PBDOM_TEXT and a PBDOM_ENTITYREFERENCE object can become a child object of a PBDOM_ATTRIBUTE, and therefore a PBDOM_ATTRIBUTE can only be an ancestor of a PBDOM_TEXT or a PBDOM_ENTITYREFERENCE object.

Description

Removes the input PBDOM_OBJECT from the PBDOM_ATTRIBUTE.

Syntax

pbdom_attribute_name.RemoveContent(pbdom_object pbdom_object_ref)

Return value

Boolean.

Returns true if the content has been successfully removed and false otherwise.

Throws

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

EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE  -- This PBDOM_ATTRIBUTE object or the input PBDOM_OBJECT is not associated with a derived PBDOM_OBJECT class object.

EXCEPTION_USE_OF_UNNAMED_PBDOM_OBJECT  -- This PBDOM_ATTRIBUTE or the PBDOM_OBJECT to be removed is nameable and has not been given a user-defined name.

EXCEPTION_WRONG_DOCUMENT_ERROR  -- The input PBDOM_OBJECT is not contained within the same PBDOM_DOCUMENT as this PBDOM_ATTRIBUTE.

EXCEPTION_WRONG_PARENT_ERROR  -- The input PBDOM_OBJECT is not a child of the current PBDOM_ATTRIBUTE.

Examples

This example adds an attribute to the root element with the name my_attr and text content "attribute text". It then creates a PBDOM_ENTITYREFERENCE object named ent_ref and inserts it before the attribute's current content.

At this point, my_attr contains two child PBDOM_OBJECTs: a PBDOM_TEXT containing "attribute text" and a PBDOM_ENTITYREFERENCE named ent_ref. The element looks like this when serialized:

<root my_attr="attribute text&ent_ref;">

A call to GetContent returns an array containing these two PBDOM_OBJECTs. pbdom_obj_array[1] should point to the PBDOM_TEXT. After pbdom_obj_array[1] is removed from my_attr, the element looks like this when serialized: <root my_attr="&ent_ref;">.

PBDOM_DOCUMENT     pbdom_doc
PBDOM_ATTRIBUTE    pbdom_attr
PBDOM_ENTITYREFERENCE   pbdom_entref
PBDOM_OBJECT            pbdom_obj_array[]

try
  pbdom_doc = Create PBDOM_DOCUMENT
  pbdom_entref = Create PBDOM_ENTITYREFERENCE

  // Create a new document object.
  pbdom_doc.NewDocument ("root")
  // Add an attribute "my_attr" to the root element.
  pbdom_doc.GetRootElement().SetAttribute("my_attr", &
     "attribute text")

  // Set the name of our PBDOM_ENTITYREFERENCE.  
  pbdom_entref.SetName ("ent_ref")
  
  // Add the entity reference to the root 
  // element's "my_attr" attribute.
  pbdom_doc.GetRootElement(). &
     GetAttribute("my_attr"). AddContent(pbdom_entref)

  // Get the existing contents of "my_attr"
  pbdom_doc.GetRootElement().GetAttribute("my_attr").&
     GetContent(pbdom_obj_array)

  // Remove PBDOM_TEXT object from "my_attr"
  pbdom_doc.GetRootElement().GetAttribute("my_attr").&
     RemoveContent(pbdom_obj_array[1])
  
// Test the text contents of "my_attr  "
  if pbdom_doc.GetRootElement(). &
     GetAttribute("my_attr").GetText() = &
     "&ent_ref;" then
    MessageBox ("Pass", &
      "GetText() on my_attr is correct.")
  else
    MessageBox ("Fail", 
      "GetText() on my_attr is incorrect.")
  end if
  
catch (pbdom_exception pbdom_e)
  MessageBox ("PBDOM_EXCEPTION", pbdom_e.GetMessage())
end try

Usage

The RemoveContent method removes the input PBDOM_OBJECT from this PBDOM_ATTRIBUTE. Currently, only a PBDOM_TEXT and a PBDOM_ENTITYREFERENCE object can be part of the contents of a PBDOM_ATTRIBUTE. Therefore, the input PBDOM_OBJECT must be either a PBDOM_TEXT or a PBDOM_ENTITYREFERENCE object.

See also

AddContent

GetContent

InsertContent

SetContent

Description

Sets the text value of a PBDOM_ATTRIBUTE object. The SetBooleanValue method creates this text value by serializing the provided boolean value into a string.

Syntax

pbdom_attribute_name.SetBooleanValue(boolean boolValue)

Return value

PBDOM_ATTRIBUTE. The PBDOM_ATTRIBUTE from which the SetBooleanValue method was invoked.

See also

GetBooleanValue

Description

Sets the content of this PBDOM_ATTRIBUTE.

Syntax

pbdom_attribute_name.SetContent(pbdom_object pbdom_object_array)

Return value

PBDOM_OBJECT. This PBDOM_ATTRIBUTE modified.

Throws

EXCEPTION_ILLEGAL_PBOBJECT  -- One of the array items is not a valid PBDOM object. This can happen if the array item has not been initialized properly or is a null object reference. This is similar to EXCEPTION_INVALID_ARGUMENT.

EXCEPTION_USE_OF_UNNAMED_PBDOM_OBJECT  -- One of the array items is nameable and has not been given a user-defined name.

EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE  -- One of the array items is not associated with a derived PBDOM_OBJECT.

EXCEPTION_PBDOM_OBJECT_ALREADY_HAS_PARENT  -- One of the array items already has a parent.

EXCEPTION_INAPPROPRIATE_USE_OF_PBDOM_OBJECT  -- One of the array items is not allowed to be set as part of the contents of a PBDOM_ATTRIBUTE.

Examples

This example demonstrates setting the contents of a PBDOM_ATTRIBUTE object. It creates a PBDOM_DOCUMENT with root element root and attaches to it a PBDOM_DOCTYPE with the following internal subset:

<!ELEMENT root ANY>
<!ATTLIST root attr CDATA #REQUIRED>
<!ENTITY ent_ref  "MY ENTITY REFERENCE">

It also creates a PBDOM_ATTRIBUTE, attr, and sets as its contents an array of three PBDOM_OBJECTS:

This removes the original contents of attr and sets new contents so that when the document is serialized into an external file, the root element looks like this:

<root attr="start text &ent_ref; end text."/>

Finally, a user-defined function called GetAttributeText parses the external serialized XML file and retrieves the text value of the attr attribute.

The code for GetAttributeText function is as follows:

PBDOM_BUILDER    pbdom_buildr
PBDOM_DOCUMENT   pbdom_doc
string           strReturn

try
  pbdom_buildr = Create PBDOM_BUILDER 
  pbdom_doc = pbdom_buildr. &
     BuildFromFile (strXMLFileName)
  
  strReturn = pbdom_doc.GetRootElement(). &
     GetAttribute(strAttributeName).GetText()
catch (PBDOM_EXCEPTION pbdom_except)
  strReturn = ""
end try
return strReturn

This function builds a PBDOM_DOCUMENT from the external XML file (its first argument) and gets the text value of an attribute (its second argument) from the root element.

The code that sets the content of the PBDOM_ATTRIBUTE is as follows:

PBDOM_DOCUMENT     pbdom_doc
PBDOM_DOCTYPE      pbdom_doctyp
PBDOM_ATTRIBUTE    pbdom_attr
PBDOM_TEXT         pbdom_txt
PBDOM_OBJECT       pbdom_obj_array_set[]
long l = 0

try
  pbdom_doc = Create PBDOM_DOCUMENT
  pbdom_doc.NewDocument ("root")
  
  pbdom_doctyp = Create PBDOM_DOCTYPE  
  pbdom_doctyp.SetName ("root")
  pbdom_doctyp.setinternalsubset("<!ELEMENT root ANY><!ATTLIST root attr CDATA #REQUIRED><!ENTITY ent_ref ~"MY ENTITY REFERENCE~">")
  
  pbdom_doc.SetDocType(pbdom_doctyp)
  
  pbdom_doc.GetRootElement().SetAttribute("attr", "")

  pbdom_obj_array_set[1] = Create PBDOM_TEXT    
  pbdom_txt = pbdom_obj_array_set[1]
  pbdom_txt.SetText ("start text ")

  pbdom_obj_array_set[2] = Create PBDOM_ENTITYREFERENCE 
  pbdom_obj_array_set[2].SetName("ent_ref")

  pbdom_obj_array_set[3] = Create PBDOM_TEXT    
  pbdom_txt = pbdom_obj_array_set[3]
  pbdom_txt.SetText (" end text.")

  pbdom_doc.GetRootElement().GetAttribute("attr"). &
    SetContent(pbdom_obj_array_set)

  
  pbdom_doc.SaveDocument &
    ("c:\xmltests\attr_set_content.xml")

  MessageBox ("Attribute Text", GetAttributeText &
   ("c:\xmltests\attr_set_content.xml", "attr"))

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

Usage

This method sets the content of this PBDOM_ATTRIBUTE. The supplied array should contain only objects of type PBDOM_TEXT and PBDOM_ENTITYREFERENCE.

When all objects in the supplied array are legal and before the new content is added, all objects in the old content will have their parentage set to null (no parent) and the old content list will be cleared from this PBDOM_ATRIBUTE.

This has the effect that the items of any active array (previously obtained with a call to GetContent) also change to reflect the new condition. In addition, all objects in the supplied array have their parentage set to this PBDOM_ATTRIBUTE.

Passing a null value or an empty array clears the existing content of this PBDOM_ATTRIBUTE.

See also

AddContent

GetContent

RemoveContent

SetContent

Description

Sets the text value of a PBDOM_ATTRIBUTE object. The SetDateValue method creates this text value by serializing the provided date value into a string.

Syntax

pbdom_attribute_name.SetDateValue(date dateValue, strDateFormat)

The value of the strDateFormat parameter can include slashes or colons as delimiters. The following table illustrates characters having special meaning in strDateFormat.

Return value

PBDOM_ATTRIBUTE. The PBDOM_ATTRIBUTE from which the SetDateValue method was invoked.

See also

GetDateValue

Description

Sets the text value of a PBDOM_ATTRIBUTE object and creates this text value by serializing the provided datetime value into a string.

Syntax

pbdom_attribute_name.SetDateTimeValue(datetime datetimeValue, string strDateFormat, string strTimeFormat)

The value of the strDateFormat parameter can use slashes or colons as delimiters. The following table illustrates characters that have special meaning in strDateFormat.

The value of the strTimeFormat parameter can include slashes or colons as delimiters. The following table illustrates characters that have special meaning in strTimeFormat.

Return value

PBDOM_ATTRIBUTE. The PBDOM_ATTRIBUTE from which the SetDateTimeValue method was invoked.

See also

GetDateTimeValue

Description

Sets the text value of a PBDOM_ATTRIBUTE object. The SetDoubleValue method creates this text value by serializing the provided double value into a string.

Syntax

pbdom_attribute_name.SetDoubleValue( double doubleValue)

Return value

PBDOM_ATTRIBUTE. The PBDOM_ATTRIBUTE from which the SetDoubleValue method was invoked.

See also

GetDoubleValue

Description

Sets the text value of a PBDOM_ATTRIBUTE object. The SetIntValue method creates this text value by serializing the provided int value into a string.

Syntax

pbdom_attribute_name.SetIntValue(integerintValue)

Return value

PBDOM_ATTRIBUTE. The PBDOM_ATTRIBUTE from which the SetIntValue method was invoked.

See also

GetIntValue

Description

Sets the text value of a PBDOM_ATTRIBUTE object. The SetLongValue method creates this text value by serializing the provided long value into a string.

Syntax

pbdom_attribute_name.SetLongValue( long longValue)

Return value

PBDOM_ATTRIBUTE. The PBDOM_ATTRIBUTE from which the SetLongValue method was invoked.

See also

GetLongValue

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

Description

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

Syntax

pbdom_attribute_name.SetNamespace(stringstrNamespacePrefix, 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

Description

Sets the input PBDOM_ELEMENT as the owner of the current PBDOM_ATTRIBUTE.

Syntax

pbdom_attribute_name.SetOwnerElementObject(pbdom_element pbdom_element_ref)

Return value

PBDOM_ATTRIBUTE. This PBDOM_ATTRIBUTE itself modified and returned.

Throws

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

EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE  -- The internal implementation of the PBDOM_ATTRIBUTE object or the input PBDOM_ELEMENT object is null. The occurrence of this exception is rare but can take place if severe memory corruption occurs.

EXCEPTION_PBDOM_OBJECT_ALREADY_HAS_OWNER  -- This PBDOM_ATTRIBUTE already has an owner Element.

EXCEPTION_USE_OF_UNNAMED_PBDOM_OBJECT  -- The input PBDOM_ELEMENT has not been named.

EXCEPTION_INVALID_NAME  -- The input PBDOM_ELEMENT already contains an attribute that has the same name and that belongs to the same namespace as this current PBDOM_ATTRIBUTE.

Examples

This example moves the positions of two PBDOM_ATTRIBUTE objects from one element to another.

In the string strXML from which a PBDOM_DOCUMENT is created, the abc root element contains a namespace declaration and two attributes. My_Attr belongs to no namespace, and pre:My_Attr_NS belongs to the http://www.pre.com namespace.

The example obtains handles for the two attributes and the data element, then detaches both attributes from abc and sets data as their new owner:

PBDOM_BUILDER     pbdombuilder_new
PBDOM_DOCUMENT    pbdom_doc
PBDOM_ATTRIBUTE   pbdom_attr
PBDOM_ATTRIBUTE   pbdom_attr_ns
PBDOM_ELEMENT     pbdom_elem_data
string strXML = "<abc  My_Attr=~"Attribute Value~" pre:My_Attr_NS=~"Attribute Value NS~" xmlns:pre=~"http://www.pre.com~"><data>Data</data></abc>"

TRY
 pbdombuilder_new = Create PBDOM_Builder
 pbdom_doc = pbdombuilder_new.BuildFromString(strXML)

 pbdom_attr = pbdom_doc.GetRootElement(). &
    GetAttribute("My_Attr")
 pbdom_attr_ns = pbdom_doc.GetRootElement(). &
    GetAttribute("My_Attr_NS", "pre", &
    "http://www.pre.com")
 pbdom_elem_data = pbdom_doc.GetRootElement(). &
    GetChildElement("data")

 pbdom_attr.Detach()
 pbdom_attr.SetOwnerElementObject (pbdom_elem_data)

 pbdom_attr_ns.Detach()
 pbdom_attr_ns.SetOwnerElementObject (pbdom_elem_data)

 pbdom_doc.SaveDocument("setownerelementobject.xml")

 Destroy pbdombuilder_new
 Destroy pbdom_doc

CATCH (PBDOM_Exception except)
 MessageBox ("Exception Occurred", except.Text)
END TRY

When the document is serialized, the XML looks like this:

<abc xmlns:pre="http://www.pre.com">
<data pre:My_Attr_NS="Attribute Value NS" My_Attr="Attribute Value">Data</data>
</abc>

Usage

According to the "Namespace in XML" specifications, an element cannot contain two attributes with the same local name and namespace URI. This is true even if the prefixes of the two attributes are different. An exception is thrown if this rule is violated when SetOwnerElementObject is invoked.

See also

GetOwnerElementObject

Description

Sets the text value of a PBDOM_ATTRIBUTE object. The SetRealValue method creates this text value by serializing the provided real value into a string.

Syntax

pbdom_attribute_name.SetRealValue(real realValue)

Return value

PBDOM_ATTRIBUTE. The PBDOM_ATTRIBUTE from which the SetRealValue method was invoked.

See also

GetRealValue

Description

Sets the string value of a PBDOM_ATTRIBUTE object.

Syntax

pbdom_attribute_name.SetText(string strText)

Return value

PBDOM_ATTRIBUTE.

Usage

This method returns the current PBDOM_ATTRIBUTE with the input string value set.

This method is the counterpart of the JDOM setValue method.

See also

GetText

GetTextNormalize

GetTextTrim

Description

Sets the text value of a PBDOM_ATTRIBUTE object. The SetTimeValue method creates this text value by serializing the provided time value into a string.

Syntax

pbdom_attribute_name.SetTimeValue(time timeValue, string strTimeFormat)

The value of the strTimeFormat parameter can use slashes or colons as delimiters. The following table illustrates characters that have special meaning in strTimeFormat.

Return value

PBDOM_ATTRIBUTE. The PBDOM_ATTRIBUTE from which the SetTimeValue method was invoked.

See also

GetTimeValue

Description

Sets the text value of a PBDOM_ATTRIBUTE object. The SetUintValue method creates this text value by serializing the provided uint value into a string.

Syntax

pbdom_attribute_name.SetUintValue(unsignedinteger uintValue)

Return value

PBDOM_ATTRIBUTE. The PBDOM_ATTRIBUTE from which the SetUintValue method was invoked.

See also

GetUintValue

Description

Sets the text value of a PBDOM_ATTRIBUTE object. The SetUlongValue method creates this text value by serializing the provided ulong value into a string.

Syntax

pbdom_attribute_name.SetUlongValue(unsignedlong ulongValue)

Return value

PBDOM_ATTRIBUTE. The PBDOM_ATTRIBUTE from which the SetUlongValue method was invoked.

See also

GetUlongValue