PBDOM_ELEMENT

Description

The PBDOM_ELEMENT class defines the behavior for an XML element modeled in PowerScript. Methods allow the user to obtain the text content of an element, the attributes of an element, and the children of an element.

In PBDOM, an XML element's attributes are not its children. Attributes are properties of elements rather than having a separate identity from the elements with which they are associated. An element's PBDOM_ATTRIBUTE objects do not have sibling relationships with each other in the same way as the element's children.

For more information on the relationships among PBDOM_ELEMENT and PBDOM_ATTRIBUTE objects, see the chapter on XML services in Application Techniques.

Methods

PBDOM_ELEMENT has the following methods:


AddContent

Description

The AddContent method is overloaded:

  • Syntax 1 adds a new PBDOM_OBJECT into a PBDOM_ELEMENT object.

  • Syntax 2 adds a new text string to the PBDOM_ELEMENT object from which the method is invoked.

Syntax

For this syntax

See

AddContent(pbdom_object pbdom_object_ref)

AddContent Syntax 1 

AddContent(string strText)

AddContent Syntax 2 


AddContent Syntax 1

Description

Adds a new PBDOM_OBJECT into a PBDOM_ELEMENT object. The added PBDOM_OBJECT becomes a child of the PBDOM_ELEMENT object.

Syntax

pbdom_element_name.AddContent(pbdom_object pbdom_object_ref)

Argument

Description

pbdom_element_name

The name of a PBDOM_ELEMENT object

pbdom_object_ref

The PBDOM_OBJECT to add


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 description section below on the valid PBDOM_OBJECTs that can be added to a PBDOM_ELEMENT object. This exception is also thrown if the input PBDOM_OBJECT is this PBDOM_ELEMENT object itself.

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_PBDOM_OBJECT_ALREADY_HAS_PARENT  -- If the input PBDOM_OBJECT already has a parent PBDOM_OBJECT.

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

Examples

The AddContent method is invoked for the Element_2 PBDOM_ELEMENT object in the following XML fragment:

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

The AddContent is invoked from the following PowerScript code, where pbdom_elem_2 represents the Element_2 object:

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)

The following XML fragment results:

     <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/>

Usage

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

  • PBDOM_ELEMENT

  • PBDOM_CDATA

  • PBDOM_COMMENT

  • PBDOM_ENTITYREFERENCE

  • PBDOM_PROCESSINGINSTRUCTION

  • PBDOM_TEXT

See also

AddContent Syntax 2

GetContent

InsertContent

RemoveContent

SetContent

AddContent Syntax 2

Description

Adds a new text string to the PBDOM_ELEMENT object from which the method is invoked.

Syntax

pbdom_element_name.AddContent(string strText)

Argument

Description

pbdom_element_name

The name of a PBDOM_ELEMENT object

strText

A string to be added to the PBDOM_ELEMENT object as new text content


Return value

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

Examples

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

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

The AddContent method is invoked from the following PowerScript statement:

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

The following XML results:

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

See also

AddContent Syntax 1

GetContent

InsertContent

RemoveContent

SetContent

AddNamespaceDeclaration

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)

Argument

Description

pbdom_element_name

The name of a PBDOM_ELEMENT object

strNamespacePrefix

The prefix of the new namespace to be declared

strNamespaceUri

The URI of the new namespace to be declared


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

Clone

Description

Creates a clone of a PBDOM_ELEMENT object.

Syntax

pbdom_element_name.Clone(boolean bDeep)

Argument

Description

pbdom_element_name

The name of a PBDOM_ELEMENT 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. 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.

Detach

Description

Detaches a PBDOM_ELEMENT object from its parent PBDOM_OBJECT.

Syntax

pbdom_element_name.Detach()

Argument

Description

pbdom_element_name

The name of a PBDOM_ELEMENT object


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.

Equals

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)

Argument

Description

pbdom_element_name

The name of a PBDOM_ELEMENT object

pbdom_object_ref

A PBDOM_OBJECT to be tested for equality with this PBDOM_ELEMENT object


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.

GetAttribute

Description

The GetAttribute method is overloaded:

  • Syntax 1 returns the PBDOM_ATTRIBUTE object for a PBDOM_ELEMENT object using the name of the PBDOM_ATTRIBUTE.

  • Syntax 2 returns the PBDOM_ATTRIBUTE object for a PBDOM_ELEMENT object with the name provided and within the namespace specified by the prefix and URI provided.

Syntax

For this syntax

See

GetAttribute(string strName)

GetAttribute Syntax 1 

GetAttribute(string strName, string strNamespacePrefix, string strNamespaceUri)

GetAttribute Syntax 2 


GetAttribute Syntax 1

Description

Returns the PBDOM_ATTRIBUTE object for a PBDOM_ELEMENT object.

Syntax

pbdom_element_name.GetAttribute(string strName)

Argument

Description

pbdom_element_name

The name of a PBDOM_ELEMENT object

strName

The name of the PBDOM_ATTRIBUTE to be returned


Return value

PBDOM_ATTRIBUTE. The PBDOM_ATTRIBUTE object matching the name specified in the method parameter. If no such PBDOM_ATTRIBUTE object exists, the GetAttribute method returns a value of null.

Throws

EXCEPTION_INVALID_NAME  -- If the supplied name is a qualified name that contains a namespace prefix.

Examples

The GetAttribute method is invoked for the following XML document:

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

The GetAttribute method is invoked from the following PowerScript statement:

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

The GetAttribute method returns the PBDOM_ATTRIBUTE object My_Attr.

Usage

If the PBDOM_ATTRIBUTE name specified in the method parameter is a qualified name, an exception is thrown. A qualified name appears in the following form: [namespace_prefix]:[local_name].

