PBDOM_DOCUMENT

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:


AddContent

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 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()

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

GetContent

InsertContent

RemoveContent

SetContent

Clone

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.

DetachRootElement

Description

Detaches the root element of this document and returns it.

Syntax

pbdom_document_name.DetachRootElement()

Argument

Description

pbdom_document_name

The name of a PBDOM_DOCUMENT object


Return value

PBDOM_ELEMENT.

Throws

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

See also

GetRootElement

HasRootElement

SetRootElement

Equals

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.

GetContent

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

AddContent

InsertContent

RemoveContent

SetContent

GetDocType

Description

Allows you to retrieve the DOCTYPE declaration of the current XML DOM document.

Syntax

pbdom_document_name.GetDocType()

Argument

Description

pbdom_document_name

The name of a PBDOM_DOCUMENT object


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.

GetElementsByTagName

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

GetObjectClass

Description

Returns a long integer code that indicates the class of the current PBDOM_OBJECT.

Syntax

pbdom_object_name.GetObjectClass()

Argument

Description

pbdom_object_name

The name of a PBDOM_OBJECT


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.

GetObjectClassString

Description

Returns a string form of the class of the PBDOM_OBJECT.

Syntax

pbdom_object_name.GetObjectClassString()

Argument

Description

pbdom_object_name

The name of a PBDOM_OBJECT


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".

GetRootElement

Description

Retrieves the root element of the current XML DOM document.

Syntax

pbdom_document_name.GetRootElement()

Argument

Description

pbdom_document_name

The name of a PBDOM_DOCUMENT object


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

DetachRootElement

HasRootElement

SetRootElement

HasChildren

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()

Argument

Description

pbdom_document_name

The name of a PBDOM_DOCUMENT object


Return value

Boolean.

Returns true if the current PBDOM_DOCUMENT object has at least one child PBDOM_OBJECT, and false otherwise.

HasRootElement

Description

Returns true if this document has a root element.

Syntax

pbdom_document_name.HasRootElement()

Argument

Description

pbdom_document_name

The name of a PBDOM_DOCUMENT object


Return value

Boolean.

Returns true if the current PBDOM_DOCUMENT object has a root element, and false otherwise.

See also

DetachRootElement

GetRootElement

SetRootElement

InsertContent

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_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)*>]>

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

AddContent

GetContent

RemoveContent

SetContent

IsAncestorObjectOf

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.

NewDocument

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 Syntax 1 

NewDocument(
string strRootElementNamespacePrefix, stringstrRootElementNamespaceURI, 
string strRootElementName, 
string strDocTypePublicId, 
string strDocTypeSystemId)

NewDocument Syntax 2 


NewDocument Syntax 1

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

SaveDocument

NewDocument Syntax 2

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

  1. 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.

  2. 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.

  3. 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.

Usage

Using the five parameters available with this syntax provides more control over the DOCTYPE definition of the document.

See also

SaveDocument

RemoveContent

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

AddContent

GetContent

InsertContent

SetContent

SaveDocument

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

NewDocument

SaveDocumentIntoString

Description

Saves the serialized XML string of the DOM tree contained within the PBDOM_DOCUMENT object into a string.

Syntax

pbdom_document_name.SaveDocumentIntoString( )

Argument

Description

pbdom_document_name

The name of a PBDOM_DOCUMENT object


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 try

See also

SaveDocument

SetContent

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

AddContent

GetContent

InsertContent

RemoveContent

SetDocType

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.

SetRootElement

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

DetachRootElement

GetRootElement

HasRootElement