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:
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
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 TRYUsage
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
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
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 tryUsage
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.