See also

GetAttribute Syntax 2

GetAttributes

GetAttributeValue

HasAttributes

SetAttribute

SetAttributes

GetAttribute Syntax 2

Description

Returns the PBDOM_ATTRIBUTE object for a PBDOM_ELEMENT object with the name provided and within the namespace specified by the prefix and URI provided.

Syntax

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

Argument

Description

pbdom_element_name

The name of a PBDOM_ELEMENT object

strName

The name of the PBDOM_ATTRIBUTE to be returned

strNamespacePrefix

The prefix of the namespace of the PBDOM_ATTRIBUTE to return

strNamespaceUri

The URI of the namespace of the PBDOM_ATTRIBUTE to return


Return value

PBDOM_ATTRIBUTE. The PBDOM_ATTRIBUTE object matching the name, namespace prefix, and URI specified in the method parameters. If no such PBDOM_ATTRIBUTE object exists, the GetAttribute method returns a value of null.

Throws

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

EXCEPTION_MEMORY_ALLOCATION_FAILURE  -- If there was any memory allocation failure during the running of this method.

See also

GetAttribute Syntax 1

GetAttributes

GetAttributeValue

HasAttributes

SetAttribute

SetAttributes

GetAttributes

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)

Argument

Description

pbdom_element_name

The name of a PBDOM_ELEMENT object

pbdom_attribute_array

An empty and unbounded array to be filled with references to the PBDOM_ATTRIBUTE objects contained in the PBDOM_ELEMENT object


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

GetAttributeValue

Description

The GetAttributeValue method is overloaded:

  • Syntax 1 returns the string value of a PBDOM_ATTRIBUTE object with the specified name.

  • Syntax 2 returns the string value of a PBDOM_ATTRIBUTE object with the specified name, using the prefix and URI of the namespace of the PBDOM_ATTRIBUTE.

  • Syntax 3 returns the string value of a PBDOM_ATTRIBUTE object with the specified name, using the prefix and URI of the namespace of the PBDOM_ATTRIBUTE. Syntax 3 also provides a default string value to return if the attribute does not exist.

  • Syntax 4 returns the string value of a PBDOM_ATTRIBUTE object with the specified name. Syntax 4 also provides a default string value to return if the attribute does not exist.

Syntax

For this syntax

See

GetAttributeValue(string strAttributeName)

GetAttributeValue Syntax 1 

GetAttributeValue(string strAttributeName, string strNamespacePrefix, string strNamespaceUri)

GetAttributeValue Syntax 2 

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

GetAttributeValue Syntax 3 

GetAttributeValue(string strAttributeName, string strDefaultValue)

GetAttributeValue Syntax 4 


GetAttributeValue Syntax 1

Description

Returns the string value of the PBDOM_ATTRIBUTE object (within a PBDOM_ELEMENT object) with the specified name and within no namespace.

Syntax

pbdom_element_name.GetAttributeValue(string strAttributeName)

Argument

Description

pbdom_element_name

The name of a PBDOM_ELEMENT object

strAttributeName

The name of the attribute whose value is to be returned


Return value

String.

The string value of the PBDOM_ATTRIBUTE object specified in strAttributeName. If no such object exists, the GetAttributeValue method returns null.

Usage

If the text value of the PBDOM_ATTRIBUTE object is empty, the GetAttributeValue method returns an empty string.

See also

GetAttribute

GetAttributeValue Syntax 2

GetAttributeValue Syntax 3

GetAttributeValue Syntax 4

HasAttributes

SetAttribute

SetAttributes

GetAttributeValue Syntax 2

Description

Returns the string value of the PBDOM_ATTRIBUTE object (within a PBDOM_ELEMENT object) with the specified name and within the specified namespace.

Syntax

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

Argument

Description

pbdom_element_name

The name of a PBDOM_ELEMENT object

strAttributeName

The name of the attribute whose value is to be returned

strNamespacePrefix

The prefix of the namespace of the PBDOM_ATTRIBUTE whose value is to be returned

strNamespaceUri

The URI of the namespace of the PBDOM_ATTRIBUTE whose value is to be returned


Return value

String.

The string value of the PBDOM_ATTRIBUTE object specified in strAttributeName. If no such object exists, the GetAttributeValue method returns an empty string.

Throws

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

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

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

See also

GetAttribute

GetAttributeValue Syntax 1

GetAttributeValue Syntax 3

GetAttributeValue Syntax 4

HasAttributes

SetAttribute

SetAttributes

GetAttributeValue Syntax 3

Description

Returns the string value of the PBDOM_ATTRIBUTE object (within a PBDOM_ELEMENT object) with the specified name and within the specified namespace. If no such PBDOM_ATTRIBUTE exists, the default value is returned.

Syntax

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

Argument

Description

pbdom_element_name

The name of a PBDOM_ELEMENT object

strAttributeName

The name of the attribute whose value is to be returned

strNamespacePrefix

The prefix of the namespace of the PBDOM_ATTRIBUTE whose value is to be returned

strNamespaceUri

The URI of the namespace of the PBDOM_ATTRIBUTE whose value is to be returned

strDefaultValue

Default string value to return if the attribute does not exist


Return value

String.

The string value of the PBDOM_ATTRIBUTE object specified in strAttributeName. If no such object exists, the GetAttributeValue method returns the string provided in strDefaultValue.

Throws

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

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

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

See also

GetAttribute

GetAttributeValue Syntax 1

GetAttributeValue Syntax 2

GetAttributeValue Syntax 4

HasAttributes

SetAttribute

SetAttributes

GetAttributeValue Syntax 4

Description

