PowerBuilder Extension Reference
PBDOM_ELEMENT Class

Description

The AddContent method is overloaded:

Syntax

AddContent(pbdom_object pbdom_object_ref)

AddContent(string strText)

pbdom_element_name.AddContent(pbdom_object pbdom_object_ref)

     <Element_1>
          <Element_1_1/>
          <Element_1_2/>
          <Element_1_3/>
     </Element_1>
     <Element_2>Element 2 Text</Element_2>
     <Element_3/>

PBDOM_ELEMENT pbdom_elem
pbdom_elem = Create PBDOM_ELEMENT
pbdom_elem.SetName("Sub_Element")
pbdom_elem.AddContent("Sub Element Text")
pbdom_elem_2.AddContent (pbdom_elem)

     <Element_1>
          <Element_1_1/>
          <Element_1_2/>
          <Element_1_3/>
     </Element_1>
     <Element_2>
          Element 2 Text
          <Sub_Element>
                    Sub Element Text
          </Sub_Element>
     <Element_2/>
     <Element_3/>

pbdom_element_name.AddContent(string strText)

<abc>
     Root Element Data
     <data>
          ABC Data
          <inner_data>My Inner Data</inner_data>
     </data>
</abc>

pbdom_doc.GetRootElement().AddContent(" And More !")

<abc>
     Root Element Data
     <data>
          ABC Data
          <inner_data>My Inner Data</inner_data>
     </data>
     And More !
</abc>

Description

Adds a new namespace declaration to this PBDOM_ELEMENT object. The new namespace can apply to the PBDOM_ELEMENT object itself if the namespace becomes the default namespace in the PBDOM_ELEMENT object.

Syntax

pbdom_element_name.AddNamespaceDeclaration(string strNamespacePrefix, string strNamespaceUri)

Return value

PBDOM_ELEMENT. The modified PBDOM_ELEMENT object.

Throws

EXCEPTION_INVALID_ARGUMENT  -- If any of the input parameters is invalid (null).

EXCEPTION_INVALID_NAME  -- If the input Prefix is invalid, as, for example, if it contains a colon.

EXCEPTION_INVALID_STRING -- If the input URI is invalid.

EXCEPTION_MEMORY_ALLOCATION_FAILURE  -- If memory allocation failure occurred in this method.

Examples

Consider the following element:

<Vehicle>
  <seats>4</seats>
  <color>Red</color>
  <engine>
     <capacity units="cc">1600</capacity>
  </engine>
</Vehicle>

Given a PBDOM_ELEMENT object elem_vehicle that represents the Vehicle element, consider the following statement:

elem_vehicle.AddNamespaceDeclaration("vehicle_specs",&
   "http://www.vehicle.com/specs")

It transforms the Vehicle element as follows:

<Vehicle xmlns:vehicle_specs="http://www.vehicle.com/specs">
  <seats>4</seats>
  <color>Red</color>
  <engine>
     <capacity units="cc">1600</capacity>
  </engine>
</Vehicle>

Vehicle, seats, color, engine, and capacity are all unqualified (that is, they have no namespace prefix). Therefore, the vehicle_specs namespace does not apply to any of them or their attributes or subelements.

However, consider the following statement:

elem_vehicle.AddNamespaceDeclaration("", &
   "http://www.vehicle.com/specs")

It transforms the Vehicle element as follows:

<Vehicle xmlns:"http://www.vehicle.com/specs">
  <seats>4</seats>
  <color>Red</color>
  <engine>
     <capacity units="cc">1600</capacity>
  </engine>
</Vehicle>

http://www.vehicle.com/specs is the default namespace and so Vehicle, seats, color, engine, and capacity are all part of this namespace. Note that the default namespace does not apply to the units attribute.

See also

GetNamespacePrefix

GetNamespaceUri

GetQualifiedName

RemoveNamespaceDeclaration

SetNamespace

Description

Creates a clone of a PBDOM_ELEMENT object.

Syntax

pbdom_element_name.Clone(boolean bDeep)

Return value

PBDOM_OBJECT. A clone of this PBDOM_ELEMENT object returned as a PBDOM_OBJECT.

Examples

The Clone method is used to alter the following XML:

<Telephone_Book>
     <Entry>
          <Particulars>
               <Name>John Doe</Name>
               <Age>21</Age>
               <Phone_Number>1234567</Phone_Number>
          </Particulars>
     </Entry>
</Telephone_Book>

The Clone method is invoked from the following PowerScript code, where entry represents the Entry> element in the preceding XML:

PBDOM_ELEMENT elem_clone

elem_clone = entry.Clone(true)
pbdom_doc.AddContent(elem_clone)

The resulting XML contains two identical Entry> elements:

<Telephone_Book>
     <Entry>
          <Particulars>
               <Name>John Doe</Name>
               <Age>21</Age>
               <Phone_Number>1234567</Phone_Number>
          </Particulars>
     </Entry>
     <Entry>
          <Particulars>
               <Name>John Doe</Name>
               <Age>21</Age>
               <Phone_Number>1234567</Phone_Number>
          </Particulars>
     </Entry>
</Telephone_Book>

Usage

This method creates and returns a duplicate of the current PBDOM_ELEMENT object. If a shallow clone is requested, this method clones the PBDOM_ELEMENT object together with its namespace information values and its PBDOM_ATTRIBUTEs and their subtrees. If a deep clone is requested, this method additionally recursively clones the subtree under the PBDOM_ELEMENT object.

A PBDOM_ELEMENT clone has no parent. However, the clone resides in the same PBDOM_DOCUMENT as its original, and if the original PBDOM_ELEMENT object is standalone, the clone is standalone.

Description

Detaches a PBDOM_ELEMENT object from its parent PBDOM_OBJECT.

