DeleteSubtree (XmlDoc/XmlNode subroutine): Difference between revisions

From m204wiki
Jump to navigation Jump to search
mNo edit summary
 
(10 intermediate revisions by 4 users not shown)
Line 4: Line 4:
==Syntax==
==Syntax==
{{Template:XmlDoc/XmlNode:DeleteSubtree syntax}}
{{Template:XmlDoc/XmlNode:DeleteSubtree syntax}}
===Syntax terms===
===Syntax terms===
<table class="syntaxTable">
<table class="syntaxTable">
<tr><th>nr</th>
<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>
<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>
<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>).
<td>A <var>Unicode</var> string that is an [[XPath#XPath_syntax|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.
<p>Prior to <var class="product">[[Sirius Mods|"Sirius Mods"]]</var> Version 7.6, this is an EBCDIC string.</p></td></tr>
<p>
This is an optional argument, and its default is a period (<tt>.</tt>), that is, the node referenced by the method object (<var class="term">nr</var>).</p>
<p>
Prior to <var class="product">[[Sirius Mods]]</var> Version 7.6, this is an EBCDIC string.</p></td></tr>
</table>
</table>


==Usage notes==
==Usage notes==
<ul>
<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>Any pointers (as <var>XmlNode</var>s or in <var>XmlNodelist</var>s) to the deleted node or any of its descendants will subsequently evaluate to <var>Null</var>.</li>
<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><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>
<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.
 
<li>If the result of the <var class="term">xpath</var> argument expression is empty, <var>DeleteSubtree</var> returns without deleting any nodes.</li>
 
<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:
For example:
<p class="code">%d = new
<p class="code">%d = new
Line 30: Line 38:
<p class="output">Before AddAttribute/Delete: <x/>
<p class="output">Before AddAttribute/Delete: <x/>
After  AddAttribute/Delete: <x xmlns:p="ftp:a"/>
After  AddAttribute/Delete: <x xmlns:p="ftp:a"/>
</p>
</p></li>
<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:
 
<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>
<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>The top node in the deleted subtree is originally added to the document by an <var>AddAttribute</var> method and has a name prefix.</li>
<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.
<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>
 
<li>The attribute node is removed by <var>DeleteSubtree</var>, but the namespace declaration for the prefix remains.</li>
</ol>
</ol>
For example:
For example:
<p class="code">%d = New
<p class="code">%d = new
%n = %d:AddElement('x')
%n = %d:addElement('x')
%n2 = %n:AddElement('x1')
%n2 = %n:addElement('x1')
%n = %n:AddElement('x2')
%n = %n:addElement('x2')
%n2 = %n2:AddAttribute('p:a', 'v', 'ftp:a')
%n2 = %n2:addAttribute('p:a', 'v', 'ftp:a')
Print 'Before AddSubtree/Delete:'
print 'Before AddSubtree/Delete:'
Print %d:Serial(, 'EBCDIC')
print %d:Serial(, 'EBCDIC')
%n2 = %n:AddSubtree(%n2)
%n2 = %n:addSubtree(%n2)
%n2:<var>DeleteSubtree</var>
%n2:<var>deleteSubtree</var>
Print 'After  AddSubtree/Delete:'
print 'After  AddSubtree/Delete:'
Print %d:Serial(, 'EBCDIC')
print %d:Serial(, 'EBCDIC')
</p>
</p>
This results in:
This results in:
Line 55: Line 66:
After  AddSubtree/Delete:
After  AddSubtree/Delete:
<x><x1 xmlns:p="ftp:a" p:a="v"/><x2 xmlns:p="ftp:a"/></x>
<x><x1 xmlns:p="ftp:a" p:a="v"/><x2 xmlns:p="ftp:a"/></x>
</p>
</p></li>
 
<li>As discussed in the <var>XmlDoc</var> API [[XmlDoc API#Updating|section on updating]], the items deleted by <var>DeleteSubtree</var> are not available for re-use by later Add, Insert, etc. methods, so <var>DeleteSubtree</var> does not affect the restriction of 16M items in an <var>XmlDoc</var>.</li>
</ul>
</ul>


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


==Request-Cancellation Errors==
==Request-cancellation errors==
This list is not exhaustive: it does <i>not</i> include all the errors that are request  cancelling.
<ul>
<ul>
<li><var class="term">XPath</var> is invalid.
<li>The <var class="term">xpath</var> value 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 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>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><var>Element</var> or <var>Attribute</var> within subtree has a prefix.
<li>Insufficient free space exists in CCATEMP.
<li>Insufficient free space exists in CCATEMP.
Line 75: Line 88:
==See also==
==See also==
<ul>
<ul>
<li>For more information about using XPath expressions, see [[XPath]].
<li>For more information about using XPath expressions, see [[XPath|"XPath"]].
</ul>
</ul>
{{Template:XmlDoc/XmlNode:DeleteSubtree footer}}
{{Template:XmlDoc/XmlNode:DeleteSubtree footer}}

Latest revision as of 22:23, 17 February 2015

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".