Returns the string value of the PBDOM_ATTRIBUTE object (within a PBDOM_ELEMENT object) with the specified name. If no such PBDOM_ATTRIBUTE exists, the default value is returned.

Syntax

pbdom_element_name.GetAttributeValue(string strAttributeName, string strDefaultValue)

Argument

Description

pbdom_element_name

The name of a PBDOM_ELEMENT object

strAttributeName

The name of the attribute whose value is to be returned

strDefaultValue

Default string value to return if the attribute does not exist


Return value

String.

The string value of the PBDOM_ATTRIBUTE object specified in strAttributeName. If no such object exists, the GetAttributeValue method returns the string provided in strDefaultValue.

See also

GetAttribute

GetAttributeValue Syntax 1

GetAttributeValue Syntax 2

GetAttributeValue Syntax 3

HasAttributes

SetAttribute

SetAttributes

GetChildElement

Description

The GetChildElement method is overloaded:

  • Syntax 1 returns the first child PBDOM_ELEMENT object that matches the name indicated by the method parameter.

  • Syntax 2 returns the first child PBDOM_ELEMENT object that matches the name and namespace indicated by the method parameter.

Syntax

For this syntax

See

GetChildElement(string strElementName)

GetChildElement Syntax 1 

GetChildElement(string strElementName, string strNamespacePrefix, string strNamespaceUri)

GetChildElement Syntax 2 


GetChildElement Syntax 1

Description

Returns the first child PBDOM_ELEMENT object, matching the name indicated by the method parameter that is contained in the PBDOM_ELEMENT object from which the method is invoked.

Syntax

pbdom_element_name.GetChildElement(string strElementName)

Argument

Description

pbdom_element_name

The name of a PBDOM_ELEMENT object

strElementName

The local name of the child PBDOM_ELEMENT object to be returned


Return value

PBDOM_ELEMENT. The first child PBDOM_ELEMENT object whose name matches the value of the method parameter. If no PBDOM_ELEMENT object exists for the specified name, the GetChildElement method returns a value of null.

See also

GetChildElement Syntax 2

GetChildElements

HasChildElements

HasChildren

IsRootElement

RemoveChildElement

RemoveChildElements

GetChildElement Syntax 2

Description

Returns the first child PBDOM_ELEMENT object, matching the name and namespace indicated by the method parameter contained in the PBDOM_ELEMENT object from which the method is invoked.

Syntax

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

Argument

Description

pbdom_element_name

The name of a PBDOM_ELEMENT object

strElementName

The local name of the child PBDOM_ELEMENT object to be returned

strNamespacePrefix

The prefix of the namespace of the child PBDOM_ELEMENT object to be returned

strNamespaceUri

The URI of the namespace of the child PBDOM_ELEMENT object to be returned


Return value

PBDOM_ELEMENT. The first child PBDOM_ELEMENT object whose name and namespace information match the values of the method parameters. If no PBDOM_ELEMENT object exists for the specified name and namespace information, the GetChildElement method returns a value of null.

Throws

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

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

See also

GetChildElement Syntax 1

GetChildElements

HasChildElements

HasChildren

IsRootElement

RemoveChildElement

RemoveChildElements

GetChildElements

Description

The GetChildElements method is overloaded:

  • Syntax 1 retrieves a list of all child PBDOM_ELEMENT objects nested one level deep within a PBDOM_ELEMENT object. The list is stored in the array specified when the method is invoked.

  • Syntax 2 retrieves a list of all child PBDOM_ELEMENT objects nested one level deep within a PBDOM_ELEMENT object specified by the name provided and belonging to no namespace. The list is stored in the array specified when the method is invoked.

  • Syntax 3 retrieves a list of all child PBDOM_ELEMENT objects nested one level deep within a PBDOM_ELEMENT object specified by the local name and namespace provided.

Syntax

For this syntax

See

GetChildElements(ref pbdom_element pbdom_element_array[])

GetChildElements Syntax 1 

GetChildElements(string strElementName, ref pbdom_element pbdom_element_array[])

GetChildElements Syntax 2 

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

GetChildElements Syntax 3 


GetChildElements Syntax 1

Description

Retrieves a list of all child PBDOM_ELEMENT objects nested one level deep within a PBDOM_ELEMENT object. The list is stored in the array specified when the method is invoked.

Syntax

pbdom_element_name.GetChildElements(ref pbdom_element pbdom_element_array)

Argument

Description

pbdom_element_name

The name of a PBDOM_ELEMENT object

pbdom_element_array

The array that stores the child PBDOM_ELEMENT objects


Return value

Boolean.

Returns true if child PBDOM_ELEMENT objects have been collected, and false otherwise.

Usage

If the PBDOM_ELEMENT object has no nested elements, GetChildElements returns an empty array.

See also

GetChildElement

GetChildElements Syntax 2

GetChildElements Syntax 3

HasChildElements

HasChildren

IsRootElement

RemoveChildElement

RemoveChildElements

GetChildElements Syntax 2

Description

Retrieves a list of all child PBDOM_ELEMENT objects nested one level deep within a PBDOM_ELEMENT object specified by the name provided and belonging to no namespace. The list is stored in the array specified when the method is invoked.

Syntax

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

Argument

Description

pbdom_element_name

The name of a PBDOM_ELEMENT object

strElementName

The name of the PBDOM_ELEMENT object for which to find children

pbdom_element_array

The array that stores the child PBDOM_ELEMENT objects


Return value

Boolean.

Returns true if child PBDOM_ELEMENT objects have been collected, and false otherwise.

Usage

If the PBDOM_ELEMENT object has no nested elements, GetChildElements returns an empty array.

See also

GetChildElement

GetChildElements Syntax 1