Syntax

pbdom_element_name.Detach()

Return value

PBDOM_OBJECT. The PBDOM_ELEMENT object detached from its parent object and returned as a PBDOM_OBJECT. If the PBDOM_ELEMENT object has no parent, the Detach method does nothing.

Description

Tests for equality between the PBDOM_ELEMENT object from which the method is invoked and a PBDOM_OBJECT indicated by the method parameter.

Syntax

pbdom_element_name.Equals(pbdom_object pbdom_object_ref)

Return value

Boolean.

Returns true if the PBDOM_ELEMENT object is equivalent to the referenced PBDOM_OBJECT and false otherwise.

Examples

The Equals method is invoked from the following PowerScript code, in which pbdom_doc represents a PBDOM_DOCUMENT object containing a root element:

PBDOM_ELEMENT pbdom_elem_1
PBDOM_ELEMENT pbdom_elem_2
PBDOM_OBJECT pbdom_obj
PBDOM_DOCUMENT pbdom_doc

pbdom_elem_1 = pbdom_doc.GetRootElement()
pbdom_elem_2 = pbdom_doc.GetRootElement()

IF pbdom_elem_1.Equals(pbdom_elem_2) THEN
   MessageBox ("Equals", "The objects are equal")
ELSE
   MessageBox ("Equals", "The objects are NOT equal")
END IF

pbdom_obj  = Create PBDOM_ELEMENT
pbdom_obj.SetName("An_Element")

IF pbdom_elem_1.Equals(pbdom_obj) THEN
   MessageBox ("Equals", "The objects are equal")
ELSE
   MessageBox ("Equals", "The objects are NOT equal")
END IF

Because pbdom_elem_1 and pbdom_elem_2 refer to the same root element, a message box reports that the objects are equal.

Description

The GetAttribute method is overloaded:

Syntax

GetAttribute(string strName)

GetAttribute(string strName, string strNamespacePrefix, string strNamespaceUri)

pbdom_element_name.GetAttribute(string strName)

<MyMusic:abc xmlns:MyMusic="http://www.MyMusic_records.com"  My_Attr="My MyMusic Attribute">Root Element Data</MyMusic:abc>

pbdom_attr = &
   pbdom_doc.GetRootElement().GetAttribute("My_Attr")

pbdom_element_name.GetAttribute(string strName, string strNamespacePrefix, string strNamespaceUri)

Description

Returns the complete set of PBDOM_ATTRIBUTE objects for a PBDOM_ELEMENT object.

If there are no PBDOM_ATTRIBUTE objects for the PBDOM_ELEMENT object, the GetAttributes method returns an empty array.

Syntax

pbdom_element_name.GetAttributes(ref pbdom_attribute pbdom_attribute_array)

Return value

Boolean.

Returns true if an array of PBDOM_ATTRIBUTE objects for the PBDOM_ELEMENT object has been retrieved, and false otherwise.

Usage

GetAttributes returns the complete set of PBDOM_ATTRIBUTE objects for a PBDOM_ELEMENT object as an array of PBDOM_ATTRIBUTE objects, or as an empty list (empty array) if there are none. The returned array items are "live" and changes to any item affect the referenced PBDOM_ATTRIBUTE.

See also

GetAttribute

GetAttributeValue

HasAttributes

SetAttribute

SetAttributes

Description

The GetAttributeValue method is overloaded:

Syntax

GetAttributeValue(string strAttributeName)

GetAttributeValue(string strAttributeName, string strNamespacePrefix, string strNamespaceUri)

GetAttributeValue(string strAttributeName, string strNamespacePrefix, string strNamespaceUri, string strDefaultValue)

GetAttributeValue(string strAttributeName, string strDefaultValue)

pbdom_element_name.GetAttributeValue(string strAttributeName)

pbdom_element_name.GetAttributeValue( string strAttributeName, string strNamespacePrefix, string strNamespaceUri)

pbdom_element_name.GetAttributeValue( string strAttributeName, string strNamespacePrefix, string strNamespaceUri, string strDefaultValue)

pbdom_element_name.GetAttributeValue(string strAttributeName, string strDefaultValue)

Description

The GetChildElement method is overloaded:

Syntax

GetChildElement(string strElementName)

GetChildElement(string strElementName, string strNamespacePrefix, string strNamespaceUri)

pbdom_element_name.GetChildElement(string strElementName)

pbdom_element_name.GetChildElement(string strElementName, string strNamespacePrefix, string strNamespaceUri)

Description

The GetChildElements method is overloaded:

Syntax

GetChildElements(ref pbdom_element pbdom_element_array[])

GetChildElements(string strElementName, ref pbdom_element pbdom_element_array[])

GetChildElements(string strElementName, string strNamespacePrefix, string strNamespaceUri, ref pbdom_element pbdom_element_array[])

pbdom_element_name.GetChildElements(ref pbdom_element pbdom_element_array)

pbdom_element_name.GetChildElements(string strElementName, ref pbdom_element pbdom_element_array[])

pbdom_element_name.GetChildElements(string strElementName, string strNamespacePrefix, string strNamespaceUri, ref pbdom_element pbdom_element_array[])

Description

Obtains an array of PBDOM_OBJECT objects, each of which is a child node of the PBDOM_ELEMENT object from which the method is invoked. The returned array is "live" in that changes to any item of the array affect the actual item to which the array refers.

Syntax

pbdom_element_name.GetContent(ref pbdom_object pbdom_object_array[ ])

Return value

Boolean.

Returns true for success and false otherwise.

Throws

EXCEPTION_INVALID_ARGUMENT  -- If the input array is null.

Examples

The GetContent method is invoked for the Root> PBDOM_ELEMENT object in the following XML DOM document:

