PowerBuilder Extension Reference
PBDOM_BUILDER

Description

Builds a PBDOM_DOCUMENT from the file pointed to by the input URL string. The URL can be a local file path.

Syntax

pbdom_builder_name.BuildFromFile (string strURL)

Return value

PBDOM_DOCUMENT.

Throws

EXCEPTION_MEMORY_ALLOCATION_FAILURE -- If there is insufficient memory to create a PBDOM_DOCUMENT object.

Examples

Suppose the file c:\pbdom_doc_1.xml contains the following XML string:

<!DOCTYPE abc [<!ENTITY text "Some Text" >]>
<abc>
  <data>
    <child_data>Child Data Text</child_data>
    <child_data An_Attribute="Some Attribute Value"/>
    &text;
    <!--Comment String-->
    <![CDATA[Some CDATA String]]>
  </data>
</abc>

The file contains a Document Type Declaration that indicates that <abc> is the root element, and a declaration for the text entity that expands to "Some Text":

The root element abc contains a child element data, which contains five child PBDOM_OBJECTs: two PBDOM_ELEMENT objects, and PBDOM_TEXT, PBDOM_COMMENT, and PBDOM_CDATA objects.

The first child_data element contains a PBDOM_TEXT with the string "Child Data Text". The second child_data element contains no child PBDOM_OBJECTs but it does contain a PBDOM_ATTRIBUTE, An_Attribute, that contains the value "Some Attribute Value".

This example creates a PBDOM_DOCUMENT called pbdom_doc from c:\pbdom_doc_1.xml, tests the content of pbdom_doc, then saves the DOM tree contained within pbdom_doc into a separate file, c:\pbdom_doc_2.xml. The input and output files should be identical.

PBDOM_Builder     pbdom_bldr
PBDOM_Document    pbdom_doc
PBDOM_Object      pbdom_obj_array[]
PBDOM_Element     pbdom_elem
integer iFileNum1
long l = 0

// Create a PBDOM_DOCUMENT from the XML file
  pbdom_bldr = Create PBDOM_Builder
  pbdom_doc = pbdom_bldr.BuildFromFile &
     ("c:\pbdom_doc_1.xml")

// Test the contents of the PBDOM_DOCUMENT
// First test the PBDOM_DOCTYPE in the document
  MessageBox ("PBDOM_DOCTYPE GetName()", &
     pbdom_doc.GetDocType().GetName())
  MessageBox ("PBDOM_DOCTYPE GetInternalSubset()", &
     pbdom_doc.GetDocType().GetInternalSubset())

// Test the root element
  MessageBox ("PBDOM_DOC Root Element Name", &
     pbdom_doc.GetRootElement().GetName())

// test the root element’s child element
  MessageBox ("PBDOM_DOC <data> Element Name", &
     pbdom_doc.GetRootElement().GetChildElement &
     ("data").GetName())

// Collect all the child PBDOM_OBJECTs of the
// <data> element
  pbdom_doc.GetRootElement().GetChildElement &
     ("data").GetContent(pbdom_obj_array)

// Display the class name, the name and the text contained
// within each PBDOM_OBJECT array item 
  for l = 1 to UpperBound(pbdom_obj_array)
    MessageBox ("Child Object " + string(l) + " Class",&
      pbdom_obj_array[l].GetObjectClassString())
    MessageBox ("Child Object " + string(l) + " Name",&
      pbdom_obj_array[l].GetName())
    MessageBox ("Child Object " + string(l) + " Text",&
      pbdom_obj_array[l].GetText())
  next

// Retrieve and display the name and text value of the
// "An_Attribute" attribute from the <child_data> element 
   pbdom_elem = pbdom_obj_array[2]
  MessageBox ("child_data Attribute name", &
    pbdom_elem.GetAttribute("An_Attribute").GetName())
  MessageBox ("child_data Attribute value", &
    pbdom_elem.GetAttribute("An_Attribute").GetText())

// save the DOM Tree contained within pbdom_doc into
// a separate file "c:\pbdom_doc_2.xml"
  pbdom_doc.SaveDocument ("c:\pbdom_doc_2.xml")

  Destroy pbdom_bldr

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

Usage

The input URL string can be a local file path.

The encoding specified in the XML export template determines the encoding of the document created using BuildFromFile.

See also

BuildFromDataStore

BuildFromString