PowerBuilder Extension Reference
PBDOM_ATTRIBUTE

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