<Root>
     <Element_1>
          <Element_1_1/>
          <Element_1_2/>
          <Element_1_3/>
     </Element_1>
     <Element_2/>
     <Element_3/>
</Root>

The GetContent method is invoked from the following PowerScript code:

PBDOM_DOCUMENT pbdom_doc
PBDOM_ELEMENT pbdom_elem_root
PBDOM_OBJECT pbdom_obj_array[]

pbdom_elem_root = pbdom_doc.GetRootElement()
pbdom_elem_root.GetContent(pbdom_obj_array)

If the GetContent method returns the value true, the PBDOM_OBJECT object pbdom_obj_array then contains the following content:

See also

AddContent Syntax 1

AddContent Syntax 2

InsertContent

RemoveContent

SetContent

Description

Retrieves the local name of a PBDOM_ELEMENT object.

Syntax

pbdom_element_name.GetName()

Return value

String.

The name of the element as it appears in the XML document but without any namespace prefix.

Examples

The GetName method returns the string abc when it is invoked for the name of the following element:

<ns:abc>My Element</ns:abc>

Usage

For an XML element that appears in the form [namespace_prefix]:[element_name], the local element name is element_name. When the XML element has no namespace prefix, the local name is simply the element name.

Use the GetQualifiedName method to obtain the fully qualified name of an element (with the namespace prefix).

See also

GetNamespacePrefix

GetNamespaceUri

RemoveNamespaceDeclaration

SetName

Description

Returns the namespace prefix for a PBDOM_ELEMENT object. If no namespace prefix exists for the PBDOM_ELEMENT object, GetNamespacePrefix returns an empty string.

Syntax

pbdom_element_name.GetNamespacePrefix()

Return value

String.

The namespace prefix for the PBDOM_ELEMENT object.

See also

AddNamespaceDeclaration

GetNamespaceUri

GetQualifiedName

RemoveNamespaceDeclaration

SetNamespace

Description

Returns the URI that is mapped to a PBDOM_ELEMENT object prefix or, if there is no prefix, to the PBDOM_ELEMENT object default namespace. If no URI is mapped to the PBDOM_ELEMENT object, GetNameSpaceUri returns an empty string.

Syntax

pbdom_element_name.GetNamespaceUri()

Return value

String.

The namespace URI for the PBDOM_ELEMENT object.

See also

AddNamespaceDeclaration

GetNamespacePrefix

GetQualifiedName

RemoveNamespaceDeclaration

SetNamespace

Description

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

Syntax

pbdom_object_name.GetObjectClass()

Return value

Long.

A code that indicates the class of the current PBDOM_OBJECT. If pbdom_object_name is a PBDOM_ELEMENT object, the returned value is 3.

Examples

The GetObjectClass method returns a value specific to the class of the object from which the method is invoked.

PBDOM_OBJECT pbdom_obj

pbdom_obj = Create PBDOM_ELEMENT
MessageBox ("Class", &
   string(pbdom_obj.GetObjectClass()))

This example illustrates polymorphisms: pbdom_obj is declared as PBDOM_OBJECT but instantiated as PBDOM_ELMENT. A message box returns the result of the GetObjectClass method invoked for PBDOM_ELEMENT object. Here the result is 3, indicating that pbdom_obj is a PBDOM_ELEMENT object.

Usage

This method can be used for diagnostic purposes to dynamically determine the type of a PBDOM_OBJECT at runtime.

Description

Returns a string form of the class of the PBDOM_OBJECT.

Syntax

pbdom_object_name.GetObjectClassString()

Return value

String.

A string that indicates the class of the current PBDOM_OBJECT. If pbdom_object_name is a PBDOM_ELEMENT object, the returned string is "pbdom_element".

Examples

The GetObjectClass method returns a string specific to the class of the object from which the method is invoked.

PBDOM_OBJECT pbdom_obj

pbdom_obj = Create PBDOM_ELEMENT
MessageBox ("Class", pbdom_obj.GetObjectClassString())

This example illustrates polymorphisms: pbdom_obj is declared as PBDOM_OBJECT but instantiated as PBDOM_ELEMENT object. A message box returns the result of the GetObjectClassString method invoked for PBDOM_ELEMENT object. Here the result is pbdom_element, indicating that pbdom_obj is a PBDOM_ELEMENT object.

Usage

This method can be used for diagnostic purposes to dynamically determine the actual type of a PBDOM_OBJECT at runtime.

Description

Returns the PBDOM_DOCUMENT object that owns the PBDOM_ELEMENT object.

Syntax

pbdom_element_name.GetOwnerDocumentObject()

Return value

PBDOM_DOCUMENT. The PBDOM_DOCUMENT that owns the PBDOM_ELEMENT object from which the GetOwnerDocumentObject method is invoked. A return value of null indicates that the PBDOM_ELEMENT object is not owned by any PBDOM_DOCUMENT.

Examples

The GetOwnerDocumentObject method is invoked from the following PowerScript code, where pbdom_root_elem refers to the root element of the PBDOM_DOCUMENT object pbdom_doc:

PBDOM_DOCUMENT pbdom_doc
PBDOM_ELEMENT pbdom_root_elem

pbdom_root_elem = pbdom_doc.GetRootElement()

IF 
   pbdom_doc.Equals &
   (pbdom_root_elem.GetOwnerDocumentObject())
THEN
     MessageBox ("Equals", "The objects are equal")
END IF

The Equals method tests for equality between pbdom_doc and the PBDOM_DOCUMENT object returned from the GetOwnerDocumentObject method. A message box reports that the objects are equal.

See also

GetParentObject

SetParentObject

Description

Returns the parent object for the PBDOM_ELEMENT object.

Syntax

