DeleteSubtree (XmlDoc/XmlNode subroutine)

Delete selected subtree (XmlDoc and XmlNode classes)

DeleteSubtree is a member of the XmlDoc and XmlNode classes.

This subroutine deletes a subtree (a node and all of its attributes and all descendants of the node and their attributes) from an XmlDoc.

Syntax

nr:DeleteSubtree[( [xpath])] Throws XPathError

Syntax terms

nr

An XmlDoc or XmlNode, used as the context node for the XPath expression. If an XmlDoc, the Root node is the context node.

XPath

A Unicode string that is an XPath expression that results in a nodelist. The head of the nodelist is the "top" node of the subtree to delete. An optional argument, its default is a period (.), that is, the node referenced by the method object (nr). Prior to Sirius Mods version 7.6, this is an EBCDIC string.

Usage notes

• Any pointers (as XmlNodes or in XmlNodelists) to any of the deleted nodes will subsequently evaluate to Null.
• DeleteSubtree may not be used if the preceding and following siblings of the top of the subtree are both Text nodes, unless the AdjacentText property setting is Combine.
• If the result of the argument XPath expression (XPath) is empty, DeleteSubtree returns without deleting any nodes.
• If the top node in the deleted subtree was originally added to the document by an AddAttribute method with a URI argument which created a namespace declaration, DeleteSubtree applied to that node does not remove the namespace declaration. For example:

      %d = New
      %n = %d:AddElement('x')
      Print 'Before AddAttribute/Delete:' And %d:Serial(, 'EBCDIC')
      %n = %n:AddAttribute('p:a', 'v', 'ftp:a')
      %n:DeleteSubtree
      Print 'After  AddAttribute/Delete:' And %d:Serial(, 'EBCDIC')
  

  This results in:

      Before AddAttribute/Delete: <x/>
      After  AddAttribute/Delete: <x xmlns:p="ftp:a"/>
  

• In the following circumstances, DeleteSubtree does not completely "undo" a preceding AddSubtree (or InsertSubtreeBefore) method:
  1. The top node in the deleted subtree is originally added to the document by an AddAttribute method and has a name prefix.
  2. This attribute node is copied (by AddSubtree or InsertSubtreeBefore) to a target where the attribute prefix is not in scope.
  3. The attribute node is removed by DeleteSubtree, but the namespace declaration for the prefix remains.

  For example:

      %d = New
      %n = %d:AddElement('x')
      %n2 = %n:AddElement('x1')
      %n = %n:AddElement('x2')
      %n2 = %n2:AddAttribute('p:a', 'v', 'ftp:a')
      Print 'Before AddSubtree/Delete:'
      Print %d:Serial(, 'EBCDIC')
      %n2 = %n:AddSubtree(%n2)
      %n2:DeleteSubtree
      Print 'After  AddSubtree/Delete:'
      Print %d:Serial(, 'EBCDIC')
  

  This results in:

      Before AddSubtree/Delete:
      <x><x1 xmlns:p="ftp:a" p:a="v"/><x2/></x>
      After  AddSubtree/Delete:
      <x><x1 xmlns:p="ftp:a" p:a="v"/><x2 xmlns:p="ftp:a"/></x>
  

Example

The method in the following example deletes the first employee child of the top-level Element of the XmlDoc:

    %doc:DeleteSubtree('/*/employee')

Request-Cancellation Errors

• XPath is invalid.
• Head of result of XPath is the Root node.
• Head of result of XPath is a node whose left and right siblings are Text nodes, and the AdjacentText property setting is Disallow.
• Element or Attribute within subtree has a prefix.
• Insufficient free space exists in CCATEMP.

See Also

• For more information about using XPath expressions, see XPath.