PowerBuilder Extension Reference
PBDOM_COMMENT

Description

Creates and returns a clone of the current PBDOM_COMMENT.

Syntax

pbdom_comment_name.Clone(boolean bDeep)

Return value

PBDOM_OBJECT.

Examples

This example creates an XML document that, when serialized, appears as follows:

<!DOCTYPE root
[
<!ELEMENT root (level_1)*>
<!ELEMENT level_1 (level_2)*>
<!ELEMENT level_2 (#PCDATA)*>
]>
<root>
   <level_1>
      <!--Element at level : 1-->
      <level_2>
         <!--Element at level : 2-->
      </level_2>
   </level_1>
</root>

The definition of the DTD shows that the document is required to have the following composition:

The following PowerScript code supplies annotations within the document by including comments to mark level_1 and level_2 elements. The sample code creates a PBDOM_DOCUMENT from an XML string that contains a DTD and a minimal root element. Then, it creates a comment that serves as a template. The template comment is then cloned, and instance-specific text is added for each element:

PBDOM_COMMENT pbdom_comm
PBDOM_COMMENT pbdom_comm_clone
PBDOM_ELEMENT pbdom_elem
PBDOM_DOCUMENT pbdom_doc
PBDOM_BUILDER pbdom_buildr
string strXML = "<!DOCTYPE root [<!ELEMENT root (level_1)*><!ELEMENT level_1 (level_2)*><!ELEMENT level_2 (#PCDATA)>]><root/>"

try
  // Create a PBDOM_DOCUMENT from the XML string that
  // contains a DTD and a minimal root element.
  pbdom_buildr = Create PBDOM_BUILDER
  pbdom_doc = pbdom_buildr.BuildFromString(strXML)

  // Create a template comment that can be reused.
  pbdom_comm = Create PBDOM_COMMENT
  pbdom_comm.SetText ("Element at level : ")
  
  // Create a level_1 element.
  pbdom_elem = Create PBDOM_ELEMENT
  pbdom_elem.SetName("level_1")

  // Clone the template comment, append instance-
  // specific text, and add it to the level_1 element.
  pbdom_comm_clone = pbdom_comm.Clone(true)
  pbdom_elem.AddContent(pbdom_comm_clone.Append("1"))
  
  // Add a level_1 element into the root element 
  // as stipulated by the DTD.
  pbdom_doc.GetRootElement().AddContent(pbdom_elem)
  
  // Create a level_2 element.
  pbdom_elem = Create PBDOM_ELEMENT
  pbdom_elem.SetName("level_2")

  // Clone the template comment, append instance-
  // specific text, and add it to the level_2 element.
  pbdom_comm_clone = pbdom_comm.Clone(true)
  pbdom_elem.AddContent(pbdom_comm_clone.Append("2"))
  
  // Add a level_2 element into the level_1 element
  // as stipulated by the DTD.
  pbdom_doc.GetRootElement().GetChildElement &
    ("level_1").AddContent(pbdom_elem)

  // Finally, serialize the document.
  pbdom_doc.SaveDocument("sample.xml")
  
catch(PBDOM_EXCEPTION pbdom_e)
  MessageBox ("PBDOM_EXCEPTION", pbdom_e.GetMessage())
end try

Usage

The Clone method creates a new PBDOM_COMMENT object that is a duplicate of, and a separate object from, the original. Whether true or false is supplied, the clone is always identical to its original, because a PBDOM_COMMENT does not contain a subtree of child PBDOM_OBJECTs.

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