pbdom_element_name.GetParentObject()

Return value

PBDOM_OBJECT. The parent object of the PBDOM_ELEMENT object from which the GetParentObject method is invoked. A return value of null indicates the PBDOM_ELEMENT object has no parent.

See also

GetOwnerDocumentObject

SetParentObject

Description

Returns the full name of a PBDOM_ELEMENT object in the form [namespace_prefix]:[local_name]. If there is no namespace prefix for the PBDOM_ELEMENT object, the GetQualifiedName method returns the local name.

Syntax

pbdom_element_name.GetQualifiedName()

Return value

String.

The full name of the PBDOM_ELEMENT object. The full name consists of both a namespace prefix and a local name.

See also

AddNamespaceDeclaration

GetNamespacePrefix

GetNamespaceUri

RemoveNamespaceDeclaration

SetNamespace

Description

Obtains a concatenation of the text values of all the PBDOM_TEXT and PBDOM_CDATA nodes contained within the PBDOM_ELEMENT object from which the method is invoked.

Syntax

pbdom_element_name.GetText()

Return value

String

Examples

The GetText method is invoked for the abc PBDOM_ELEMENT object:

<abc>Root Element Data<data>ABC Data </data> now with extra info</abc>

The GetText method returns the following string:

Root Element Data now with extra info

The text "ABC Data" is excluded because it is not contained within the PBDOM_ELEMENT abc.

See also

GetTextNormalize

GetTextTrim

SetText

Description

Returns the normalized text data contained in a PBDOM_ELEMENT object.

Syntax

pbdom_element_name.GetTextNormalize()

Return value

String

Examples

The GetTextNormalize method is invoked for the abc element of the following XML:

<abc>     Root      Element      Data     <data>ABC Data </data> now with extra info     </abc>

The GetTextNormalize method returns the following string:

Root Element Data now with extra info

Usage

The text data returned includes any text data contained in PBDOM_CDATA objects. All surrounding whitespace characters are removed. Internal whitespace characters are normalized to a single space. The GetTextNormalize method returns an empty string if no text values exist for the PBDOM_ELEMENT object or if there are only whitespace characters.

See also

GetText

GetTextTrim

SetText

Description

Returns the text data contained within a PBDOM_ELEMENT object with any leading and trailing whitespace characters removed.

Syntax

pbdom_element_name.GetTextTrim()

Return value

String

Examples

The GetTextTrim method is invoked for the abc element of the following XML:

<abc>     Root    Element Data <![CDATA[ with       some cdata text   ]]></abc>

The GetTextTrim method returns the following string:

Root Element Data with some cdata text

Usage

Surrounding whitespace characters are removed from the returned text data. The GetTextTrim method returns an empty string if no text value exists for the PBDOM_ELEMENT object or if the text value contains only whitespace characters.

See also

GetText

GetTextNormalize

SetText

Description

Indicates whether a PBDOM_ELEMENT object has one or more attributes.

Syntax

pbdom_element_name.HasAttributes()

Return value

Boolean.

Returns true if this PBDOM_ELEMENT object has at least one attribute and false if this PBDOM_ELEMENT object has no attributes.

Examples

In the following document fragment, only the element site has an attribute (href):

<books>
   <title>Inside Wizardry</title>
   <author>Ron Potter</author>
   <site href="http://www.mybooks.com/press"/>
</books>

If the PBDOM_ELEMENT object pbdom_elem_site represents the element site, the following call returns true:

pbdom_elem_site.HasAttributes()

See also

GetAttribute

GetAttributes

GetAttributeValue

SetAttribute

SetAttributes

Description

Indicates whether a PBDOM_ELEMENT object has one or more child PBDOM_ELEMENT objects.

Syntax

pbdom_element_name.HasChildElements()

Return value

Boolean.

Returns true if this PBDOM_ELEMENT object has at least one child PBDOM_ELEMENT object and false if this PBDOM_ELEMENT object has no child PBDOM_ELEMENT objects.

Examples

The HasChildElements method is invoked for the books PBDOM_ELEMENT object in the following XML fragment:

<books>
   <title>Inside OLE</title>
   <author>Kraig Brockschmidt</author>
   <site href="http://www.microsoft.com/press"/>
</books>

The books object has three child PBDOM_ELEMENT objects: title, author, and site. The HasChildElements method returns true.

See also

GetChildElement

GetChildElements

HasChildren

IsRootElement

RemoveChildElement

RemoveChildElements

Description

Indicates whether a PBDOM_ELEMENT object has one or more child objects.

Syntax

pbdom_element_name.HasChildren()

Return value

Boolean.

Returns true if this PBDOM_ELEMENT object has at least one child object and false if this PBDOM_ELEMENT object has no child objects.

Examples

The HasChildren method is invoked for elements in the following XML fragment:

<books>
     <title>Inside OLE</title>
     <author>Kraig Brockschmidt</author>
     <site href="http://www.microsoft.com/press"/>
</books>

The books element has three child elements: title, author, and site. The title and author elements each have a child PBDOM_TEXT object. The HasChildren method returns a value of true when invoked for these elements.

In contrast, the site element has a PBDOM_ATTRIBUTE href, which is not considered a child PBDOM_OBJECT. The HasChildren method returns a value of False when invoked for the site element.

Usage

PBDOM's implementation of the HasChildren method differs from JDOM's implementation in that the JDOM HasChildren method returns true only if an Element contains child Elements. Text and other types of objects do not count.

PBDOM provides an alternative method, HasChildElements, to specifically detect whether a PBDOM_ELEMENT object has at least one child PBDOM_ELEMENT object.

See also

HasChildElements

IsRootElement

Description

Inserts a new PBDOM_OBJECT into a PBDOM_ELEMENT object.

