Description
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.
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:
Description
Allows you to add a new PBDOM_OBJECT into the current PBDOM_DOCUMENT object.
Syntax
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 |
Return value
PBDOM_OBJECT. The return value is the newly modified PBDOM_DOCUMENT object returned as a PBDOM_OBJECT.
Throws
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.
Examples
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 TRYThe 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()
Usage
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. |
See also
Description
Creates a clone of the current PBDOM_DOCUMENT object.
Syntax
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. |
Return value
PBDOM_OBJECT.
Throws
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.
Usage
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.
Description
Detaches the root element of this document and returns it.
Syntax
pbdom_document_name.DetachRootElement()
Return value
PBDOM_ELEMENT.
Throws
EXCEPTION_MEMORY_ALLOCATION_FAILURE -- Insufficient memory was encountered while executing this method.
See also
Description
Tests for the equality of the current PBDOM_DOCUMENT object and a referenced PBDOM_OBJECT.
Syntax
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 |
Return value
Boolean.
Returns true if the current PBDOM_DOCUMENT object is equivalent to the input PBDOM_OBJECT, and false otherwise.
Throws
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.
Usage
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.
Description
Returns all child content of the current PBDOM_DOCUMENT object.
Syntax
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_OBJECTsthat receives PBDOM_OBJECTs |
Return value
Boolean.
Returns true for success and false for failure.
Throws
EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE -- This PBDOM_OBJECT object is not associated with a derived PBDOM_OBJECT class object.
Examples
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>Usage
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.
See also
Description
Allows you to retrieve the DOCTYPE declaration of the current XML DOM document.
Syntax
pbdom_document_name.GetDocType()
Return value
PBDOM_DOCTYPE.
Throws
EXCEPTION_MEMORY_ALLOCATION_FAILURE -- Insufficient memory was encountered while executing this method.
Usage
The DOCTYPE declaration is housed in a PBDOM_OBJECT.
Description
Retrieves all the elements in the XML document that have the specified TagName.
Syntax
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 |
Return value
Boolean.
GetElementsByTagName returns true for success and false if an exception occurs.
Examples
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
Description
Returns a long integer code that indicates the class of the current PBDOM_OBJECT.
Syntax
pbdom_object_name.GetObjectClass()
Return value
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.
Description
Returns a string form of the class of the PBDOM_OBJECT.
Syntax
pbdom_object_name.GetObjectClassString()
Return value
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".
Description
Retrieves the root element of the current XML DOM document.
Syntax
pbdom_document_name.GetRootElement()
Return value
PBDOM_ELEMENT. The root element of the PBDOM_DOCUMENT object housed in a PBDOM_ELEMENT object.
Throws
EXCEPTION_MEMORY_ALLOCATION_FAILURE -- Insufficient memory was encountered while executing this method.
Usage
The return value is the root element encapsulated in a PBDOM_ELEMENT object.
See also
Description
Returns true if the current PBDOM_DOCUMENT object has at least one child PBDOM_OBJECT, and false if it has none.
Syntax
pbdom_document_name.HasChildren()
Return value
Boolean.
Returns true if the current PBDOM_DOCUMENT object has at least one child PBDOM_OBJECT, and false otherwise.
Description
Returns true if this document has a root element.
Syntax
pbdom_document_name.HasRootElement()
Return value
Boolean.
Returns true if the current PBDOM_DOCUMENT object has a root element, and false otherwise.
See also
Description
Inserts a new PBDOM_OBJECT into the current PBDOM_DOCUMENT object.
Syntax
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 |
Return value
PBDOM_OBJECT. The modified PBDOM_DOCUMENT object returned as a PBDOM_OBJECT.
Throws
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.
Examples
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_1The 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)*>]>
Usage
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.
See also
Description
The IsAncestorObjectOf method determines whether the current PBDOM_DOCUMENT object is the ancestor of another PBDOM_OBJECT.
Syntax
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 |
Return value
Boolean.
Returns true if the current PBDOM_DOCUMENT object is the ancestor of the referenced PBDOM_OBJECT, and false otherwise.
Throws
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.
Description
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.
Syntax
|
For this syntax |
See |
|---|---|
NewDocument(string strRootElementName) |
|
NewDocument( string strRootElementNamespacePrefix, stringstrRootElementNamespaceURI, string strRootElementName, string strDocTypePublicId, string strDocTypeSystemId) |
Description
Creates a new XML DOM document from scratch.
Syntax
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 |
Return value
Boolean.
Returns true if a new document is successfully created and false otherwise.
Throws
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.
Usage
The parameter strRootElementName becomes the name of the root element.
See also
Description
Creates a new XML DOM document from scratch.
Syntax
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. |
Return value
Boolean.
Returns true if a new document is successfully created, and false otherwise.
Throws
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.
Examples
-
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 tryWhen 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 tryWhen 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 tryWhen 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.
Usage
Using the five parameters available with this syntax provides more control over the DOCTYPE definition of the document.
See also
Description
Removes a child PBDOM_OBJECT from the current PBDOM_DOCUMENT object.
Syntax
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 |
Return value
Boolean.
Returns true if the content was removed, and false otherwise.
Throws
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.
Usage
When a PBDOM_OBJECT is removed from the current PBDOM_DOCUMENT object, all children under the removed PBDOM_OBJECT are also removed.
See also
Description
Saves the serialized XML string of the DOM tree contained within the PBDOM_DOCUMENT object into a disk file.
Syntax
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 |
Return value
Boolean.
Returns true if a new document was successfully saved to a disk file, and false otherwise.
Throws
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.
Usage
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.
See also
Description
Saves the serialized XML string of the DOM tree contained within the PBDOM_DOCUMENT object into a string.
Syntax
pbdom_document_name.SaveDocumentIntoString( )
Return value
String.
Returns a string containing the XML string of the PBDOM_DOCUMENT.
Examples
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 trySee also
Description
Sets the entire content of the PBDOM_DOCUMENT object, removing pre-existing children first.
Syntax
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.
Return value
PBDOM_OBJECT. The modified PBDOM_DOCUMENT object returned as a PBDOM_OBJECT.
Throws
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.
Usage
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.
See also
Description
Sets the DOCTYPE declaration of this document.
Syntax
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 |
Return value
PBDOM_DOCUMENT. The same PBDOM_DOCUMENT object with a modified DOCTYPE declaration.
Throws
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.
Usage
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.
Description
Sets the root element for this document.
Syntax
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 |
Return value
PBDOM_DOCUMENT. The PBDOM_DOCUMENT object with a modified root element.
Throws
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.
Usage
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.
See also