GetChildElements Syntax 3

HasChildElements

HasChildren

IsRootElement

RemoveChildElement

RemoveChildElements

GetChildElements Syntax 3

Description

Retrieves a list of all child PBDOM_ELEMENT objects nested one level deep within a PBDOM_ELEMENT object specified by the local name and namespace provided.

Syntax

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

Argument

Description

pbdom_element_name

The name of a PBDOM_ELEMENT object

strElementName

The name of a PBDOM_ELEMENT object for which to find children

strNamespacePrefix

The prefix of the namespace of the child PBDOM_ELEMENT objects to match

strNamespaceUri

The URI of the namespace of the child PBDOM_ELEMENT objects to match

pbdom_element_array[]

The array that stores the child PBDOM_ELEMENT objects


Return value

Boolean.

Returns true if child PBDOM_ELEMENT objects have been collected, and false otherwise.

Throws

EXCEPTION_INVALID_ARGUMENT -- If any of the parameters is invalid.

EXCEPTION_INVALID_NAME  -- If the input element name or namespace prefix or namespace URI is invalid. The only exception is if the input element name is an empty string.

Usage

If the PBDOM_ELEMENT object has no nested elements, GetChildElements returns an empty array.

If the value of strElementName is an empty string, then all child elements match.

See also

GetChildElement

GetChildElements Syntax 1

GetChildElements Syntax 2

HasChildElements

HasChildren

IsRootElement

RemoveChildElement

RemoveChildElements

GetContent

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[ ])

Argument

Description

pbdom_element_name

The name of a PBDOM_ELEMENT object

pbdom_object_array

The name of an array of PBDOM_OBJECT objects that receive references to the PBDOM_OBJECT objects contained within the PBDOM_ELEMENT object


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:

Array element

Value

1

<Element_1>

2

<Element_2>

3

<Element_3>


See also

AddContent Syntax 1

AddContent Syntax 2

InsertContent

RemoveContent

SetContent

GetName

Description

Retrieves the local name of a PBDOM_ELEMENT object.

Syntax

pbdom_element_name.GetName()

Argument

Description

pbdom_element_name

The name of a PBDOM_ELEMENT object


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

GetNamespacePrefix

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

Argument

Description

pbdom_element_name

The name of a PBDOM_ELEMENT object


Return value

String.

The namespace prefix for the PBDOM_ELEMENT object.

See also

AddNamespaceDeclaration

GetNamespaceUri

GetQualifiedName

RemoveNamespaceDeclaration

SetNamespace

GetNamespaceUri

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

Argument

Description

pbdom_element_name

The name of a PBDOM_ELEMENT object


Return value

String.

The namespace URI for the PBDOM_ELEMENT object.

See also

AddNamespaceDeclaration

GetNamespacePrefix

GetQualifiedName

RemoveNamespaceDeclaration

SetNamespace

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 object


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.

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 your PBDOM_OBJECT object


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.

GetOwnerDocumentObject

Description

Returns the PBDOM_DOCUMENT object that owns the PBDOM_ELEMENT object.

Syntax

pbdom_element_name.GetOwnerDocumentObject()

Argument

Description

pbdom_element_name

The name of a PBDOM_ELEMENT object


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

GetParentObject

Description

Returns the parent object for the PBDOM_ELEMENT object.

Syntax

pbdom_element_name.GetParentObject()

Argument

Description

pbdom_element_name

The name of a PBDOM_ELEMENT object


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

GetQualifiedName

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

Argument

Description

pbdom_element_name

The name of a PBDOM_ELEMENT object


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

GetText

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

Argument

Description

pbdom_element_name

The name of a PBDOM_ELEMENT object


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

GetTextNormalize

Description

Returns the normalized text data contained in a PBDOM_ELEMENT object.

Syntax

pbdom_element_name.GetTextNormalize()

Argument

Description

pbdom_element_name

The name of a PBDOM_ELEMENT object


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

GetTextTrim

Description

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

Syntax

pbdom_element_name.GetTextTrim()

Argument

Description

pbdom_element_name

The name of a PBDOM_ELEMENT object


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

HasAttributes

Description

Indicates whether a PBDOM_ELEMENT object has one or more attributes.

Syntax

pbdom_element_name.HasAttributes()

Argument

Description

pbdom_element_name

The name of a PBDOM_ELEMENT object


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

HasChildElements

Description

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

Syntax

pbdom_element_name.HasChildElements()

Argument

Description

pbdom_element_name

The name of a PBDOM_ELEMENT object


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

HasChildren

Description

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

Syntax

pbdom_element_name.HasChildren()

Argument

Description

pbdom_element_name

The name of a PBDOM_ELEMENT object


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

InsertContent

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)

Argument

Description

pbdom_element_name

The name of a PBDOM_ELEMENT object

pbdom_object_new

The PBDOM_OBJECT to insert

pbdom_object_ref

A positional reference PBDOM_OBJECT in front of which the new PBDOM_OBJECT is to be inserted


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

IsAncestorObjectOf

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)

Argument

Description

pbdom_element_name

The name of a PBDOM_ELEMENT object

pbdom_object_ref

The PBDOM_OBJECT to be tested for equality with this PBDOM_ELEMENT object


Return value

Boolean.

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

IsRootElement

Description

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

Syntax

pbdom_element_name.IsRootElement()

Argument

Description

pbdom_element_name

The name of a PBDOM_ELEMENT object


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

RemoveAttribute

Description