Syntax

pbdom_element_name.InsertContent(pbdom_object pbdom_object_new, pbdom_object pbdom_object_ref)

Return value

PBDOM_OBJECT. The PBDOM_ELEMENT object modified and returned as a PBDOM_OBJECT.

Throws

EXCEPTION_INAPPROPRIATE_USE_OF_PBDOM_OBJECT  -- If an invalid PBDOM_OBJECT is added. See AddContent for the valid PBDOM_OBJECT objects that can be added to a PBDOM_ELEMENT object. This exception is also thrown if the input PBDOM_OBJECT or the reference PBDOM_OBJECT is this PBDOM_ELEMENT object itself.

EXCEPTION_USE_OF_UNNAMED_PBDOM_OBJECT  -- If the input PBDOM_OBJECT to insert has not been given a user-defined name. The same exception is also 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  -- If the input PBDOM_OBJECT to insert is not associated with a derived PBDOM_OBJECT. The same exception is also 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_INVALID_ARGUMENT  -- If the reference PBDOM_OBJECT (second parameter) is intended to be null but is not specifically set to null using the SetNull method.

EXCEPTION_PBDOM_OBJECT_ALREADY_HAS_PARENT  -- If the input PBDOM_OBJECT to insert already has a parent.

EXCEPTION_WRONG_PARENT_ERROR  -- If the reference PBDOM_OBJECT is not a child of this PBDOM_ELEMENT object.

EXCEPTION_HIERARCHY_ERROR  -- If inserting the input PBDOM_OBJECT will cause the current PBDOM_ELEMENT object to be no longer well formed.

Examples

The following PowerScript code is used to create an XML document:

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_doc1.NewDocument ("", "", "Root_Element", "", "")
pbdom_elem_root = pbdom_doc1.GetRootElement()
pbdom_elem_root.AddContent (pbdom_elem_1)
pbdom_elem_root.AddContent (pbdom_elem_3)

The following XML results:

!DOCTYPE Root_Element> 
<Root_Element>
     <pbdom_elem_1 /> 
     <pbdom_elem_3 /> 
</Root_Element>

The InsertContent method is used to add an element between pbdom_elem_1 and pbdom_elem_3:

pbdom_elem_root.InsertContent(pbdom_elem_2, &
   pbdom_elem_3)

The following XML results:

<!DOCTYPE Root_Element> 
<Root_Element>
     <pbdom_elem_1 /> 
     <pbdom_elem_2 /> 
     <pbdom_elem_3 /> 
</Root_Element>

Usage

The inserted object becomes a child of the PBDOM_ELEMENT object. The new PBDOM_OBJECT is positioned before another PBDOM_OBJECT, which is specified in the second of two parameters.

See also

AddContent Syntax 1

AddContent Syntax 2

GetContent

RemoveContent

SetContent

Description

Determines whether a PBDOM_ELEMENT object is the ancestor of the PBDOM_OBJECT indicated by the method parameter.

Syntax

pbdom_element_name.IsAncestorObjectOf(pbdom_object pbdom_object_ref)

Return value

Boolean.

Returns true if this PBDOM_ELEMENT object is the ancestor of the specified PBDOM_OBJECT, and false otherwise.

Description

Indicates whether a PBDOM_ELEMENT object is the root element of a PBDOM_DOCUMENT object.

Syntax

pbdom_element_name.IsRootElement()

Return value

Boolean.

Returns true if this PBDOM_ELEMENT object is the root element of a PBDOM_DOCUMENT, and false otherwise.

See also

GetChildElement

GetChildElements

HasChildElements

HasChildren

RemoveChildElement

RemoveChildElements

Description

The RemoveAttribute method is overloaded:

Syntax

RemoveAttribute(pbdom_attribute pbdom_attribute_ref)

RemoveAttribute(string strAttributeName)

RemoveAttribute(string strAttributeName, string strNamespacePrefix, string strNamespaceUri)

pbdom_element_name.RemoveAttribute(pbdom_attribute pbdom_attribute_ref)

pbdom_element_name.RemoveAttribute(string strAttributeName)

bdom_element_name.RemoveAttribute(string strAttributeName, string strNamespacePrefix, string strNamespaceUri)

Description

The RemoveChildElement method is overloaded:

Syntax

RemoveChildElement(string strElementName)

RemoveChildElement(string strElementName, string strNamespacePrefix, string strNamespaceUri)

pbdom_element_name.RemoveChildElement(string strElementName)

pbdom_element_name.RemoveChildElement(string strElementName, string strNamespacePrefix, string strNamespaceUri)

Description

The RemoveChildElements method is overloaded:

Syntax

RemoveChildElements()

RemoveChildElements(string strElementName)

RemoveChildElements(string strElementName, string strNamespacePrefix, string strNamespaceUri)

pbdom_element_name.RemoveChildElements()

pbdom_element_name.RemoveChildElements(string strElementName)

pbdom_element_name.RemoveChildElements(string strElementName, string strNamespacePrefix, string strNamespaceUri)

Description

Removes a child PBDOM_OBJECT from a PBDOM_ELEMENT object. All children of the removed PBDOM_OBJECT are also removed.

Syntax

pbdom_element_name.RemoveContent(pbdom_object pbdom_object_ref)

Return value

Boolean.

Returns true if the specified content was removed and false otherwise.

Throws

EXCEPTION_USE_OF_UNNAMED_PBDOM_OBJECT  -- If the input PBDOM_OBJECT has not been given a user-defined name.

EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE  -- If the input PBDOM_OBJECT is not associated with a derived PBDOM_OBJECT.

EXCEPTION_WRONG_DOCUMENT_ERROR  -- If the input PBDOM_OBJECT is not from the same document as this PBDOM_ELEMENT object.

