DeleteSubtree (XmlDoc/XmlNode subroutine): Difference between revisions
Line 57: | Line 57: | ||
</p> | </p> | ||
<li>As discussed in the <var>XmlDoc</var> API [[#Updating|section on updating]], the items deleted by <var>DeleteSubtree</var> are not available for re-use by later Add, Insert, etc. methods, | <li>As discussed in the <var>XmlDoc</var> 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>. | ||
</ul> | </ul> | ||
Revision as of 20:10, 20 February 2014
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:
- 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.
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
- 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".