The RemoveAttribute method is overloaded:

  • Syntax 1 removes a PBDOM_ATTRIBUTE from its owner PBDOM_ELEMENT object using a reference to the PBDOM_ATTRIBUTE.

  • Syntax 2 removes a PBDOM_ATTRIBUTE from its owner PBDOM_ELEMENT object using the name of the PBDOM_ATTRIBUTE.

  • Syntax 3 removes a PBDOM_ATTRIBUTE from its owner PBDOM_ELEMENT object using the name and namespace of the PBDOM_ATTRIBUTE.

Syntax

For this syntax

See

RemoveAttribute(pbdom_attribute pbdom_attribute_ref)

RemoveAttribute Syntax 1 

RemoveAttribute(string strAttributeName)

RemoveAttribute Syntax 2 

RemoveAttribute(string strAttributeName, string strNamespacePrefix, string strNamespaceUri)

RemoveAttribute Syntax 3 


RemoveAttribute Syntax 1

Description

Removes a PBDOM_ATTRIBUTE from its owner PBDOM_ELEMENT object.

Syntax

pbdom_element_name.RemoveAttribute(pbdom_attribute pbdom_attribute_ref)

Argument

Description

pbdom_element_name

The name of a PBDOM_ELEMENT object

pbdom_attribute_ref

The PBDOM_ATTRIBUTE object to remove from this PBDOM_ELEMENT object


Return value

Boolean.

Returns true if the specified PBDOM_ATTRIBUTE was removed, and false otherwise.

RemoveAttribute Syntax 2

Description

Removes a PBDOM_ATTRIBUTE specified by the name provided that is not contained in a namespace. If no such PBDOM_ATTRIBUTE exists, RemoveAttribute does nothing.

Syntax

pbdom_element_name.RemoveAttribute(string strAttributeName)

Argument

Description

pbdom_element_name

The name of a PBDOM_ELEMENT object

strAttributeName

The name of the PBDOM_ATTRIBUTE object to remove


Return value

Boolean.

Returns true if the specified PBDOM_ATTRIBUTE was removed, and false otherwise.

RemoveAttribute Syntax 3

Description

Removes a PBDOM_ATTRIBUTE specified by the name and namespace provided. If no such PBDOM_ATTRIBUTE exists, RemoveAttribute does nothing.

Syntax

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

Argument

Description

pbdom_element_name

The name of a PBDOM_ELEMENT object

strAttributeName

The name of the PBDOM_ATTRIBUTE object to remove

strNamespacePrefix

Prefix of the namespace of the PBDOM_ATTRIBUTE to remove

strNamespaceUri

URI of the namespace of the PBDOM_ATTRIBUTE to remove


Return value

Boolean.

Returns true if the specified PBDOM_ATTRIBUTE was removed, and false otherwise.

Throws

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

EXCEPTION_INVALID_STRING  -- If the input Attribute Name is invalid (for example, contains a colon), or if the namespace prefix or URI is invalid.

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

RemoveChildElement

Description

The RemoveChildElement method is overloaded:

  • Syntax 1 removes the first child PBDOM_ELEMENT object (one level deep) that has the local name provided and belongs to no namespace.

  • Syntax 2 removes the first child PBDOM_ELEMENT object (one level deep) that has the local name provided and belongs to the specified namespace.

Syntax

For this syntax

See

RemoveChildElement(string strElementName)

RemoveChildElement Syntax 1 

RemoveChildElement(string strElementName, string strNamespacePrefix, string strNamespaceUri)

RemoveChildElement Syntax 2 


RemoveChildElement Syntax 1

Description

Removes the first child PBDOM_ELEMENT object (one level deep) that has the local name provided and belongs to no namespace.

Syntax

pbdom_element_name.RemoveChildElement(string strElementName)

Argument

Description

pbdom_element_name

The name of a PBDOM_ELEMENT object

strElementName

The name of the child PBDOM_ELEMENT object to remove


Return value

Boolean.

Returns true if the specified PBDOM_ELEMENT object was removed, and false otherwise.

Throws

EXCEPTION_INVALID_ARGUMENT  -- If the input parameter is invalid, for example, null.

EXCEPTION_INVALID_STRING -- If the input element name is invalid.

See also

GetChildElement

GetChildElements

HasChildElements

HasChildren

IsRootElement

RemoveChildElement Syntax 2

RemoveChildElements

RemoveChildElement Syntax 2

Description

Removes the first child PBDOM_ELEMENT object (one level deep) that has the local name provided and belongs to the specified namespace.

Syntax

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

Argument

Description

pbdom_element_name

The name of a PBDOM_ELEMENT object

strElementName

The name of the PBDOM_ELEMENT object to remove

strNamespacePrefix

Prefix of the namespace of the PBDOM_ELEMENT object to remove

strNamespaceUri

URI of the namespace of the PBDOM_ATTRIBUTE to remove


Return value

Boolean.

Returns true if the specified PBDOM_ELEMENT object was removed and false otherwise.

Throws

EXCEPTION_INVALID_ARGUMENT  -- If the input parameter is invalid, for example, null.

EXCEPTION_INVALID_STRING  -- If the input element name is invalid or the input namespace prefix or URI is invalid.

See also

GetChildElement

GetChildElements

HasChildElements

HasChildren

IsRootElement

RemoveChildElement Syntax 1

RemoveChildElements

RemoveChildElements

Description

The RemoveChildElements method is overloaded:

  • Syntax 1 method removes from the current PBDOM_ELEMENT object all child PBDOM_ELEMENT objects. It uses no parameters.

  • Syntax 2 method removes from the current PBDOM_ELEMENT object all child PBDOM_ELEMENT objects that have the specified local name and belong to no namespace.

  • Syntax 3 removes from the current PBDOM_ELEMENT object all child PBDOM_ELEMENT objects (one level deep) that have the specified local name and belong to the specified namespace.

