PowerBuilder Extension Reference
PBDOM_ENTITYREFERENCE

Description

Creates and returns a clone of the current PBDOM_ENTITYREFERENCE object.

Syntax

pbdom_entityref_name.Clone(boolean bDeep)

Return value

PBDOM_OBJECT. A clone of the current PBDOM_ENTITYREFERENCE object housed in a PBDOM_OBJECT.

Examples

This example creates a PBDOM_DOCUMENT based on a string that contains an XML document, and creates a PBDOM_ENTITYREFERENCE object to reference the ENTITY my_er defined in the DOCTYPE. The DOCTYPE also indicates that the root element must contain zero or more child elements named child, and that each child can contain only parsed character data.

The FOR loop creates ten child elements and inserts a new clone of pbdom_er into each child element. You must use a clone, because the same object cannot be inserted as a child of more than one parent:

PBDOM_BUILDER           pbdom_buildr
PBDOM_DOCUMENT          pbdom_doc
PBDOM_ENTITYREFERENCE   pbdom_er
string strXML = "<!DOCTYPE root [<!ELEMENT root (child)*><!ELEMENT child (#PCDATA)><!ENTITY my_er ~"MY ENTITY~">]><root/>"
long l = 0

TRY
  pbdom_buildr = Create PBDOM_BUILDER
  pbdom_doc = pbdom_buildr.BuildFromString(strXML)
  pbdom_er = Create PBDOM_ENTITYREFERENCE
  pbdom_er.SetName("my_er")
  
// Create 10 child elements for the root element
  for l = 1 to 10
    PBDOM_ELEMENT pbdom_elem_child
    
    pbdom_elem_child = Create PBDOM_ELEMENT
    pbdom_elem_child.SetName("child")
    // Add a clone of pbdom_er as content
    pbdom_elem_child.AddContent(pbdom_er.Clone(true))
    
    pbdom_doc.GetRootElement(). &
      AddContent(pbdom_elem_child)
  next
  
  pbdom_doc.SaveDocument("clone_er.xml")
CATCH(PBDOM_EXCEPTION pbdom_e)
  MessageBox ("PBDOM_EXCEPTION", pbdom_e.GetMessage())
END TRY

When the PBDOM_DOCUMENT object is serialized, it produces the following XML document:

<!DOCTYPE root
[
<!ELEMENT root (child)*>
<!ELEMENT child (#PCDATA)*>
<!ENTITY my_er "MY ENTITY">
]
> 
<root> <child>MY ENTITY</child> 
<child>MY ENTITY</child> 
<child>MY ENTITY</child> 
<child>MY ENTITY</child> 
<child>MY ENTITY</child> 
<child>MY ENTITY</child> 
<child>MY ENTITY</child> 
<child>MY ENTITY</child> 
<child>MY ENTITY</child> 
<child>MY ENTITY</child> 
</root>

Usage

The Clone method creates a new PBDOM_ENTITYREFERENCE object which is a duplicate of the original. A PBDOM_ENTITYREFERENCE object cannot contain any child PBDOM_OBJECTs, so there is no subtree beneath a PBDOM_ENTITYREFERENCE object. A shallow clone is therefore structurally no different than a deep clone of a PBDOM_ENTITYREFERENCE object.

This method allows you to use an entity reference node more than once. You cannot add a PBDOM_ENTITYREFERENCE object as the child of more than one PBDOM_OBJECT, but you can clone it and then add the clone as the child of another PBDOM_OBJECT.

A PBDOM_ENTITYREFERENCE clone does not have any parent. However, the clone resides in the same PBDOM_DOCUMENT as its original. If the original PBDOM_ENTITYREFERENCE object is standalone, the clone is also standalone.