View source for DeleteSubtree (XmlDoc/XmlNode subroutine)

{{Template:XmlDoc/XmlNode:DeleteSubtree subtitle}}
<var>DeleteSubtree</var> deletes a subtree (a node and all of its attributes and all descendants of the node and their attributes) from an <var>XmlDoc</var>.

==Syntax==
{{Template:XmlDoc/XmlNode:DeleteSubtree syntax}}
===Syntax terms===
<table class="syntaxTable">
<tr><th>nr</th>
<td>An <var>XmlDoc</var> or <var>XmlNode</var>, used as the context node for the <var class="term">XPath</var> expression. If an <var>XmlDoc</var>, the <var>Root</var> node is the context node.</td></tr>
<tr><th>xpath</th>
<td>A <var>Unicode</var> string that is an [[XPath#XPath_syntax|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 (<var class="term">nr</var>).
<p>Prior to <var class="product">[[Sirius Mods|"Sirius Mods"]]</var> Version 7.6, this is an EBCDIC string.</p></td></tr>
</table>

==Usage notes==
<ul>
<li>Any pointers (as <var>XmlNode</var>s or in <var>XmlNodelist</var>s) to any of the deleted nodes will subsequently evaluate to <var>Null</var>.
<li><var>DeleteSubtree</var> may not be used if the preceding and following siblings of the top of the subtree are both <var>Text</var> nodes, unless the <var>[[AdjacentText (XmlDoc property)|AdjacentText]]</var> property setting is <code>Combine</code>.
<li>If the result of the argument <var class="term">XPath</var>  expression is empty, <var>DeleteSubtree</var> returns without deleting any nodes.
<li>If the top node in the deleted subtree was originally added to the document by an <var>[[AddAttribute_(XmlNode_function)|AddAttribute]]</var> method with a <var class="term">URI</var> argument which created a namespace declaration, <var>DeleteSubtree</var> applied to that node does not remove the namespace declaration.
For example:
<p class="code">%d = new
%n = %d:[[AddElement_(XmlDoc/XmlNode_function)|addElement]]('x')
print 'Before AddAttribute/Delete:' And %d:Serial(, 'EBCDIC')
%n = %n:[[AddAttribute_(XmlNode_function)|AddAttribute]]('p:a', 'v', 'ftp:a')
%n:deleteSubtree
print 'After  AddAttribute/Delete:' And %d:Serial(, 'EBCDIC')
</p>
Results in:
<p class="output">Before AddAttribute/Delete: <x/>
After  AddAttribute/Delete: <x xmlns:p="ftp:a"/>
</p>
<li>In the following circumstances, <var>DeleteSubtree</var> does not completely "undo" a preceding <var>[[AddSubtree_(XmlDoc/XmlNode_function)|addSubtree]]</var> or <var>[[InsertSubtreeBefore_(XmlNode_function)|insertSubtreeBefore]]</var> method:
<ol>
<li>The top node in the deleted subtree is originally added to the document by an <var>[[AddAttribute_(XmlNode_function)|AddAttribute]]</var> method and has a name prefix.
<li>This attribute node is copied, by <var>AddSubtree</var> or <var>InsertSubtreeBefore</var>, to a target where the attribute prefix is not in scope.
<li>The attribute node is removed by <var>DeleteSubtree</var>, but the namespace declaration for the prefix remains.
</ol>
For example:
<p class="code">%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:<var>DeleteSubtree</var>
Print 'After  AddSubtree/Delete:'
Print %d:Serial(, 'EBCDIC')
</p>
This results in:
<p class="code">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>
</p>
</ul>

==Example==
<ol>
<li>Tthe following example deletes the first <code>employee</code> child of the top-level <var>Element</var> of the <var>XmlDoc</var>:
<p class="code">%doc:deleteSubtree('/*/employee')
</p></ol>

==Request-Cancellation Errors==
<ul>
<li><var class="term">XPath</var> is invalid.
<li>Head of result of <var class="term">XPath</var> is the <var>Root</var> node.
<li>Head of result of <var class="term">XPath</var> is a node whose left and right siblings are <var>Text</var> nodes, and the <var>[[AdjacentText_(XmlDoc_property)|AdjacentText]]</var> property setting is <code>Disallow</code>.
<li><var>Element</var> or <var>Attribute</var> within subtree has a prefix.
<li>Insufficient free space exists in CCATEMP.
</ul>

==See also==
<ul>
<li>For more information about using XPath expressions, see [[XPath]].
</ul>
{{Template:XmlDoc/XmlNode:DeleteSubtree footer}}