DeleteSubtree (XmlDoc/XmlNode subroutine): Difference between revisions

From m204wiki
Jump to navigation Jump to search
mNo edit summary
mNo edit summary
Line 7: Line 7:
<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 head of the nodelist is the "top" node of the subtree to delete. An optional argument, its default is a period (<tt>.</tt>), that is, the node referenced by the method object (<var class="term">nr</var>).
<p>Prior to <var class="product">[[Sirius Mods]]</var> Version 7.6, this is an EBCDIC string.</p></td></tr>
<p>Prior to <var class="product">[[Sirius Mods]]</var> Version 7.6, this is an EBCDIC string.</p></td></tr>
</table>
</table>
Line 17: Line 17:
<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 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><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 XPath expression is empty, <var>DeleteSubtree</var> returns without deleting any nodes.
<li>If the result of the <var class="term">xpath</var> argument 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.
<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 31: Line 31:
After  AddAttribute/Delete: <x xmlns:p="ftp:a"/>
After  AddAttribute/Delete: <x xmlns:p="ftp:a"/>
</p>
</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:
<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>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>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>The attribute node is removed by <var>DeleteSubtree</var>, but the namespace declaration for the prefix remains.
Line 63: Line 63:
</p>
</p>


==Request-Cancellation Errors==
==Request-cancellation errors==
<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>.

Revision as of 21:36, 31 May 2011

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

Example

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

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

Request-cancellation errors

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