Syntax

For this syntax

See

RemoveChildElements()

RemoveChildElements Syntax 1 

RemoveChildElements(string strElementName)

RemoveChildElements Syntax 2 

RemoveChildElements(string strElementName, string strNamespacePrefix, string strNamespaceUri)

RemoveChildElements Syntax 3 


RemoveChildElements Syntax 1

Description

Removes from the current PBDOM_ELEMENT object all child PBDOM_ELEMENT objects. It uses no parameters.

Syntax

pbdom_element_name.RemoveChildElements()

Argument

Description

pbdom_element_name

The name of a PBDOM_ELEMENT object


Return value

Boolean.

Returns true if any child PBDOM_ELEMENT object was removed and false otherwise.

See also

GetChildElement

GetChildElements

HasChildElements

HasChildren

IsRootElement

RemoveChildElement

RemoveChildElements Syntax 2

RemoveChildElements Syntax 3

RemoveChildElements Syntax 2

Description

Removes from the current PBDOM_ELEMENT object all child PBDOM_ELEMENT objects that have the specified local name and belong to no namespace.

Syntax

pbdom_element_name.RemoveChildElements(string strElementName)

Argument

Description

pbdom_element_name

The name of a PBDOM_ELEMENT object

strElementName

The name of the child PBDOM_ELEMENT objects to remove


Return value

Boolean.

Returns true if any child PBDOM_ELEMENT object was removed, and false otherwise.

See also

GetChildElement

GetChildElements

HasChildElements

HasChildren

IsRootElement

RemoveChildElement

RemoveChildElements Syntax 1

RemoveChildElements Syntax 3

RemoveChildElements Syntax 3

Description

Removes from the current PBDOM_ELEMENT object all child PBDOM_ELEMENT objects (one level deep) that have the specified local name and belong to the specified namespace.

Syntax

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

Argument

Description

pbdom_element_name

The name of a PBDOM_ELEMENT object

strElementName

The name of the child PBDOM_ELEMENT objects to remove

strNamespacePrefix

Prefix of the namespace of the child PBDOM_ELEMENT objects to remove

strNamespaceUri

URI of the namespace of the child PBDOM_ATTRIBUTE objects to remove


Return value

Boolean.

Returns true if any child PBDOM_ELEMENT object was removed and false otherwise.

Throws

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

EXCEPTION_INVALID_NAME  -- If the input element name or namespace prefix or URI is invalid. The only exception is if the input element name is an empty string, in which case all element names match.

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

See also

GetChildElement

GetChildElements

HasChildElements

HasChildren

IsRootElement

RemoveChildElement

RemoveChildElements Syntax 1

RemoveChildElements Syntax 2

RemoveContent

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)

Argument

Description

pbdom_element_name

The name of a PBDOM_ELEMENT object

pbdom_object_ref

The PBDOM_OBJECT to remove


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

RemoveNamespaceDeclaration

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)

Argument

Description

pbdom_element_name

The name of a PBDOM_ELEMENT object

strNamespacePrefix

Prefix of the namespace declaration to remove

strNamespaceUri

URI of the namespace declaration to remove


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

SetAttribute

Description

The SetAttribute method is overloaded:

  • Syntax 1 adds a predefined PBDOM_ATTRIBUTE object to a PBDOM_ELEMENT object.

  • Syntax 2 adds a PBDOM_ATTRIBUTE object and its value to a PBDOM_ELEMENT object using strings for the name and value of the PBDOM_ATTRIBUTE.

  • Syntax 3 adds an attribute/value pair to a PBDOM_ELEMENT object using strings for the name and value of the PBDOM_ATTRIBUTE, and the prefix and URI of the namespace to which the PBDOM_ATTRIBUTE belongs.

Syntax

For this syntax

See

SetAttribute(pbdom_attribute pbdom_attribute_ref)

SetAttribute Syntax 1 

SetAttribute(string strName, string strValue)

SetAttribute Syntax 2 

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

SetAttribute Syntax 3 


SetAttribute Syntax 1

Description

Adds a predefined PBDOM_ATTRIBUTE object to a PBDOM_ELEMENT object. Any existing attribute with the same name and namespace URI is overwritten.

Syntax

pbdom_element_name.SetAttribute(pbdom_attribute pbdom_attribute_ref)

Argument

Description

pbdom_element_name

The name of a PBDOM_ELEMENT object

pbdom_attribute_ref

The PBDOM_ATTRIBUTE object to be set for this PBDOM_ELEMENT object


Return value

PBDOM_ELEMENT. The PBDOM_ELEMENT object modified to contain the specified PBDOM_ATTRIBUTE.

Throws

EXCEPTION_INVALID_ARGUMENT  -- The input PBDOM_ATTRIBUTE is invalid. This can happen if it has not been initialized properly or it is a null object reference.

EXCEPTION_USE_OF_UNNAMED_PBDOM_OBJECT  -- The input PBDOM_ATTRIBUTE has not been given a user-defined name.

EXCEPTION_PBDOM_OBJECT_ALREADY_HAS_OWNER  -- The input PBDOM_ATTRIBUTE already has an owner element.

Examples

  1. The SetAttribute method is invoked for the following element:

    <image></image>

    The SetAttribute method is invoked from the following PowerScript code, where elem_image represents the image element from the preceding XML:

    attr_src.SetName("src")
    attr_src.SetValue("logo.gif")
    elem_image.SetAttribute(attr_src)

    The following XML results:

    <image src="logo.gif"></image>
  2. The following example demonstrates the impact of setting a PBDOM_ATTRIBUTE for a PBDOM_ELEMENT object where the PBDOM_ELEMENT object already contains an attribute of the same name and namespace URI as the input PBDOM_ATTRIBUTE.

