DeleteSubtree (XmlDoc/XmlNode subroutine): Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (1 revision)
m (1 revision)
Line 18: Line 18:
<tr><th>XPath</th>
<tr><th>XPath</th>
<td>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 (<i>nr</i>).
<td>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 (<i>nr</i>).
Prior to ''Sirius Mods'' version 7.6, this is an EBCDIC string.</td></tr>
<p class="code">Prior to ''Sirius Mods'' version 7.6, this is an EBCDIC string.</td></tr>
</p>
</table>
</table>


Line 34: Line 35:
applied to that node does not remove the namespace declaration.
applied to that node does not remove the namespace declaration.
For example:
For example:
<pre>
<p class="code">%d = New
    %d = New
%n = %d:AddElement('x')
    %n = %d:AddElement('x')
Print 'Before AddAttribute/Delete:' And %d:Serial(, 'EBCDIC')
    Print 'Before AddAttribute/Delete:' And %d:Serial(, 'EBCDIC')
%n = %n:AddAttribute('p:a', 'v', 'ftp:a')
    %n = %n:AddAttribute('p:a', 'v', 'ftp:a')
%n:DeleteSubtree
    %n:DeleteSubtree
Print 'After  AddAttribute/Delete:' And %d:Serial(, 'EBCDIC')
    Print 'After  AddAttribute/Delete:' And %d:Serial(, 'EBCDIC')
</p>
</pre>
This results in:
This results in:
<pre>
<p class="code">Before AddAttribute/Delete: <x/>
    Before AddAttribute/Delete: <x/>
After  AddAttribute/Delete: <x xmlns:p="ftp:a"/>
    After  AddAttribute/Delete: <x xmlns:p="ftp:a"/>
</p>
</pre>
<li>In the following circumstances, DeleteSubtree does not completely "undo"
<li>In the following circumstances, DeleteSubtree does not completely "undo"
a preceding
a preceding
Line 59: Line 58:
</ol>
</ol>
For example:
For example:
<pre>
<p class="code">%d = New
    %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:DeleteSubtree
    %n2:DeleteSubtree
Print 'After  AddSubtree/Delete:'
    Print 'After  AddSubtree/Delete:'
Print %d:Serial(, 'EBCDIC')
    Print %d:Serial(, 'EBCDIC')
</p>
</pre>
This results in:
This results in:
<pre>
<p class="code">Before AddSubtree/Delete:
    Before AddSubtree/Delete:
<x><x1 xmlns:p="ftp:a" p:a="v"/><x2/></x>
    <x><x1 xmlns:p="ftp:a" p:a="v"/><x2/></x>
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>
</pre>
</ul>
</ul>


Line 85: Line 82:
The method in the following example deletes the first <tt>employee</tt>
The method in the following example deletes the first <tt>employee</tt>
child of the top-level Element of the XmlDoc:
child of the top-level Element of the XmlDoc:
<pre>
<p class="code">%doc:DeleteSubtree('/*/employee')
    %doc:DeleteSubtree('/*/employee')
</p>
</pre>


===Request-Cancellation Errors===
===Request-Cancellation Errors===

Revision as of 05:42, 25 January 2011

Delete selected subtree (XmlDoc and XmlNode classes)

This subroutine 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 argument XPath expression (XPath) 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')

    This 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 method in the following example deletes the first employee child of the top-level Element of the XmlDoc:

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

Request-Cancellation Errors

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