PBDOM_BUILDER

Description

The PBDOM_BUILDER class serves as a DOM factory that creates a PBDOM_DOCUMENT from various input sources, such as a string and a DataStore. A PBDOM_BUILDER class is not a PBDOM_OBJECT. There are no DOM objects to which you can map a PBDOM_BUILDER class.

The PBDOM_BUILDER methods can be contrasted with the PBDOM_DOCUMENT NewDocument methods (overloaded with several versions) that are intended to be used to build a PBDOM_DOCUMENT from scratch.

Methods

PBDOM_BUILDER has the following methods:

BuildFromDataStore

BuildFromFile

BuildFromString

GetParseErrors

BuildFromDataStore

Description

Builds a PBDOM_DOCUMENT from the referenced DataStore object.

Syntax

pbdom_builder_name.BuildFromDataStore(datastore datastore_ref)

Argument

Description

pbdom_builder_name

The name of a PBDOM_BUILDER object

datastore_ref

A DataStore object


Return value

PBDOM_DOCUMENT.

Throws

EXCEPTION_INVALID_ARGUMENT  -- The input DataStore object is invalid. This can happen if it has not been initialized properly or is a null object reference.

Examples

The following PowerScript code fragment demonstrates how to use the BuildFromDataStore method with a referenced DataStore object.

PBDOM_Builder pbdom_bldr
pbdom_document pbdom_doc
datastore ds

ds = Create datastore
ds.DataObject = "d_customer"
ds.SetTransObject (SQLCA)
ds.Retrieve()

pbdom_doc = pbdom_bldr.BuildFromDataStore(ds)

In this example, a DataStore object ds is created and populated with data, and then passed to the BuildFromDataStore method. The BuildFromDataStore method causes the DataStore to export the data to XML, using the most current XML template for the DataStore, and then it uses the XML to build a PBDOM_DOCUMENT. The PBDOM_DOCUMENT object is assigned to pbdom_doc.

Usage

This method creates a temporary file in the directory pointed to by the user's TMP environment variable. If this directory is invalid, the temporary file is created in the Windows\temp directory.

The encoding specified in the XML export template has no effect on the encoding of the document created using BuildFromDataStore. It always has UTF-16LE encoding.

See also

BuildFromFile

BuildFromString

BuildFromFile

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)

Argument

Description

pbdom_builder_name

The name of a PBDOM_BUILDER object

strURL

A string that indicates the URL of the file from which to build a PBDOM_DOCUMENT


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

BuildFromString

Description

Builds a PBDOM_DOCUMENT from a string.

Syntax

pbdom_builder_name.BuildFromString(string strXMLStream)

Argument

Description

pbdom_builder_name

The name of a PBDOM_BUILDER object

strXMLStream

A string containing XML


Return value

PBDOM_DOCUMENT.

Throws

EXCEPTION_INVALID_ARGUMENT  -- The input string is invalid. This can happen if it has not been initialized properly or is a null object reference.

EXCEPTION_MEMORY_ALLOCATION_FAILURE  -- Insufficient memory was encountered while executing this method.

Examples

The following PowerScript code fragment demonstrates how to use the BuildFromString method with an input string. A string containing XML is passed to the BuildFromString method and the return value is assigned to a PBDOM_DOCUMENT.

PBDOM_Builder pbdom_bldr
pbdom_document pbdom_doc
string strXML

strXML = "<Music:abc xmlns:ZMusic="
strXML += "~"http://www.ZMusic.com~">"
strXML += "Root Element Data<data>ABC Data"
strXML += "<inner_data>My Inner Data</inner_data>"

strXML += "My Data</data></abc>"

pbdom_bldr = Create PBDOM_Builder
pbdom_doc = pbdom_bldr.BuildFromString (strXML)

Usage

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

See also

BuildFromDataStore

BuildFromFile

GetParseErrors

Description

Obtains a list of parsing errors detected during document parsing.

Syntax

pbdom_builder_name.GetParseErrors(ref string strErrorMessageArray[])

Argument

Description

pbdom_builder_name

The name of a PBDOM_BUILDER object

strErrorMessageArray

An unbounded array of strings, each of which will be filled with a formatted string containing a parse error.


Return value

Boolean.

Returns true if a list of parse errors has been retrieved and false otherwise. Also returns false if there are no parse errors.

Throws

EXCEPTION_INVALID_ARGUMENT  -- The input string array is invalid. This can happen if it has not been initialised properly or is a null object reference.

EXCEPTION_MEMORY_ALLOCATION_FAILURE  -- Insufficient memory was encountered while executing this method.

Examples

The code in this example attempts to create a PBDOM_DOCUMENT based on the following XML:

<!DOCTYPE root 
[
<!ELEMENT root ANY>
<!ELEMENT data (#PCDATA)> 
<!ENTITY text "Some Text">
]
>
<root><abc/><def/></root>

This XML is well formed but is not valid, because the element root contains two child elements abc and def that are not declared in the DOCTYPE. When GetParseErrors is called, it returns the value true, indicating that at least one parse error has occurred, and generates the following list of errors:

"1,103,Unknown element 'abc'"
"1,109,Unknown element 'def'"

The 1 in both error messages indicates that the error occurred in line 1 of the XML string, and the 103 and 109 indicate columns 103 and 109, respectively.

PBDOM_BUILDER pbdom_buildr
PBDOM_DOCUMENT pbdom_doc
long l = 0
string strXML = "<!DOCTYPE root [<!ELEMENT root ANY><!ELEMENT data (#PCDATA)> <!ENTITY text ~"Some Text~">]> <root><abc/><def/></root>"
string strParseErrors[]
BOOLEAN bRetTemp = FALSE

try
  pbdom_buildr = Create PBDOM_BUILDER
  pbdom_doc = pbdom_buildr.BuildFromString (strXML)
  bRetTemp = &
     pbdom_buildr.GetParseErrors(strParseErrors)
  
  if bRetTemp = true then
    for l = 1 to UpperBound(strParseErrors)
       MessageBox ("Parse Error", strParseErrors[l])
    next
  end if
catch (PBDOM_EXCEPTION pbdom_except)
  MessageBox ("PBDOM_EXCEPTION", &
     pbdom_except.GetMessage())
end try

Usage

This method retrieves a list of errors detected during the last parse operation performed by this PBDOM_BUILDER. Each string in the array has the following format:

[Line Number],[Column Number],[Error Message]

where Line Number and Column Number indicate the line number and column number in the XML document where the error was encountered. Error Message is the parse error message.