This example demonstrates:

1. Using an External DTD.

2. Using a parameter entity.

3. Using a single line statement to obtain the children
   PBDOM_OBJECTs of an element.

4. Obtaining the text of the three separate types of PBDOM_CHARACTERDATA
   objects : PBDOM_TEXT, PBDOM_COMMENT, and PBDOM_CDATA.

5. Obtaining the trimmed text of the same three separate
   types of PBDOM_CHARACTERDATA objects.

6. The difference between the two types of text retrieved
   in 4 and 5.

The PowerScript code saves a string into an external file,
then creates a PBDOM_DOCUMENT pbdom_doc based
on the following DOM tree:

c:external_entity.dtd is
an external Document Type Definition file. Its contents are the
external subset of the Document Type Definition. The first line declares
a PARAMETER entity param_entity_ref that
contains the following replacement text:

The next line declares a general entity text1 that
contains the following replacement text:

When the entity text1 is used in an XML
document, it is expanded to the contents of the PARAMETER entity param_entity_ref.

The PowerScript code then obtains the root element, uses it
to obtain the data child element, and then
obtains an array of the child element’s own children. PBDOM
collects all the PBDOM_OBJECTs that are the children of
data and stores them in the PBDOM_OBJECT array pbdom_obj_array.

Next, the FOR loop iterates through all
the items in pbdom_obj_array and
stores each item in the PBDOM_CHARACTERDATA array pbdom_chardata.
This step is not required—the pbdom_obj_array can
be used to manipulate the data element’s children. It is
done to demonstrate that you can cast each item into a PBDOM_CHARACTERDATA
object by assigning it into a PBDOM_CHARACTERDATA array.

This is possible if and only if each PBDOM_OBJECT
is also derived from PBDOM_CHARACTERDATA. If a PBDOM_OBJECT
is not derived from PBDOM_CHARACTERDATA, the PowerBuilder
VM throws an exception.

The next FOR loop iterates through all
the items of the pbdom_chardata array and
calls the GetText and GetTextTrim methods
on each. Each of the returned strings from GetText and GetTextTrim is
delimited by “[” and “]” characters
so that the complete text content displays clearly in the message
boxes.

The first child of data is the PBDOM_TEXT &text1;,
which expands to the string in param_entity_ref.
The entity references within this string are also expanded and the
Tab and Space characters display when GetText is
called. When GetTextTrim is called, PBDOM removes
the beginning and trailing whitespace characters and the resulting
string is simply PARAMETER ENTITY REFERENCE.The
second child of data is the PBDOM_COMMENT <!-- &text1;-->., and
the third child is the PBDOM_CDATA <![CDATA[&text1;]]>.
The string &text1; is
not considered to be an entity reference by PBDOM because W3C DOM
comments and CDATA sections cannot hold any entity references. Both GetText and GetTextTrim return
the string &text1;.
There are no leading or trailing spaces to remove.