The example creates a PBDOM_DOCUMENT based on the following document:

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

Then it creates a PBDOM_ATTRIBUTE object and sets its name to a and its prefix and URI to pre2 and http://www.pre.com. The bVerifyNamespace argument is set to false because this PBDOM_ATTRIBUTE has not been assigned an owner PBDOM_ELEMENT object yet, so that the verification for a predeclared namespace would fail. The text value is set to 456.

The child1 element already contains an attribute named a that belongs to the namespace http://www.pre.com, as indicated by the prefix pre1. The new PBDOM_ATTRIBUTE uses the prefix pre2, but it represents the same namespace URI, so setting the new PBDOM_ATTRIBUTE to child1 successfully replaces the existing pre1:a with the new PBDOM_ATTRIBUTE pre2:a.

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

When saved and converted to an XML document, the document looks like the following:

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

Usage

This method allows the caller to add a predefined PBDOM_ATTRIBUTE object to a PBDOM_ELEMENT object. If this PBDOM_ELEMENT object already contains an existing attribute with the same name and namespace URI as the input PBDOM_ATTRIBUTE, the existing attribute is replaced by the input PBDOM_ATTRIBUTE.

If a PBDOM_ATTRIBUTE has been created to represent the original attribute, it is still valid after the call, but the attribute that 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 Syntax 2

SetAttribute Syntax 3

SetAttributes

SetAttribute Syntax 2

Description

Adds a PBDOM_ATTRIBUTE object and its value to a PBDOM_ELEMENT object. Any existing attribute with the same name and namespace URI is overwritten.

Syntax

pbdom_element_name.SetAttribute(string strName, string strValue)

Argument

Description

pbdom_element_name

The name of a PBDOM_ELEMENT object

strName

The name of the PBDOM_ATTRIBUTE to be added

strValue

The value of the PBDOM_ATTRIBUTE to be added


Return value

PBDOM_ELEMENT. The PBDOM_ELEMENT object modified to contain the specified PBDOM_ATTRIBUTE with the specified value.

Throws

EXCEPTION_INVALID_ARGUMENT  -- One or both of the input strings are invalid. This can happen if either or both strings have not been initialized properly or are null.

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

EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE  -- This PBDOM_ELEMENT object's internal implementation is null. The occurrence of this exception is rare but can take place if severe memory corruption occurs.

EXCEPTION_INVALID_NAME -- An invalid name for the attribute is supplied.

EXCEPTION_INVALID_STRING  -- An invalid string for the attribute value is supplied.

Examples

  1. The SetAttribute method is invoked for the following XML element:

    <code0789725045</code

    The SetAttribute method is invoked from the following PowerScript statement, where elem_code represents the code element:

    elem_code.SetAttribute("type", "ISBN")

    The following XML element results:

    <code type="ISBN">0789725045</code>
  2. The following example demonstrates the effect of setting an attribute for a PBDOM_ELEMENT object when the PBDOM_ELEMENT object already contains an attribute of the same name. The example creates a PBDOM_DOCUMENT based on the following document:

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

    The child1 element already contains an attribute named b with value 456. Calling the SetAttribute method with name b and value 789 creates a new attribute for child1 that replaces the original b attribute.

    PBDOM_BUILDER     pbdom_buildr
    PBDOM_DOCUMENT   pbdom_doc
    string strXML = "<root xmlns:pre1=~"http://www.pre.com~" ><child1 pre1:a=~"123~" b=~"456~"/></root>"
    
    try
      pbdom_buildr = Create PBDOM_BUILDER
      pbdom_doc = pbdom_buildr.BuildFromString (strXML)
      pbdom_doc.GetRootElement(). &
        GetChildElement("child1").SetAttribute("b", "789")
    catch (PBDOM_EXCEPTION except)
      MessageBox ("PBDOM_EXCEPTION", except.GetMessage())
    end try

    After the PBDOM_DOCUMENT object is saved and converted to XML, the XML document looks like the following:

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

Usage

This method allows the caller to add an attribute/value pair to a PBDOM_ELEMENT object. If the PBDOM_ELEMENT object already contains an existing attribute that has the same name as the input name and that belongs to no namespace, the original attribute is removed from this PBDOM_ELEMENT object and a new one (corresponding to the specified attribute name and value) is created and set in its place.

If a PBDOM_ATTRIBUTE has been created to represent the original attribute, it is still valid, but the attribute that 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 Syntax 1

SetAttribute Syntax 3

SetAttributes

SetAttribute Syntax 3

Description

Adds an attribute/value pair to a PBDOM_ELEMENT object. The attribute namespace is specified, and any existing attribute of the same name and namespace URI is removed.

Syntax

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

Argument

Description

pbdom_element_name

The name of a PBDOM_ELEMENT object

strName

The name of the PBDOM_ATTRIBUTE to be added

strValue

The value of the PBDOM_ATTRIBUTE to be added

strNamespacePrefix

The prefix of the namespace to which the PBDOM_ATTRIBUTE belongs

strNamespaceUri

The URI of the namespace to which the PBDOM_ATTRIBUTE belongs

bVerifyNamespace

Specifies whether or not the method should verify the existence of an in-scope namespace declaration for the given prefix and URI


Return value

Long.

Returns 0 if no namespace verification error occurs and -1 if no in-scope namespace declaration exists for the given prefix and URI settings.

Throws

EXCEPTION_INVALID_ARGUMENT  -- If any of the arguments is invalid. This can happen if any of the input strings has been set to null using the PowerScript SetNull function.

EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE  -- This PBDOM_ELEMENT object's internal implementation is null. The occurrence of this exception is rare but can take place if severe memory corruption occurs.

