The PBDOM_DOCUMENT class defines behavior for an XML DOM document. Methods allow access to the root element, processing instructions, and other document-level information.
The PBDOM_DOCUMENT class inherits from a PBDOM_OBJECT and so provides specialized implementations for most of the PBDOM_OBJECT class methods.
Some of the inherited methods from PBDOM_OBJECT serve no meaningful objective and only default or trivial functionalities result. These are described in the following table:
Method |
Always returns |
|---|---|
Detach |
The current PBDOM_DOCUMENT |
GetName |
The string "#document" |
GetOwnerDocumentObject |
null |
GetParentObject |
null |
GetText |
An empty string |
GetTextNormalize |
An empty string |
GetTextTrim |
An empty string |
SetName |
false |
SetParentObject |
The current PBDOM_DOCUMENT |
PBDOM_DOCUMENT has the following non-trivial methods:
Allows you to add a new PBDOM_OBJECT into the current PBDOM_DOCUMENT object.
pbdom_document_name.AddContent(pbdom_object pbdom_object_ref)
Argument |
Description |
|---|---|
pbdom_document_name |
The name of a PBDOM_DOCUMENT object |
pbdom_object_ref |
The PBDOM_OBJECT to add |
PBDOM_OBJECT. The return value is the newly modified PBDOM_DOCUMENT object returned as a PBDOM_OBJECT.
EXCEPTION_USE_OF_UNNAMED_PBDOM_OBJECT – The input PBDOM_OBJECT is nameable, but it currently has no name.
EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE – The input PBDOM_OBJECT object is not associated with a derived PBDOM_OBJECT class object.
EXCEPTION_INAPPROPRIATE_USE_OF_PBDOM_OBJECT – Adding the input PBDOM_OBJECT is inappropriate. See description section below on the valid PBDOM_OBJECTs that can be added to a PBDOM_DOCUMENT object.
EXCEPTION_PBDOM_OBJECT_ALREADY_HAS_PARENT – If the PBDOM_OBJECT to be added already has a parent PBDOM_OBJECT.
EXCEPTION_MULTIPLE_ROOT_ELEMENT – If a PBDOM_ELEMENT is to be added and this document already has a root element.
EXCEPTION_MULTIPLE_DOCTYPE – If a PBDOM_DOCTYPE is to be added and this document already has a DOCTYPE.
The document pbdom_doc1 is
created with three elements: pbdom_elem_1, pbdom_elem_2,
and pbdom_elem_3. pbdom_elem_2 and pbdom_elem_3 are
set as children of pbdom_element_1. pbdom_doc1.GetRootElement().Detach()detaches
the root element from pbdom_doc1. pbdom_elem_1 is
added as a child of pbdom_doc1 with pbdom_doc1.AddContent(pbdom_elem_1).
TRY
PBDOM_ELEMENT pbdom_elem_1
PBDOM_ELEMENT pbdom_elem_2
PBDOM_ELEMENT pbdom_elem_3
PBDOM_DOCUMENT pbdom_doc1
pbdom_doc1 = Create PBDOM_DOCUMENT
pbdom_elem_1 = Create PBDOM_ELEMENT
pbdom_elem_2 = Create PBDOM_ELEMENT
pbdom_elem_3 = Create PBDOM_ELEMENT
pbdom_elem_1.SetName("pbdom_elem_1")
pbdom_elem_2.SetName("pbdom_elem_2")
pbdom_elem_3.SetName("pbdom_elem_3")
pbdom_elem_1.AddContent(pbdom_elem_2)
pbdom_elem_1.AddContent(pbdom_elem_3)
pbdom_doc1.NewDocument("", "", "Root_Element", &
"", "")
pbdom_doc1.GetRootElement().Detach()
pbdom_doc1.AddContent(pbdom_elem_1)
CATCH (pbdom_exception ex)
MessageBox("Exception", ex.getMessage())
END TRY
The original root element <Root_Element> has been detached and replaced by <pbdom_elem_1>. The document is transformed to:
<!DOCTYPE Root_Element> <pbdom_elem_1> <pbdom_elem_2/> <pbdom_elem_3/> </pbdom_elem_1>
If the following root element detachment statement is omitted, an exception is thrown:
pbdom_doc1.GetRootElement().Detach()
The new PBDOM_OBJECT becomes a child PBDOM_OBJECT of the current PBCOM_DOCUMENT. The following table lists the PBDOM_OBJECTs that can be added to a PBDOM_DOCUMENT object and the restrictions for their addition.
PBDOM_OBJECT |
Restrictions |
|---|---|
PBDOM_ELEMENT |
Allowed to be added only if this document currently does not contain any root element. Otherwise the exception EXCEPTION_MULTIPLE_ROOT_ELEMENT is thrown.The PBDOM_ELEMENT to be added must not already have a parent PBDOM_OBJECT. If it does, the exception EXCEPTION_PBDOM_OBJECT_ALREADY_HAS_PARENT is thrown. |
PBDOM_COMMENT |
Any number of PBDOM_COMMENT objects can be added to a document.The only restriction is that the PBDOM_COMMENT must not already have a parent. If so, the exception EXCEPTION_PBDOM_OBJECT_ALREADY_HAS_PARENT is thrown. |
PBDOM_ PROCESSINGINSTRUCTION |
Any number of PBDOM_PROCESSINGINSTRUCTION objects can be added to a document.The only restriction is that the PBDOM_PROCESSINGINSTRUCTION must not already have a parent. If so, the exception EXCEPTION_PBDOM_OBJECT_ALREADY_HAS_PARENT is thrown. |
PBDOM_DOCTYPE |
Allowed to be added only if this document currently does not contain any DOCTYPE node. Otherwise the exception EXCEPTION_MULTIPLE_DOCTYPE is thrown.The PBDOM_DOCTYPE to be added must not already have a parent PBDOM_OBJECT. If it does, the exception EXCEPTION_PBDOM_OBJECT_ALREADY_HAS_PARENT is thrown. |
Creates a clone of the current PBDOM_DOCUMENT object.
pbdom_document_name.Clone(boolean bDeep)
Argument |
Description |
|---|---|
pbdom_document_name |
The name of a PBDOM_DOCUMENT object |
bDeep |
A boolean specifying whether a deep or shallow clone is returned. Values are true for a deep clone and false for a shallow clone. |
PBDOM_OBJECT.
EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE – The internal implementation of the PBDOM_DOCUMENT object is null. The occurrence of this exception is rare but can happen if severe memory corruption occurs.
If you specify a deep clone, the Clone method creates a deep clone of the current PBDOM_DOCUMENT object as a PBDOM_OBJECT. The method recursively clones the subtree under the PBDOM_DOCUMENT object, where the subtree consists of all legal children of the PBDOM_DOCUMENT object.
If a shallow clone is requested, this method clones only the PBDOM_DOCUMENT object and returns a completely empty PBDOM_DOCUMENT object as a PBDOM_OBJECT.
Detaches the root element of this document and returns it.
pbdom_document_name.DetachRootElement()
Argument |
Description |
|---|---|
pbdom_document_name |
The name of a PBDOM_DOCUMENT object |
PBDOM_ELEMENT.
EXCEPTION_MEMORY_ALLOCATION_FAILURE – Insufficient memory was encountered while executing this method.
Tests for the equality of the current PBDOM_DOCUMENT object and a referenced PBDOM_OBJECT.
pbdom_document_name.Equals(pbdom_object pbdom_object_ref)
Argument |
Description |
|---|---|
pbdom_document_name |
The name of a PBDOM_OBJECT |
pbdom_object_ref |
A PBDOM_OBJECT to test for equality with the current PBDOM_OBJECT |
Boolean. Returns true if the current PBDOM_DOCUMENT object is equivalent to the input PBDOM_OBJECT, and false otherwise.
EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE – The input PBDOM_OBJECT is not associated with a derived PBDOM_OBJECT class object.
EXCEPTION_INVALID_ARGUMENT – The input PBDOM_OBJECT is invalid. This can happen if the object has not been initialized properly or is a null object reference.
True is returned only if the referenced PBDOM_OBJECT is also a PBDOM_DOCUMENT object and refers to the same DOM document as the current PBDOM_DOCUMENT object.
Returns all child content of the current PBDOM_DOCUMENT object.
pbdom_document_name.GetContent(ref pbdom_object pbdom_object_array[ ])
Argument |
Description |
|---|---|
pbdom_document_name |
The name of a PBDOM_DOCUMENT object |
pbdom_object_array |
The referenced name of an array of PBDOM_OBJECTs that receives PBDOM_OBJECTs |
Boolean. Returns true for success and false for failure.
EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE – This PBDOM_OBJECT object is not associated with a derived PBDOM_OBJECT class object.
Assume a PBDOM_DOCUMENT object called pbdom_doc contains the following XML document.
<Root> <Element_1> <Element_1_1/> <Element_1_2/> <Element_1_3/> </Element_1> <Element_2/> <Element_3/> </Root>
In the following PowerScript code fragment, the array pbdom_obj_array contains
just one PBDOM_ELEMENT which represents the element Root: pbdom_obj_array[1] -
<Root>:
PBDOM_DOCUMENT pbdom_doc PBDOM_OBJECT pbdom_obj_array[] … pbdom_doc.GetContent(pbdom_obj_array) pbdom_doc.GetRootElement().GetContent(pbdom_obj_array)
The call to GetRootElement in the last line of the previous code fragment yields an array that contains:
pbdom_obj_array[1] - <Element_1> pbdom_obj_array[2] - <Element_2> pbdom_obj_array[3] - <Element_3>
The returned PBDOM_OBJECT array can be manipulated. For example, the following statement causes Element_2 to contain the Text node “Element 2 Text”:
pbdom_obj_array[2].AddContent ("Element 2 Text")
After this call, the tree is as follows:
<Root> Element_1> Element_1_1/> Element_1_2/> Element_1_3/> /Element_1> Element_2>Element 2 Text<Element_2/> Element_3/> </Root>
The returned array is passed by reference, with items in the same order in which they appear in the PBDOM_DOCUMENT object. Any changes to any item of the array affect the actual item to which it refers.
Allows you to retrieve the DOCTYPE declaration of the current XML DOM document.
pbdom_document_name.GetDocType()
Argument |
Description |
|---|---|
pbdom_document_name |
The name of a PBDOM_DOCUMENT object |
PBDOM_DOCTYPE.
EXCEPTION_MEMORY_ALLOCATION_FAILURE – Insufficient memory was encountered while executing this method.
The DOCTYPE declaration is housed in a PBDOM_OBJECT.
Retrieves all the elements in the XML document that have the specified TagName.
pbdom_object_name.GetElementsByTagName(string strTagName, ref pbdom_element pbdom_element_array[])
Argument |
Description |
|---|---|
strTagName |
The TagName of the elements to be searched for |
pbdom_element_array[] |
A reference to a PBDOM_ELEMENT object array that has the specified TagName |
Boolean. GetElementsByTagName returns true for success and false if an exception occurs.
Assume a PBDOM_DOCUMENT contains the following XML fragment:
<book> <title>The Winter’s Tale</title> <author>William Shakespeare</author> <price>7.95</price> <quantity>1</quantity> </book> <book> <title>Le Lecon</title> <author>Eugene Ionesco</author> <price>10.95</price> <quantity>1</quantity> </book> <book> <title>Deutsches Tempo</title> <author>Kurt Tucholsky</author> <price>13.95</price> <quantity>1</quantity> </book>
The following statements extract the list of titles from the document and display it in a multilineedit control:
pbdom_document doc
pbdom_element element[]
// doc contains role elements
boolean bb_bool
bb_bool = doc.getelementsbytagname("title",element[])
integer ii_bound, i
ii_bound = upperbound(element)
for i = 1 to ii_bound
mle_1.text += element[i].gettext() + "~r~n"
next
Returns a long integer code that indicates the class of the current PBDOM_OBJECT.
pbdom_object_name.GetObjectClass()
Argument |
Description |
|---|---|
pbdom_object_name |
The name of a PBDOM_OBJECT |
Long. GetObjectClass returns a long integer code that indicates the class of the current PBDOM_OBJECT. If pbdom_object_name is a PBDOM_DOCUMENT object, the returned value is 2.
Returns a string form of the class of the PBDOM_OBJECT.
pbdom_object_name.GetObjectClassString()
Argument |
Description |
|---|---|
pbdom_object_name |
The name of a PBDOM_OBJECT |
String. GetObjectClassString returns a string that indicates the class of the current PBDOM_OBJECT. If pbdom_object_name is a PBDOM_DOCUMENT object, the returned string is “pbdom_document”.
Retrieves the root element of the current XML DOM document.
pbdom_document_name.GetRootElement()
Argument |
Description |
|---|---|
pbdom_document_name |
The name of a PBDOM_DOCUMENT object |
PBDOM_ELEMENT. The root element of the PBDOM_DOCUMENT object housed in a PBDOM_ELEMENT object.
EXCEPTION_MEMORY_ALLOCATION_FAILURE – Insufficient memory was encountered while executing this method.
The return value is the root element encapsulated in a PBDOM_ELEMENT object.
Returns true if the current PBDOM_DOCUMENT object has at least one child PBDOM_OBJECT, and false if it has none.
pbdom_document_name.HasChildren()
Argument |
Description |
|---|---|
pbdom_document_name |
The name of a PBDOM_DOCUMENT object |
Boolean. Returns true if the current PBDOM_DOCUMENT object has at least one child PBDOM_OBJECT, and false otherwise.
Returns true if this document has a root element.
pbdom_document_name.HasRootElement()
Argument |
Description |
|---|---|
pbdom_document_name |
The name of a PBDOM_DOCUMENT object |
Boolean. Returns true if the current PBDOM_DOCUMENT object has a root element, and false otherwise.
Inserts a new PBDOM_OBJECT into the current PBDOM_DOCUMENT object.
pbdom_document_name.InsertContent(pbdom_object pbdom_object_new, pbdom_object pbdom_object_ref)
Argument |
Description |
|---|---|
pbdom_document_name |
The name of a PBDOM_DOCUMENT object |
pbdom_object_new |
The PBDOM_OBJECT to insert |
pbdom_object_ref |
The PBDOM_OBJECT in front of which the new PBDOM_OBJECT will be inserted |
PBDOM_OBJECT. The modified PBDOM_DOCUMENT object returned as a PBDOM_OBJECT.
EXCEPTION_INVALID_ARGUMENT – The input PBDOM_OBJECT to insert is invalid. This can happen if it has not been initialized properly or is a null object reference.
EXCEPTION_USE_OF_UNNAMED_PBDOM_OBJECT – The input PBDOM_OBJECT to insert has not been given a user-defined name. The same exception is thrown if the reference PBDOM_OBJECT is also not given a user-defined name, unless the reference PBDOM_OBJECT is specifically set to null.
EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE – The input PBDOM_OBJECT to insert is not associated with a derived PBDOM_OBJECT. The same exception is thrown if the reference PBDOM_OBJECT is also not associated with a derived PBDOM_OBJECT, unless the reference PBDOM_OBJECT is specifically set to null.
EXCEPTION_PBDOM_OBJECT_ALREADY_HAS_PARENT – The input PBDOM_OBJECT to insert already as a parent.
EXCEPTION_MULTIPLE_ROOT_ELEMENT – A PBDOM_ELEMENT is to be inserted, but this document already has a root element.
EXCEPTION_MULTIPLE_DOCTYPE – A PBDOM_DOCTYPE is to be inserted, but this document already has a DOCTYPE.
EXCEPTION_HIERARCHY_ERROR – Inserting the PBDOM_OBJECT adversely affects how well-formed the document is.
EXCEPTION_INAPPROPRIATE_USE_OF_PBDOM_OBJECT – An invalid PBDOM_OBJECT is to be inserted. See AddContent for information on the valid PBDOM_OBJECTs that can be added to a PBDOM_DOCUMENT object.
EXCEPTION_WRONG_PARENT_ERROR – The reference PBDOM_OBJECT is not a child of this PBDOM_DOCUMENT object.
A PBDOM_DOCUMENT object is created from an XML string. The PBDOM_ELEMENT pbdom_elem_1 is also created and set as Elem_1. The PBDOM_DOCTYPE pbdom_doctype_1 and the root element pbdom_root_elem are set.The root element is detached from its parent, which is also the PBDOM_DOCUMENT object itself. This makes it possible to insert pbdom_elem_1 into the document specifically before pbdom_doctype_1.
pbdom_builder pbdom_builder_1
pbdom_document pbdom_doc
pbdom_doctype pbdom_doctype_1
pbdom_element pbdom_elem_1
pbdom_element pbdom_elem_root
string strXML
strXML = "<!DOCTYPE abc [<!-- internal subset -->"
strXML += "<!ELEMENT abc (#PCDATA)> "
strXML += "<!ELEMENT data&(#PCDATA)> "
strXML += "<!ELEMENT inner_data (#PCDATA)>]><abc>"
strXML += "Root Element Data<data>ABC Data<inner_data>"
strXML += "My Inner Data</inner_data>My Data</data>"
strXML += " now with extra& info</abc>"
pbdom_builder_1 = Create PBDOM_Builder
pbdom_elem_1 = Create PBDOM_Element
pbdom_doc = pbdom_builder_1.BuildFromString (strXML)
pbdom_elem_1.SetName ("Elem_1")
pbdom_doctype_1 = pbdom_doc.GetDocType()
pbdom_elem_root = pbdom_doc.GetRootElement()
pbdom_elem_root.Detach()
pbdom_doc.InsertContent(pbdom_elem_1, pbdom_doctype_1
The result is the following document, which is not well-formed:
<Elem_1/> <!DOCTYPE abc[<!-- internal subset --> <!ELEMENT abc (#PCDATA)*> <!ELEMENT data (#PCDATA)*> <!ELEMENT inner_data (#PCDATA)*>]>
When a new PBDOM_OBJECT is inserted into the current PBDOM_DOCUMENT object, the new PBDOM_OBJECT becomes a child node of the current PBDOM_DOCUMENT object. Also, the new PBDOM_OBJECT is to be positioned specifically before another PBDOM_OBJECT, denoted using the second parameter.
If the second PBDOM_OBJECT is specified as null, then the new PBDOM_OBJECT is to be inserted at the end of the list of children of the current PBDOM_DOCUMENT object.
The IsAncestorObjectOf method determines whether the current PBDOM_DOCUMENT object is the ancestor of another PBDOM_OBJECT.
pbdom_document_name.IsAncestorObjectOf(pbdom_object pbdom_object_ret)
Argument |
Description |
|---|---|
pbdom_document_name |
The name of a PBDOM_DOCUMENT object |
pbdom_object_ref |
The PBDOM_OBJECT to check against |
Boolean. Returns true if the current PBDOM_DOCUMENT object is the ancestor of the referenced PBDOM_OBJECT, and false otherwise.
EXCEPTION_INVALID_ARGUMENT – The input PBDOM_OBJECT is invalid. This can happen if it has not been initialized properly or is a null object reference.
The NewDocument method is overloaded:
Syntax 1 creates a new XML DOM document using the name of the root element to be contained within the new DOM document.
Syntax 2 creates a new XML DOM document using the name and namespace URI of the root element to be contained in the new DOM document, and also the external subset public and system identifiers.
For this syntax |
See |
|---|---|
NewDocument(string strRootElementName) |
|
NewDocument( string strRootElementNamespacePrefix, stringstrRootElementNamespaceURI, string strRootElementName, string strDocTypePublicId, string strDocTypeSystemId) |
Creates a new XML DOM document from scratch.
pbdom_document_name.NewDocument(strRootElementName)
Argument |
Description |
|---|---|
pbdom_document_name |
The name of a PBDOM_DOCUMENT object |
strRootElementName |
The name of the root element to be contained in the DOM document |
Boolean. Returns true if a new document is successfully created and false otherwise.
EXCEPTION_INVALID_ARGUMENT – The input string is invalid, which can occur if the string was set to null by means of the PowerScript SetNull method.
EXCEPTION_MEMORY_ALLOCATION_FAILURE – Insufficient memory was encountered while executing this method.
The parameter strRootElementName becomes the name of the root element.
Creates a new XML DOM document from scratch.
pbdom_document_name.NewDocument(string strRootElementNamespacePrefix, string strRootElementNamespaceURI, string strRootElementName, string strDocTypePublicId, string strDocTypeSystemId)
Argument |
Description |
|---|---|
pbdom_document_name |
The name of a PBDOM_DOCUMENT object. |
strRootElementNamespacePrefix |
The namespace prefix of the root element to be contained in the DOM document. This can be an empty string. |
strRootElementNamespaceURI |
The namespace URI of the root element to be contained in the DOM document. This can be an empty string. |
strRootElementName |
The name of the root element to be contained in the DOM document. |
strDocTypePublicId |
The external subset public identifier. |
strDocTypeSystemId |
The external subset system identifier. |
Boolean. Returns true if a new document is successfully created, and false otherwise.
EXCEPTION_INVALID_ARGUMENT – One of the input strings is invalid. This can happen if the string has been set to null using the PowerScript SetNull method.
EXCEPTION_MEMORY_ALLOCATION_FAILURE – Insufficient memory was encountered while executing this method.
EXCEPTION_INVALID_NAME – The root element name, or the root element namespace prefix or URI, is invalid.
EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE – This PBDOM_DOCUMENT object's internal implementation is NULL. The occurrence of this exception is rare but can take place if severe memory corruption occurs.
This example attempts to create a PBDOM_DOCUMENT object in which the root element belongs to no namespace, as indicated by the empty strings for the namespace prefix and URI arguments to NewDocument:
PBDOM_DOCUMENT pbdom_doc
try
pbdom_doc = Create PBDOM_DOCUMENT
pbdom_doc.NewDocument ("", "", "root", "public_id", &
"system_id.dtd")
pbdom_doc.SaveDocument &
("new_document_no_namespace.xml")
catch (PBDOM_EXCEPTION except)
MessageBox ("PBDOM_EXCEPTION", except.GetMessage())
end try
When serialized, the XML document looks like the following :
<!DOCTYPE root PUBLIC "public_id" "system_id.dtd"> <root xmlns=""/>
The namespace declaration attribute (xmlns="")
present in the root element indicates that the root element belongs
to no namespace.
This example attempts to create a PBDOM_DOCUMENT
object in which the root element belongs to a default namespace.
The URI is http://www.pre.com,
which means that the root element belongs to the namespace http://www.pre.com.
The prefix is an empty string, which means that the root element
belongs to the http://www.pre.com namespace
by default:
PBDOM_DOCUMENT pbdom_doc
try
pbdom_doc = Create PBDOM_DOCUMENT
pbdom_doc.NewDocument ("", "http://www.pre.com", &
"root", "public_id", "system_id.dtd")
pbdom_doc.SaveDocument &
("new_document_default_namespace.xml")
catch (PBDOM_EXCEPTION except)
MessageBox ("PBDOM_EXCEPTION", except.GetMessage())
end try
When serialized, the XML document looks like the following :
<!DOCTYPE root PUBLIC "public_id" "system_id.dtd"> <root xmlns="http://www.pre.com"/>
The namespace declaration attribute (xmlns="http://www.pre.com") present
in the root element indicates that the root element belongs to the
default namespace http://www.pre.com.
All child elements of root belong to this same namespace
unless another in-scope namespace declaration is present and is used.
This example attempts to create a PBDOM_DOCUMENT
object in which the root element belong to a prefixed namespace.
The namespace prefix is pre and
the URI is http://www.pre.com.
This means that the root element will belong to the namespace http://www.pre.com,
and that the root element will have a namespace prefix of pre:
PBDOM_DOCUMENT pbdom_doc
try
pbdom_doc = Create PBDOM_DOCUMENT
pbdom_doc.NewDocument ("pre", "http://www.pre.com", &
"root", "public_id", "system_id.dtd")
pbdom_doc.SaveDocument &
("new_document_namespace.xml")
catch (PBDOM_EXCEPTION except)
MessageBox ("PBDOM_EXCEPTION", except.GetMessage())
end try
When serialized, the XML document looks like the following :
<!DOCTYPE pre:root PUBLIC "public_id" "system_id.dtd"> <pre:root xmlns:pre="http://www.pre.com"/>
A namespace declaration attribute (xmlns:pre="http://www.pre.com")
is present in the root element. The root element also contains a pre prefix.
This indicates that the root element belongs to the namespace http://www.pre.com. However,
the fact that the http://www.pre.com namespace
is prefixed by pre indicates that the child
elements of root belong to this same namespace only if their qualified
names also contain the pre prefix and there
is an in-scope namespace declaration for http://www.pre.com that
is prefixed by pre.
Using the five parameters available with this syntax provides more control over the DOCTYPE definition of the document.
Removes a child PBDOM_OBJECT from the current PBDOM_DOCUMENT object.
pbdom_document_name.RemoveContent(pbdom_object pbdom_object_ref)
Argument |
Description |
|---|---|
pbdom_document_name |
The name of a PBDOM_DOCUMENT object |
pbdom_object_ref |
The PBDOM_OBJECT to remove |
Boolean. Returns true if the content was removed, and false otherwise.
EXCEPTION_INVALID_ARGUMENT– The input PBDOM_OBJECT to remove is invalid. This can happen if it has not been initialized properly or is a null object reference.
EXCEPTION_USE_OF_UNNAMED_PBDOM_OBJECT – The input PBDOM_OBJECT is nameable, but it has not been assigned a name.
EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE – The input PBDOM_OBJECT is not associated with a derived PBDOM_OBJECT class object.
EXCEPTION_WRONG_DOCUMENT_ERROR – The input PBDOM_OBJECT is not contained within the current PBDOM_DOCUMENT object.
EXCEPTION_WRONG_PARENT_ERROR – The input PBDOM_OBJECT is not a child of the current PBDOM_DOCUMENT object.
When a PBDOM_OBJECT is removed from the current PBDOM_DOCUMENT object, all children under the removed PBDOM_OBJECT are also removed.
Saves the serialized XML string of the DOM tree contained within the PBDOM_DOCUMENT object into a disk file.
pbdom_document_name.SaveDocument(string strFileName)
Argument |
Description |
|---|---|
pbdom_document_name |
The name of a PBDOM_DOCUMENT object |
strFileName |
The name of the disk file to which the contents of the current PBDOM_DOCUMENT object is to be serialized |
Boolean. Returns true if a new document was successfully saved to a disk file, and false otherwise.
EXCEPTION_INVALID_ARGUMENT – The input string specifying the file name is invalid. This can happen if the string has been set to null using the PowerScript SetNull method.
EXCEPTION_MEMORY_ALLOCATION_FAILURE – Insufficient memory was encountered while executing this method.
A PBDOM_DOCUMENT object that has been created from an existing XML document or string can differ from its original after it has been converted back to an XML string or document. This can occur even if no modifications have been made to the PBDOM_DOCUMENT object using PowerScript.
This can occur if the original XML document or string referred to an external DTD that mandates the inclusion of default attributes. In this case, PBDOM complies with the rules of the DTD and inserts these required attributes into the relevant elements while building up the in-memory DOM tree.
When the PBDOM_DOCUMENT object is saved and converted back to an XML document, these default attributes are saved in the document.
Saves the serialized XML string of the DOM tree contained within the PBDOM_DOCUMENT object into a string.
pbdom_document_name.SaveDocumentIntoString( )
Argument |
Description |
|---|---|
pbdom_document_name |
The name of a PBDOM_DOCUMENT object |
String. Returns a string containing the XML string of the PBDOM_DOCUMENT.
This code creates a new PBDOM_DOCUMENT and saves it to the string ls_xml:
PBDOM_DOCUMENT pbdom_doc
string ls_xml
try
pbdom_doc = Create PBDOM_DOCUMENT
pbdom_doc.NewDocument ("pre", "http://www.pre.com", &
"root", "public_id", "system_id.dtd")
ls_xml = pbdom_doc.SaveDocumentIntoString
catch (PBDOM_EXCEPTION except)
MessageBox ("PBDOM_EXCEPTION", except.GetMessage())
end try
Sets the entire content of the PBDOM_DOCUMENT object, removing pre-existing children first.
pbdom_document_name.SetContent(pbdom_object pbdom_object_array)
Argument |
Description |
|---|---|
pbdom_document_name |
The name of a PBDOM_DOCUMENT object |
pbdom_object_array |
An array of PBDOM_OBJECTs set as the contents of the PBDOM_DOCUMENT object |
pbdom_object_array must contain only PBDOM_OBJECT objects that can legally be set as the contents of a PBDOM_DOCUMENT object. The SetContent method restricts the array to one PBDOM_ELEMENT object to set as the root element of the PBDOM_DOCUMENT object from which the method is invoked. The SetContent method also restricts the array to one PBDOM_DOCTYPE object to set as the DOCTYPE of the PBDOM_DOCUMENT object.
PBDOM_OBJECT. The modified PBDOM_DOCUMENT object returned as a PBDOM_OBJECT.
EXCEPTION_ILLEGAL_PBOBJECT – An array item is not a valid PBDOM object. This can happen if the array item has not been initialized properly or is a null object reference.
EXCEPTION_USE_OF_UNNAMED_PBDOM_OBJECT – An array item is nameable and has not been given a user-defined name.
EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE – An array item is not associated with a derived PBDOM_OBJECT.
EXCEPTION_PBDOM_OBJECT_ALREADY_HAS_PARENT – An array item already has a parent PBDOM_OBJECT.
EXCEPTION_MULTIPLE_ROOT_ELEMENT – The array contains more than one PBDOM_ELEMENT. The array must contain at most one PBDOM_ELEMENT that is set as the root element of this document.
EXCEPTION_MULTIPLE_DOCTYPE – The array contains more than one PBDOM_DOCTYPE. The array must contain at most one PBDOM_DOCTYPE that is set as the DOCTYPE of this document.
EXCEPTION_MULTIPLE_XMLDECL – The array contains more than one PBDOM_PROCESSINGINSTRUCTION that has been constructed into an XML Declaration.
EXCEPTION_INAPPROPRIATE_USE_OF_PBDOM_OBJECT – An array item is not allowed to be set as a document-level content.
The supplied array contains PBDOM_OBJECTs that can legally be set as the content of a PBDOM_DOCUMENT object.For example, a PBDOM_DOCUMENT object accepts only an array that contains PBDOM_ELEMENT, PBDOM_COMMENT, PBDOM_DOCTYPE, or PBDOM_PROCESSINGINSTRUCTION objects. In addition, the array can contain at most one PBDOM_ELEMENT object that it sets as its root element, at most one PBDOM_DOCTYPE object that it sets as its DOCTYPE, and at most one XML declaration .PBDOM_PROCESSINGINSTRUCTION.
In the event of an exception, the original contents of this PBDOM_DOCUMENT object are unchanged, and the PBDOM_OBJECTs contained in the supplied array are unaltered.
Sets the DOCTYPE declaration of this document.
pbdom_document_name.SetDocType(pbdom_doctype pbdom_doctype_ref)
Argument |
Description |
|---|---|
pbdom_document_name |
The name of a PBDOM_DOCUMENT object |
pbdom_doctype_ref |
A PBDOM_DOCTYPE object to be set as the DOCTYPE of this document |
PBDOM_DOCUMENT. The same PBDOM_DOCUMENT object with a modified DOCTYPE declaration.
EXCEPTION_INVALID_ARGUMENT – The input PBDOM_DOCTYPE is invalid. This can happen if it has not been initialized properly or is a null object reference.
EXCEPTION_USE_OF_UNNAMED_PBDOM_OBJECT – The input PBDOM_DOCTYPE is nameable and has not been given a user-defined name.
EXCEPTION_WRONG_DOCUMENT_ERROR – The input PBDOM_DOCTYPE already has an owner document.
EXCEPTION_PBDOM_OBJECT_ALREADY_HAS_PARENT – The input PBDOM_DOCTYPE is already the DOCTYPE of another document.
If this document already contains a DOCTYPE declaration, the new PBDOM_DOCTYPE replaces it. The DOCTYPE of a PBDOM_DOCUMENT object can be changed multiple times, and it is legal for a user to call the SetDocType method multiple times.
A DOM DOCTYPE object can have no owner document, or it can have an owner document but no parent node. A DOCTYPE that has an owner document as well as a parent node is the actual DOCTYPE of the owner document.
Sets the root element for this document.
pbdom_document_name.SetRootElement(pbdom_element pbdom_element_ref)
Argument |
Description |
|---|---|
pbdom_document_name |
The name of a PBDOM_DOCUMENT object |
pbdom_element_ref |
A PBDOM_ELEMENT object to be set as the root element for this document |
PBDOM_DOCUMENT. The PBDOM_DOCUMENT object with a modified root element.
EXCEPTION_INVALID_ARGUMENT – The input PBDOM_ELEMENT is invalid. This can happen if it has not been initialized properly or is a null object reference.
EXCEPTION_USE_OF_UNNAMED_PBDOM_OBJECT – The input PBDOM_ELEMENT is nameable and it has not been given a user-defined name.
EXCEPTION_PBDOM_OBJECT_ALREADY_HAS_PARENT – The input PBDOM_ELEMENT already has a parent PBDOM_OBJECT.
If this document already has a root element, the existing root element is replaced. The root element of a PBDOM_DOCUMENT object can be changed multiple times, and it is legal for a user to call the SetRootElement method multiple times.
