DeleteSubtree (XmlDoc/XmlNode subroutine)
DeleteSubtree deletes a subtree (a node and all of its attributes and all descendants of the node and their attributes) from an XmlDoc.
nr:DeleteSubtree[( [xpath])] Throws XPathError
|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.
- 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
- 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.
%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')
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:
- The top node in the deleted subtree is originally added to the document by an AddAttribute method and has a name prefix.
- This attribute node is copied, by AddSubtree or InsertSubtreeBefore, to a target where the attribute prefix is not in scope.
- The attribute node is removed by DeleteSubtree, but the namespace declaration for the prefix remains.
%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.
The following example deletes the first
employee child of the top-level Element of the XmlDoc:
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
- Element or Attribute within subtree has a prefix.
- Insufficient free space exists in CCATEMP.
- For more information about using XPath expressions, see "XPath".