EXCEPTION_WRONG_PARENT_ERROR  -- If the input PBDOM_OBJECT is not a child of the current PBDOM_ELEMENT object.

Examples

The RemoveContent method is used to modify the following XML fragment:

<Telephone_Book>
     <Entry>
          <Particulars>
               <Name>John Doe</Name>
               <Age>21</Age>
               <Phone_Number>1234567</Phone_Number>
          </Particulars>
     </Entry>
</Telephone_Book>

The RemoveContent method is invoked from the following PowerScript code:

PBDOM_DOCUMENT pbdom_doc
PBDOM_ELEMENT pbdom_entry

pbdom_doc.GetRootElement().RemoveContent(pbdom_entry)

The following XML results:

<Telephone_Book></Telephone_Book>

See also

AddContent Syntax 1

AddContent Syntax 2

GetContent

InsertContent

SetContent

Description

Removes the specified PBDOM_NAMESPACE declaration for a PBDOM_ELEMENT object. If the namespace prefix is an empty string, RemoveNamespaceDeclaration removes a default namespace declaration.

Syntax

pbdom_element_name.RemoveNamespaceDeclaration(string strNamespacePrefix, string strNamespaceUri)

Return value

Boolean.

Returns true if the namespace has been removed from the PBDOM_ELEMENT object, and false otherwise.

Throws

EXCEPTION_INVALID_ARGUMENT  -- If any of the input parameters is invalid, for example, null.

EXCEPTION_INVALID_NAME  -- If the namespace prefix or URI is invalid, or both the namespace prefix and URI are invalid as a pair.

EXCEPTION_MEMORY_ALLOCATION_FAILURE  -- If any memory allocation failure occurred during the execution of this method.

See also

AddNamespaceDeclaration

GetNamespacePrefix

GetNamespaceUri

GetQualifiedName

SetNamespace

Description

The SetAttribute method is overloaded:

Syntax

SetAttribute(pbdom_attribute pbdom_attribute_ref)

SetAttribute(string strName, string strValue)

SetAttribute(string strName, string strValue, string strNamespacePrefix, string strNamespaceUri, boolean bVerifyNamespace)

pbdom_element_name.SetAttribute(pbdom_attribute pbdom_attribute_ref)

<root xmlns:pre1="http://www.pre.com" xmlns:pre2="http://www.pre.com">
   <child1 pre1:a="123"/>
</root>

PBDOM_BUILDER pbdom_buildr
PBDOM_DOCUMENT pbdom_doc
PBDOM_ATTRIBUTE pbdom_attr
string strXML = "<root xmlns:pre1=~"http://www.pre.com~" xmlns:pre2=~"http://www.pre.com~"><child1 pre1:a=~"123~"/></root>"

try
  pbdom_buildr = Create PBDOM_BUILDER
  pbdom_doc = pbdom_buildr.BuildFromString (strXML)
  
  // Create a PBDOM_ATTRIBUTE and set its properties
  pbdom_attr = Create PBDOM_ATTRIBUTE
  pbdom_attr.SetName ("a")
  pbdom_attr.SetNamespace ("pre2", &
     "http://www.pre.com", false)
  pbdom_attr.SetText("456")
  
  // Attempt to obtain the child1 element and 
  // set the new attribute to it
  pbdom_doc.GetRootElement(). &
    GetChildElement("child1").SetAttribute(pbdom_attr)
  
  pbdom_doc.SaveDocument &
     ("pbdom_elem_set_attribute_1.xml")

catch (PBDOM_EXCEPTION except)
  MessageBox ("PBDOM_EXCEPTION", except.GetMessage())
end try

<root xmlns:pre1="http://www.pre.com" xmlns:pre2="http://www.pre.com"
   <child1 pre2:a="456"/
</root

pbdom_element_name.SetAttribute(string strName, string strValue)

pbdom_element_name.SetAttribute(string strName, string strValue, string strNamespacePrefix, string strNamespaceUri, boolean bVerifyNamespace)

Description

Sets the attributes for the DOM element represented by the current PBDOM_ELEMENT object.

Syntax

pbdom_element_name.SetAttributes(pbdom_attribute pbdom_attribute_array[])

Return value

PBDOM_ELEMENT. The PBDOM_ELEMENT object modified.

Throws

EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE  -- The internal implementation of this PBDOM_ELEMENT object or one of the PBDOM_ATTRIBUTE array items is null. This exception is rare but can take place if severe memory corruption occurs.

EXCEPTION_INVALID_ARGUMENT  -- One of the PBDOM_ATTRIBUTE array items is null.

EXCEPTION_INVALID_NAME  -- If two or more PBDOM_ATTRIBUTEs in the array contain the same name and namespace URI.

EXCEPTION_USE_OF_UNNAMED_PBDOM_OBJECT  -- One of the PBDOM_ATTRIBUTE array items has not been named.

EXCEPTION_PBDOM_OBJECT_ALREADY_HAS_OWNER  -- One of the PBDOM_ATTRIBUTE array items already has an owner PBDOM_ELEMENT object.

Examples

This example demonstrates setting the attributes of a PBDOM_ELEMENT object using an array of PBDOM_ATTRIBUTE objects. It builds a PBDOM_DOCUMENT based on the following XML:

<root xmlns:pre1="http://www.pre.com">
   <child1 pre1:a="123"/>
</root>

The code creates an array of three PBDOM_ATTRIBUTE objects with names a, b, and c, and sets their namespace prefixes and URIs to pre1 and http://www.pre.com. The call to SetAttributes attempts to set the attributes of child1 using the PBDOM_ATTRIBUTEs of this array. When you save PBDOM_DOCUMENT and convert it to an XML document, the result is:

<root xmlns:pre1="http://www.pre.com">
   <child1 pre1:a="456" pre1:b="456" pre1:c="456" />
</root>

Although child1 originally contained the pre1:a attribute, and the PBDOM_ATTRIBUTE array also contained an item with name a within the namespace URI http://www.pre.com, no exception is thrown. The original pre1:a attribute is replaced by the PBDOM_ATTRIBUTE array item with name a within the namespace URI http://www.pre.com.

PBDOM_BUILDER     pbdom_buildr
PBDOM_DOCUMENT    pbdom_doc
PBDOM_ATTRIBUTE   pbdom_attr_array[]
string            Name[]
long              l = 0
string strXML = "<root xmlns:pre1=~"http://www.pre.com~"><child1 pre1:a=~"123~"/></root>"

try
  pbdom_buildr = Create PBDOM_BUILDER
  pbdom_doc = pbdom_buildr.BuildFromString (strXML)
  
  Name[1] = "a"
  Name[2] = "b"
  Name[3] = "c"

  for l = 1 to 3
    pbdom_attr_array[l] = Create PBDOM_ATTRIBUTE
    pbdom_attr_array[l].SetName (Name[l])
    pbdom_attr_array[l].SetNamespace ("pre1", &
      "http://www.pre.com", false)
    pbdom_attr_array[l].SetText("456")
  next 

    pbdom_doc.GetRootElement().GetChildElement &
      ("child1").SetAttributes(pbdom_attr_array)
    pbdom_doc.SaveDocument ("set_attributes.xml")

catch (PBDOM_EXCEPTION except)
  MessageBox ("PBDOM_EXCEPTION", except.GetMessage())
end try

Usage

This method sets the attributes of the DOM element represented by this PBDOM_ELEMENT object. The supplied array should contain only objects of type PBDOM_ATTRIBUTE.

When all objects in the supplied array are legal and before the new attributes are added, all old attributes have their parentage set to null (no parent) and the old attribute list is cleared from this PBDOM_ELEMENT object. This has the effect that any active attribute list (previously obtained with a call to GetAttributes) also changes to reflect the new situation with the old attributes. In addition, all PBDOM_ATTRIBUTEs in the supplied array have their parentage set to this current PBDOM_ELEMENT object.

Passing an empty array clears the existing attributes of this PBDOM_ELEMENT object.

This method fails and an exception is thrown if the PBDOM_ATTRIBUTE array contains two or more PBDOM_ATTRIBUTEs with the same name and namespace URI.

No exception is thrown if this PBDOM_ELEMENT object contains an existing attribute whose name and namespace URI matches one of the PBDOM_ATTRIBUTE array items. All the existing attributes of this PBDOM_ELEMENT object are removed, so it does not matter whether any existing attribute matches any of the PBDOM_ATTRIBUTE items in the array in terms of name and namespace URI.

In the event of an exception, the original attributes of the PBDOM_ELEMENT object remain unchanged, and the PBDOM_ATTRIBUTEs in the supplied array are not altered.

If any PBDOM_ATTRIBUTE has been created to represent any original attribute, it is still valid, but the attribute it represents has been detached from the original owner element. Calling GetOwnerElementObject on this PBDOM_ATTRIBUTE returns a null value.

See also

GetAttribute

GetAttributes

GetAttributeValue

HasAttributes

SetAttribute

Description

Sets the content of the PBDOM_ELEMENT object using an array containing PBDOM_OBJECT objects legal for a PBDOM_ELEMENT object. Any existing children of the PBDOM_ELEMENT object are removed when the SetContent method is invoked.

If the input array reference is null, all contents of the PBDOM_ELEMENT object are removed. If the array contains illegal objects, an exception is thrown, and nothing is altered.

Syntax

pbdom_element_name.SetContent(pbdom_object pbdom_object_array[])

Return value

PBDOM_OBJECT. The PBDOM_ELEMENT object modified and returned as a PBDOM_OBJECT.

Throws

EXCEPTION_USE_OF_UNNAMED_PBDOM_OBJECT  -- If an input PBDOM_OBJECT array item has not been given a user-defined name.

EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE  -- If an input PBDOM_OBJECT array item is not associated with a derived PBDOM_OBJECT.

EXCEPTION_PBDOM_OBJECT_ALREADY_HAS_PARENT  -- If an input PBDOM_OBJECT array item already has a parent PBDOM_OBJECT.

EXCEPTION_INAPPROPRIATE_USE_OF_PBDOM_OBJECT  -- If an inappropriate PBDOM_OBJECT array item is found. This happens if the PBDOM_OBJECT array item is not allowed to be added as a child of a PBDOM_ELEMENT object (for example, a PDBOM_DOCUMENT).

EXCEPTION_HIERARCHY_ERROR  -- If one of the PBDOM_OBJECT array items, if set as part of the contents of this PBDOM_ELEMENT object, will cause the current PBDOM_ELEMENT object to be no longer well formed.

Examples

The SetContent method is invoked on the following XML fragment:

<Telephone_Book>
     <Entry>
          <Particulars>
               <Name>John Doe</Name>
               <Age>21</Age>
               <Phone_Number>1234567</Phone_Number>
          </Particulars>
     </Entry>
</Telephone_Book>

The SetContent method is invoked from the following PowerScript code:

PBDOM_OBJECT pbdom_obj_array[]

pbdom_obj_array[1] = entry_1
pbdom_obj_array[2] = entry_2

pbdom_doc.GetRootElement().SetContent(pbdom_obj_array)

The entry_1 PBDOM_ELEMENT object contains the following:

     <Entry>
          <Particulars>
               <Name>James Gomez</Name>
               <Age>25</Age>
               <Phone_Number>1111111</Phone_Number>
          </Particulars>
     </Entry>