EXCEPTION_INVALID_NAME  -- The input namespace prefix or the URI, or their combination, is not valid. This will happen if:

  • The namespace prefix is an empty string and the URI is not an empty string. If both are empty strings, the NONAMESPACE namespace is being specified and this prefix/URI combination is correct.

  • The namespace prefix is xmlns and the URI is not http://www.w3.org/2000/xmlns/. This namespace prefix/URI pair is unique and exclusive and cannot be used separately. The use of this pair signifies a namespace declaration.

  • The namespace prefix string is invalid. That is, it does not conform to the W3C "Namespaces in XML" specifications for the name of a prefix.

  • The namespace URI string is invalid. That is, it does not conform to the W3C specifications for a URI string.

EXCEPTION_MEMORY_ALLOCATION_FAILURE  -- If there has been any memory allocation failure during this method call.

Examples

  1. The SetAttribute method is invoked for the following XML element:

    <code>0789725045</code>

    The SetAttribute method is invoked from the following PowerScript statement, where elem_code represents the code element:

    elem_code.SetAttribute("type", "ISBN", "ns", & "http://www.books.com/codes", false)

    The following XML element results:

    <code ns:type="ISBN">0789725045</code>
  2. The following example demonstrates the effect of setting an attribute with a particular name and namespace URI for an element that already contains an existing attribute with the same name and namespace URI. It creates a PBDOM_DOCUMENT based on the following XML:

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

    The child1 element already contains an attribute named a that belongs to the namespace http://www.pre.com, as indicated by the pre1 prefix. The call to SetAttribute attempts to set an attribute for child1 with the same name, a, but with the namespace prefix pre2.

    The last parameter, bVerifyNamespace, is set to true. This tells the SetAttribute method to check first to see if an in-scope namespace declaration for pre2 and http://www.pre.com exists. An in-scope declaration for this namespace prefix/URI pair does exist, and so the verification succeeds.

    The original pre1:a attribute is removed from the child1 element and a new attribute pre2:a, belonging to the same namespace and with the value 456, is created and set in its place. The new attribute replaces the original attribute, instead of being set as an additional attribute, because both attributes have the same URI.

    PBDOM_BUILDER     pbdom_buildr
    PBDOM_DOCUMENT   pbdom_doc
    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)
    
    pbdom_doc.GetRootElement().GetChildElement("child1").SetAttribute("a", "456", "pre2", "http://www.pre.com", true)
      
    catch (PBDOM_EXCEPTION pbdom_except)
      MessageBox ("PBDOM_EXCEPTION", pbdom_except.GetMessage())
    end try
    

Usage

This method allows the caller to add an attribute/value pair to a PBDOM_ELEMENT object.

The parameter bVerifyNamespace, when set to true, instructs the method to perform a thorough search up the DOM node tree, starting at the current PBDOM_ELEMENT object, to check for an in-scope namespace declaration for the given prefix and URI. If a namespace declaration is not found, no attribute is created. If a namespace declaration is found, an attribute is created.

If the bVerifyNamespace parameter is set to false, no verification search is performed, and the method always returns 0.

If the PBDOM_ELEMENT object already contains an existing attribute that has the same name as the input name and the same namespace URI as the input namespace URI, the original attribute is replaced with a new one with the same name and URI.

If a PBDOM_ATTRIBUTE has been created to represent the original attribute, it is still valid, but the attribute that 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 Syntax 1

SetAttribute Syntax 2

SetAttributes

SetAttributes

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[])

Argument

Description

pbdom_element_name

The name of a PBDOM_ELEMENT object

pbdom_attribute_array

An array of PBDOM_ATTRIBUTE objects


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

SetContent

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[])

Argument

Description

pbdom_element_name

The name of a PBDOM_ELEMENT object

pbdom_object_array

An array of PBDOM_OBJECTS to form the contents the PBDOM_ELEMENT object


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:

  • PBDOM_ELEMENT

  • PBDOM_CDATA

  • PBDOM_COMMENT

  • PBDOM_ENTITYREFERENCE

  • PBDOM_PROCESSINGINSTRUCTION

  • PBDOM_TEXT

See also

AddContent Syntax 1

AddContent Syntax 2

GetContent

InsertContent

RemoveContent

SetDocument

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)

Argument

Description

pbdom_element_name

The name of a PBDOM_ELEMENT object

pbdom_document_ref

The PBDOM_DOCUMENT to be set as the owner document and parent of this PBDOM_ELEMENT object


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.

SetName

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)

Argument

Description

pbdom_element_name

The name of a PBDOM_ELEMENT object

strName

The new local name for the PBDOM_ELEMENT object


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

SetNamespace

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)

Argument

Description

pbdom_element_name

The name of a PBDOM_ELEMENT object

strNamespacePrefix

Prefix of the namespace to be set for the PBDOM_ELEMENT object

strNamespaceUri

URI of the namespace to be set for the PBDOM_ELEMENT object

bVerifyNamespace

A boolean value indicating whether verification should be performed to ensure that the provided namespace prefix and URI have been declared either within this PBDOM_ELEMENT object or in an ancestor PBDOM_ELEMENT object


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

SetParentObject

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)

Argument

Description

pbdom_element_name

The name of a PBDOM_ELEMENT object

pbdom_object_ref

The PBDOM_OBJECT to be set as the parent of this PBDOM_ELEMENT object


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

SetText

Description

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

Syntax

pbdom_element_name.SetText(string strText)

Argument

Description

pbdom_element_name

The name of a PBDOM_ELEMENT object

strText

String to be set as the content of the PBDOM_ELEMENT object


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