DeleteSubtree (XmlDoc/XmlNode subroutine)

Delete selected subtree (XmlDoc and XmlNode classes)

DeleteSubtree 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 node that is the head of the nodelist is the "top" node of the subtree to be deleted. Any other nodes in the nodelist are ignored. This is an optional argument, and 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 the deleted node or any of its descendants 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 xpath argument expression 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')

  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>

• As discussed in the XmlDoc API section on updating, the items deleted by DeleteSubtree are not available for re-use by later Add, Insert, etc. methods, so DeleteSubtree does not affect the restriction of 16M items in an XmlDoc.

Example

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

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

Request-cancellation errors

This list is not exhaustive: it does not include all the errors that are request cancelling.

• The xpath value 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".

XmlDoc class XmlNode class XmlNodelist class	List of XmlDoc methods List of XmlNode methods List of XmlNodelist methods List of XmlDoc API methods	XmlDoc methods syntax XmlNode methods syntax XmlNodelist methods syntax
Notation conventions for methods