The entry_2 PBDOM_ELEMENT object contains the following:

     <Entry>
          <Particulars>
               <Name>Mary Jones</Name>
               <Age>22</Age>
               <Phone_Number>2222222</Phone_Number>
          </Particulars>
     </Entry>

The SetContent method returns the following:

<Telephone_Book>
     <Entry>
          <Particulars>
               <Name>James Gomez</Name>
               <Age>25</Age>
               <Phone_Number>1111111</Phone_Number>
          </Particulars>
     </Entry>
     <Entry>
          <Particulars>
               <Name>Mary Jones</Name>
               <Age>22</Age>
               <Phone_Number>2222222</Phone_Number>
          </Particulars>
     </Entry>
</Telephone_Book>

Usage

Only the following PBDOM_OBJECT types can be validly added to a PBDOM_ELEMENT object:

See also

AddContent Syntax 1

AddContent Syntax 2

GetContent

InsertContent

RemoveContent

Description

Sets a PBDOM_DOCUMENT as parent of a PBDOM_ELEMENT object, making the PBDOM_ELEMENT object the root element.

Syntax

pbdom_element_name.SetDocument(pbdom_document pbdom_document_ref)

Return value

PBDOM_ELEMENT. The modified PBDOM_ELEMENT object.

Usage

The PBDOM_OBJECT referenced must be a PBDOM_DOCUMENT object. The PBDOM_ELEMENT object must not already have a parent object. If the target PBDOM_DOCUMENT already has a root element, the existing root element is replaced by the new PBDOM_ELEMENT object.

Description

Sets the local name of a PBDOM_ELEMENT object. This name refers to the local portion of the element tag name.

Syntax

pbdom_element_name.SetName(string strName)

Return value

Boolean.

Returns true if the local name of the PBDOM_ELEMENT object has been changed, and false otherwise.

Examples

The SetName method is invoked for the abc element of the following XML fragment:

<abc>My Data</abc>

The SetName method is invoked in the following PowerScript code, in which the PBDOM_ELEMENT object elem represents the abc element.

elem.SetName("def")

The following XML results:

<def>My Data</def>

Since the elem object still represents the same element, calling the SetName method changes the def element.

See also

GetName

Description

Sets the namespace for a PBDOM_ELEMENT object. If the namespace prefix and URI provided are empty strings, SetNamespace assigns no namespace to the PBDOM_ELEMENT object.

Syntax

pbdom_element_name.SetNamespace(string strNamespacePrefix, string strNamespaceUri, boolean bVerifyNamespace)

Return value

Long.

Returns 0 for success and -1 if no in-scope namespace declaration matching the input prefix and URI exists.

Throws

EXCEPTION_INVALID_ARGUMENT  -- If any of the input arguments is invalid, for example, null.

EXCEPTION_INVALID_NAME -- If the input namespace prefix or URI is invalid.

EXCEPTION_MEMORY_ALLOCATION_FAILURE  -- If a memory allocation failure occurred during the execution of this method.

EXCEPTION_INTERNAL_XML_ENGINE_ERROR  -- If an internal XML engine failure occurred during the execution of this method.

Usage

If bVerifyNamespace is set to true and the namespace prefix and URI have not been declared, SetNamespace returns a value of -1 and fails.

If bVerifyNamespace is set to false, SetNamespace sets the namespace of the PBDOM_ELEMENT object to the specified prefix and URI. It is the responsibility of the PBDOM user to ensure that such a namespace is declared and is in scope for this PBDOM_ELEMENT object before the document is saved and converted to an XML document.

See also

AddNamespaceDeclaration

GetNamespacePrefix

GetNamespaceUri

GetQualifiedName

RemoveNamespaceDeclaration

Description

Sets the referenced PBDOM_OBJECT as the parent of the PBDOM_ELEMENT object from which the method is invoked.

Syntax

pbdom_element_name.SetParentObject(pbdom_object pbdom_object_ref)

Return value

PBDOM_OBJECT. The PBDOM_ELEMENT object modified and returned as a PBDOM_OBJECT.

Throws

EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE  -- If the input PBDOM_OBJECT is not associated with a derived PBDOM_OBJECT.

EXCEPTION_PBDOM_OBJECT_ALREADY_HAS_PARENT  -- The input PBDOM_OBJECT already has a parent.

EXCEPTION_INAPPROPRIATE_USE_OF_PBDOM_OBJECT  -- If the input PBDOM_OBJECT is not allowed to be the parent of a PBDOM_ELEMENT object.

EXCEPTION_USE_OF_UNNAMED_PBDOM_OBJECT  -- If the input PBDOM_OBJECT is nameable and has not been named.

Usage

If the class of the referenced PBDOM_OBJECT is PBDOM_DOCUMENT, then the behavior of SetParentObject is identical to that of the SetDocument method. If the class of the referenced PBDOM_OBJECT is PBDOM_ELEMENT, SetParentObject sets the referenced object as the parent of the PBDOM_ELEMENT object from which the method is invoked. If the referenced PBDOM_OBJECT is of any other class, an exception is thrown.

See also

GetOwnerDocumentObject

GetParentObject

Description

Sets the content of a PBDOM_ELEMENT object to the text provided.

Syntax

pbdom_element_name.SetText(string strText)

Return value

PBDOM_OBJECT. The PBDOM_ELEMENT object modified and returned as a PBDOM_OBJECT.

Usage

Existing text content and non-text content are replaced by the text provided in strText. A value of null for strText is equivalent to an empty string value. If the PBDOM_ELEMENT is to have both text content and nested elements, use the SetContent method instead of SetText.

See also

GetText

GetTextNormalize

GetTextTrim