InsertSubtreeBefore (XmlNode function): Difference between revisions

From m204wiki
Jump to navigation Jump to search
 
(6 intermediate revisions by 4 users not shown)
Line 1: Line 1:
{{Template:XmlNode:InsertSubtreeBefore subtitle}}
{{Template:XmlNode:InsertSubtreeBefore subtitle}}
This callable function inserts a copy of a <var>subtree</var> of an <var>XmlDoc</var> as the sibling immediately preceding the method <var>XmlNode</var>.  A subtree is a node, all of its attributes and namespace declarations, and
The <var>InsertSubtreeBefore</var> [[Notation conventions for methods#Callable functions|callable]] function inserts a copy of a '''subtree''' of an <var>XmlDoc</var> as the sibling immediately preceding the method <var>XmlNode</var>.  A subtree is a node, all of its attributes and namespace declarations, and all descendants of the node and their attributes and namespace declarations.
all descendants of the node and their attributes and namespace declarations.


==Syntax==
==Syntax==
Line 8: Line 7:
<table class="syntaxTable">
<table class="syntaxTable">
<tr><th>%outNod</th>
<tr><th>%outNod</th>
<td>If specified, an <var>XmlNode</var> that is set to point to the top of the <var>subtree</var> that is inserted. </td></tr>
<td>If specified, an <var>XmlNode</var> that is set to point to the top of the subtree that is inserted.</td></tr>
<tr><th>nod</th>
<tr><th>nod</th>
<td><var>XmlNode</var> that points to the (non-Root) node before which the <var>subtree</var> copy is inserted. </td></tr>
<td><var>XmlNode</var> that points to the (non-Root) node before which the subtree copy is inserted.</td></tr>
<tr><th>sourceSubtreeNod</th>
<tr><th>sourceSubtreeNod</th>
<td><var>XmlNode</var> that points to the non-Root node that is the top of the <var>subtree</var> to be copied. </td></tr>
<td><var>XmlNode</var> that points to the non-Root node that is the top of the subtree to be copied.</td></tr>
<tr><th><var>DefaultURI</var></th>
<tr><th><var>DefaultURI</var></th>
<td>Optional, but <var>[[Methods#Named parameters|Name-Required]]</var> <var>Unicode</var> string parameter that controls the URI of the default namespace of some of the <var>Element</var> nodes of the inserted <var>subtree</var>.
<td>Optional, but [[Methods#Named parameters|name required]], <var>Unicode</var> string parameter that controls the URI of the default namespace of some of the <var>Element</var> nodes of the inserted subtree.
<p>If a <var class="term">DefaultURI</var> argument is specified, its value is used as the URI that is used for all unprefixed elements in the inserted <var>subtree</var> that are not already in the scope of a default namespace declaration within the inserted <var>subtree</var>. For more details, see the "Usage Notes" section, below.</p>
<p>If a <var>DefaultURI</var> argument is specified, its value is used as the URI that is used for all unprefixed elements in the inserted subtree that are not already in the scope of a default namespace declaration within the inserted subtree. For more details, see the [[#Usage_notes|"Usage Notes"]] section, below.</p>
<p>This parameter is available as of <var class="product">[[Sirius Mods]]</var> Version 6.9. Prior to <var class="product">Sirius Mods</var> Version 7.6, ''string'' is an EBCDIC string.</p></td></tr>
<p>This parameter is available as of <var class="product">[[Sirius Mods]]</var> Version 6.9. Prior to <var class="product">Sirius Mods</var> Version 7.6, ''string'' is an EBCDIC string.</p></td></tr>
</table>
</table>
Line 21: Line 20:
==Usage notes==
==Usage notes==
<ul>
<ul>
<li>Since the return value of <var>InsertSubtreeBefore</var> is frequently not needed, you may want to [[Notation_conventions_for_methods#Callable_methods|Call]] it instead of saving its return value.
<li>Since the return value of <var>InsertSubtreeBefore</var> is frequently not needed, you may want to <var>[[Notation_conventions_for_methods#Callable_methods|Call]]</var> it instead of saving its return value.
<li>The target parent and subtree nodes can either be in the same or in different <var>XmlDoc</var>s.
<li>The target parent and subtree nodes can either be in the same or in different <var>XmlDoc</var>s.
<li>When copying between different <var>XmlDoc</var>s under <var class="product">Sirius Mods</var> Version 6.8 or earlier, the <var>XmlDoc</var>s' Namespace properties must be the same, that is, both <code>On</code> or both <code>Off</code>.  As of <var class="product">Sirius Mods</var> Version 6.9, these conditions also permit such copying:
<li>When copying between different <var>XmlDoc</var>s under <var class="product">Sirius Mods</var> Version 6.8 or earlier, the <var>XmlDoc</var>s' <var>[[Namespace (XmlDoc property)|Namespace]]</var> property values must be the same, that is, both <var>On</var> or both <var>Off</var>.  As of <var class="product">Sirius Mods</var> Version 6.9, these conditions also permit such copying:
<ul>
<ul>
<li>The source <var>XmlDoc</var> has <code>Namespace=None</code> and the target <var>XmlDoc</var> has <code>Namespace=Ignore</code>.
<li>The source <var>XmlDoc</var> has <code>Namespace=None</code> and the target <var>XmlDoc</var> has <code>Namespace=Ignore</code>.
<li>The source <var>XmlDoc</var> has <code>Namespace=None</code> and the target <var>XmlDoc</var> has <code>Namespace=On</code>, if the <var class="term">DefaultURI</var> argument is specified.
<li>The source <var>XmlDoc</var> has <code>Namespace=None</code> and the target <var>XmlDoc</var> has <code>Namespace=On</code>, if the <var>DefaultURI</var> argument is specified.
</ul>
</ul>
<li>There is a very small "one-time" processing cost if certain XPath operations are performed after using this method, because Insert-Before methods are guaranteed to add a node out of document order.  In general, processing an <var>XmlDoc</var> is likely to be more efficient if you add nodes in document order (that is, top-to-bottom, left-to-right).
<li>There is a very small "one-time" processing cost if [[XPath#ordScan|certain Xpath expression]] operations are performed after using this method, because "Insert-Before" methods are guaranteed to add a node out of document order.  In general, processing an <var>XmlDoc</var> is likely to be more efficient if you add nodes in document order (that is, top-to-bottom, left-to-right).
<li>A <var>subtree</var> that is a <var>Text</var> node may not be inserted adjacent to (that is, as a sibling of) another <var>Text</var> node, unless the <var>[[AdjacentText (XmlDoc property)|AdjacentText]]</var> property setting is <code>Combine</code>.
<li>A subtree that is a <var>Text</var> node may not be inserted adjacent to (that is, as a sibling of) another <var>Text</var> node, unless the <var>[[AdjacentText (XmlDoc property)|AdjacentText]]</var> property setting is <code>Combine</code>.
<li>A node that is added to an <var>XmlDoc</var> whose <var>[[AllowNull (XmlDoc property)|AllowNull]]</var> property setting is <code>True</code>, may not later be the source node of a subtree to be inserted into a target <var>XmlDoc</var> in which <code>AllowNull=False</code>.
<li>A node that is added to an <var>XmlDoc</var> whose <var>[[AllowNull (XmlDoc property)|AllowNull]]</var> property setting is <code>True</code>, may not later be the source node of a subtree to be inserted into a target <var>XmlDoc</var> in which <code>AllowNull=False</code>.
<li>If the <var class="term">DefaultURI</var> argument is specified, the value of the Namespace property of the method object of <var>InsertSubtreeBefore</var> must be <code>On</code>.
<li>If the <var>DefaultURI</var> argument is specified, the setting of the <var>Namespace</var> property of the method object of <var>InsertSubtreeBefore</var> must be <code>On</code>.
<li>If the <var class="term">DefaultURI</var> argument is ''not'' specified, each node copied by <var>InsertSubtreeBefore</var> retains the URI value it had in the source <var>XmlDoc</var>.
<li>If the <var>DefaultURI</var> argument is ''not'' specified, each node copied by <var>InsertSubtreeBefore</var> retains the URI value it had in the source <var>XmlDoc</var>.
See example [[??]] refid=insub2..
See [[#InsertSubtreeBeforeExample2|Example 2]].
<p>
<p>
If a <var class="term">DefaultURI</var> argument is present, its value becomes the URI of any unprefixed node whose namespace declaration is located at a source <var>XmlDoc</var> element that is ''not'' part of the inserted subtree.  See example [[??]] refid=insub3..</p>
If a <var>DefaultURI</var> argument is present, its value becomes the URI of any unprefixed node whose namespace declaration is located at a source <var>XmlDoc</var> element that is ''not'' part of the inserted subtree.  See [[#InsertSubtreeBeforeExample3|Example 3]].</p>
<p>
<p>
The namespace URI of an unprefixed node is preserved if the namespace declaration is within the inserted subtree, whether the <var class="term">DefaultURI</var> argument is specified or not. See example [[??]] refid=insub4..</p>
The namespace URI of an unprefixed node is preserved if the namespace declaration is within the inserted subtree, whether the <var>DefaultURI</var> argument is specified or not. See [[#InsertSubtreeBeforeExample4|Example 4]].</p>
<li>You can apply the <var>[[DefaultURI (XmlDoc/XmlNode function)|DefaultURI]]</var> function to the <var>InsertSubtreeBefore</var> method object to cause an inserted subtree to "inherit" the default namespace of the target parent node.  See example [[??]] refid=insub5..
<li>You can apply the <var>[[DefaultURI (XmlDoc/XmlNode function)|DefaultURI]]</var> function to the <var>InsertSubtreeBefore</var> method object to cause an inserted subtree to "inherit" the default namespace of the target parent node.  See [[#InsertSubtreeBeforeExample5|Example 5]].
</ul>
</ul>


==Examples==
==Examples==
<ol>
<ol>
<li>In the following example, a subtree (node "c") is inserted before node "a":
<li><div id="InsertSubtreeBeforeExample1"></div>In the following example, a subtree (node "c") is inserted before node "a":
<p class="code">begin
<p class="code">begin
   %doc is object XmlDoc
   %doc is object xmlDoc
   %doc = new
   %doc = new
   [[Notation_conventions_for_methods#Callable_methods|Call]] %doc:[[LoadXml_(XmlDoc/XmlNode_function)|loadXml]]  -
   [[Notation_conventions_for_methods#Callable_methods|Call]] %doc:[[LoadXml_(XmlDoc/XmlNode_function)|loadXml]]  -
Line 58: Line 57:
</p>
</p>
Here is the serialized document before the subtree is inserted:
Here is the serialized document before the subtree is inserted:
<p class="code"><top>
<p class="output"><top>
   <a>
   <a>
       <nowiki><b>05</b></nowiki>
       <nowiki><b>05</b></nowiki>
Line 68: Line 67:
</p>
</p>
Here is the document after the subtree is inserted:
Here is the document after the subtree is inserted:
<p class="code"><top>
<p class="output"><top>
   <c>
   <c>
       <d att="value"/>
       <d att="value"/>
Line 80: Line 79:
</top>
</top>
</p>
</p>
<li>In the following request, a source node is inserted before a sibling node, and the source node retains the URI value it had in the source <var>XmlDoc</var>:
<li><div id="InsertSubtreeBeforeExample2"></div>In the following request, a source node is inserted before a sibling node, and the source node retains the URI value it had in the source <var>XmlDoc</var>:
<p class="code">begin
<p class="code">begin
   %outDoc is object xmlDoc auto new
   %outDoc is object xmlDoc auto new
Line 101: Line 100:
</p>
</p>
These lines result:
These lines result:
<p class="code">Source document:
<p class="output">Source document:
<sourceWrap xmlns="urn:source">
<sourceWrap xmlns="urn:source">
   <source/>
   <source/>
Line 114: Line 113:
The default namespace URI in scope at the <code>source</code> element (child of <code>sourceWrap</code>) is <code>urn:source</code>, and that is retained when the node is copied to its target.
The default namespace URI in scope at the <code>source</code> element (child of <code>sourceWrap</code>) is <code>urn:source</code>, and that is retained when the node is copied to its target.


The result is different if a <code>DefaultURI</code> argument is specified for <var>InsertSubtreeBefore</var> as in the next example.
The result is different if a <var>DefaultURI</var> argument is specified for <var>InsertSubtreeBefore</var> as in the next example.
<li>in the following request fragment:
<li><div id="InsertSubtreeBeforeExample3"></div>in the following request fragment: a source node is copied to a target using a <var>DefaultURI</var> specification, and the source node retains the URI value it had in the source <var>XmlDoc</var>:
a source node is copied to a target using a <tt>DefaultURI</tt> specification,
<p class="code">%top = %outDoc:addElement('top', , 'urn:top')
and the source node retains the URI value it had in the source <var>XmlDoc</var>:
%sib = %top:addElement('sibling')
<p class="code">%top = %outDoc:AddElement('top', , 'urn:top')
%src = %inDoc:addElement('sourceWrap', , 'urn:source')
%sib = %top:AddElement('sibling')
%src = %src:addElement('source')
%src = %inDoc:AddElement('sourceWrap', , 'urn:source')
%sib:insertSubtreeBefore(%src, defaultURI='urn:top')
%src = %src:AddElement('source')
%top:print
%sib:InsertSubtreeBefore(%src, DefaultURI='urn:top')
%top:Print
</p>
</p>


The URI of the <tt>source</tt> element after the subtree is inserted is the URI
The URI of the <code>source</code> element after the subtree is inserted is the URI value specified in the <var>DefaultURI</var> argument:
value specified in the <tt>DefaultURI</tt> argument:
<p class="output"><top xmlns="urn:top">
<p class="code"><top xmlns="urn:top">
   <source/>
   <source/>
   <sibling/>
   <sibling/>
Line 134: Line 130:
</p>
</p>


This <tt>source</tt> element URI would '''not''' be used if
This <code>source</code> element URI would '''not''' be used if the declaration of the default namespace in scope at the <code>source</code> element were inside the source subtree, as in the next example.
the declaration of the default namespace in scope at the <tt>source</tt>
<li><div id="InsertSubtreeBeforeExample4"></div>In the following <var class="product">User Language</var> fragment, the namespace URI of an unprefixed node is preserved (despite the <var>DefaultURI</var> argument), since the namespace declaration is within the inserted subtree:
element were inside the source subtree, as in the next example.
<p class="code">%top = %outDoc:addElement('top', , 'urn:top')
<li>In the following User Language fragment, the namespace URI of an unprefixed
%sib = %top:addElement('sibling')
node is preserved
%src = %inDoc:addElement('source', , 'urn:source')
(despite the <tt>DefaultURI</tt> argument),
%sib:insertSubtreeBefore(%src, defaultURI='urn:top')
since the namespace declaration is within the inserted subtree:
%top:print
<p class="code">%top = %outDoc:AddElement('top', , 'urn:top')
%sib = %top:AddElement('sibling')
%src = %inDoc:AddElement('source', , 'urn:source')
%sib:InsertSubtreeBefore(%src, DefaultURI='urn:top')
%top:Print
</p>
</p>
The result is:
The result is:
Line 153: Line 144:
</top>
</top>
</p>
</p>
<li>In the following fragment,
<li><div id="InsertSubtreeBeforeExample5"></div>In the following fragment, the <var>[[DefaultURI (XmlDoc/XmlNode function)|DefaultURI]]</var> function is used to provide a value for the <var>DefaultURI</var> argument so that the inserted subtree "inherits" the default namespace of the parent of the target sibling node:
the [[DefaultURI (XmlDoc/XmlNode function)|DefaultURI]] function
is used to provide a value for the <tt>DefaultURI</tt> argument so that
the inserted subtree "inherits" the default namespace of the
parent of the target sibling node:


For example, in the following User Language fragment:
For example, in the following <var class="product">User Language</var> fragment:
<p class="code">%top = %outDoc:AddElement('top', , 'urn:top')
<p class="code">%top = %outDoc:AddElement('top', , 'urn:top')
%sib = %top:AddElement('sibling')
%sib = %top:addElement('sibling')
%src = %inDoc:AddElement('sourceWrap', , 'urn:source')
%src = %inDoc:addElement('sourceWrap', , 'urn:source')
%src = %src:AddElement('source')
%src = %src:addElement('source')


%sib:InsertSubtreeBefore(%src, DefaultURI=%top:DefaultURI)
%sib:insertSubtreeBefore(%src, defaultURI=%top:DefaultURI)
%top:Print
%top:print
</p>
</p>
The result is:
The result is:
Line 175: Line 162:
</p>
</p>


The following method call, which uses the XPath notation for parent node
The following method call, which uses the [[XPath]] notation for parent node (<code>..</code>) in the <var>DefaultURI</var> function argument,
(<tt>..</tt>) in the DefaultURI function argument,
will also produce the same result:
will also produce the same result:
<p class="code">%sib:InsertSubtreeBefore(%src,                  -
<p class="code">%sib:insertSubtreeBefore(%src,                  -
   DefaultURI=%sib:DefaultURI('..'))
   defaultURI=%sib:defaultURI('..'))
</p>
</p>
</ol>
</ol>


==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">Nod</var> is the <var>Root</var> node.
<li>Object <var class="term">nod</var> is the <var>Root</var> node.
<li><var class="term">sourceSubtreeNod</var> is a <var>Root</var> node.
 
<li><var class="term">Nod</var> is the same as, or a descendant of, <var class="term">sourceSubtreeNod</var>.
<li>The <var class="term">sourceSubtreeNode</var> argument is a <var>Root</var> node.
<li>Source and target <var>XmlDoc</var>s have different Namespace settings.
 
<li><var class="term">nod</var> is the same as, or a descendant of, <var class="term">sourceSubtreeNode</var>.
 
<li>Source and target <var>XmlDoc</var>s have different <var>Namespace</var> settings.
 
<li>Any of the errors which would occur based on insertion of the top subtree node at the given target parent: for example,
<li>Any of the errors which would occur based on insertion of the top subtree node at the given target parent: for example,
<ul>
<ul>
<li>insertion of a duplicate attribute
<li>Insertion of a duplicate <var>Attribute</var>
<li>insertion of a <var>Text</var> node before a target <var>Text</var> node, when the <var>AdjacentText</var> property setting is <code>Disallow</code>
<li>Insertion of a <var>Text</var> node before a target <var>Text</var> node, when the <var>AdjacentText</var> property setting is <code>Disallow</code>
<li>insertion of a <var>Text</var> node before a target sibling that follows a <var>Text</var> node, when the <var>AdjacentText</var> property setting is <code>Disallow</code>
<li>Insertion of a <var>Text</var> node before a target sibling that follows a <var>Text</var> node, when the <var>AdjacentText</var> property setting is <code>Disallow</code>
</ul>
</ul>
See the "Add" function corresponding to the type of the subtree node (for those examples just cited, <var>[[AddAttribute (XmlNode function)|AddAttribute]]</var> and <var>[[AddText (XmlNode function)|AddText]]</var>, respectively).
See the "Add" function corresponding to the type of the subtree node (for those examples just cited, <var>[[AddAttribute (XmlNode function)|AddAttribute]]</var> and <var>[[AddText (XmlNode function)|AddText]]</var>, respectively).
<li>Insufficient free space exists in CCATEMP.
<li>Insufficient free space exists in CCATEMP.
</ul>
</ul>
Line 201: Line 193:
==See also==
==See also==
<ul>
<ul>
<li><var>[[AddSubtree (XmlDoc/XmlNode function)|AddSubtree]]</var> also copies a Subtree node.  <var>InsertSubtreeBefore</var> copies a subtree as the immediately preceding sibling of the node pointed to by the method object; <var>AddSubtree</var> copies a subtree as the last child of the node pointed to by the method object.
<li><var>[[AddSubtree (XmlDoc/XmlNode function)|AddSubtree]]</var> also copies a subtree node.  <var>InsertSubtreeBefore</var> copies a subtree as the immediately preceding sibling of the node pointed to by the method object; <var>AddSubtree</var> copies a subtree as the last child of the node pointed to by the method object.
<li>For hints about inserting a node ''after'' a sibling node, see the <var>[[InsertElementBefore_(XmlNode_function)#Examples|"Example section in InsertElementBefore"]]</var>.
<li>For hints about inserting a node ''after'' a sibling node, see the <var>InsertElementBefore</var> [[InsertElementBefore_(XmlNode_function)#Examples|"Examples"]] section.
</ul>
</ul>
{{Template:XmlNode:InsertSubtreeBefore footer}}
{{Template:XmlNode:InsertSubtreeBefore footer}}

Latest revision as of 17:32, 3 March 2014

Insert copy of subtree before this node (XmlNode class)

[Requires Janus SOAP]

The InsertSubtreeBefore callable function inserts a copy of a subtree of an XmlDoc as the sibling immediately preceding the method XmlNode. A subtree is a node, all of its attributes and namespace declarations, and all descendants of the node and their attributes and namespace declarations.

Syntax

[%outNod =] nod:InsertSubtreeBefore( sourceSubtreeNode, [DefaultURI= unicode])

Syntax terms

%outNod If specified, an XmlNode that is set to point to the top of the subtree that is inserted.
nod XmlNode that points to the (non-Root) node before which the subtree copy is inserted.
sourceSubtreeNod XmlNode that points to the non-Root node that is the top of the subtree to be copied.
DefaultURI Optional, but name required, Unicode string parameter that controls the URI of the default namespace of some of the Element nodes of the inserted subtree.

If a DefaultURI argument is specified, its value is used as the URI that is used for all unprefixed elements in the inserted subtree that are not already in the scope of a default namespace declaration within the inserted subtree. For more details, see the "Usage Notes" section, below.

This parameter is available as of Sirius Mods Version 6.9. Prior to Sirius Mods Version 7.6, string is an EBCDIC string.

Usage notes

  • Since the return value of InsertSubtreeBefore is frequently not needed, you may want to Call it instead of saving its return value.
  • The target parent and subtree nodes can either be in the same or in different XmlDocs.
  • When copying between different XmlDocs under Sirius Mods Version 6.8 or earlier, the XmlDocs' Namespace property values must be the same, that is, both On or both Off. As of Sirius Mods Version 6.9, these conditions also permit such copying:
    • The source XmlDoc has Namespace=None and the target XmlDoc has Namespace=Ignore.
    • The source XmlDoc has Namespace=None and the target XmlDoc has Namespace=On, if the DefaultURI argument is specified.
  • There is a very small "one-time" processing cost if certain Xpath expression operations are performed after using this method, because "Insert-Before" methods are guaranteed to add a node out of document order. In general, processing an XmlDoc is likely to be more efficient if you add nodes in document order (that is, top-to-bottom, left-to-right).
  • A subtree that is a Text node may not be inserted adjacent to (that is, as a sibling of) another Text node, unless the AdjacentText property setting is Combine.
  • A node that is added to an XmlDoc whose AllowNull property setting is True, may not later be the source node of a subtree to be inserted into a target XmlDoc in which AllowNull=False.
  • If the DefaultURI argument is specified, the setting of the Namespace property of the method object of InsertSubtreeBefore must be On.
  • If the DefaultURI argument is not specified, each node copied by InsertSubtreeBefore retains the URI value it had in the source XmlDoc. See Example 2.

    If a DefaultURI argument is present, its value becomes the URI of any unprefixed node whose namespace declaration is located at a source XmlDoc element that is not part of the inserted subtree. See Example 3.

    The namespace URI of an unprefixed node is preserved if the namespace declaration is within the inserted subtree, whether the DefaultURI argument is specified or not. See Example 4.

  • You can apply the DefaultURI function to the InsertSubtreeBefore method object to cause an inserted subtree to "inherit" the default namespace of the target parent node. See Example 5.

Examples

  1. In the following example, a subtree (node "c") is inserted before node "a":

    begin %doc is object xmlDoc %doc = new Call %doc:loadXml - ('<top><a><b>05</b></a><c><d att="value"></d></c></top>') %n1 is object xmlNode %n2 is object xmlNode %n1 = %doc:selectSingleNode('top/c') %n2 = %doc:selectSingleNode('top/a') call %n2:insertSubtreeBefore(%n1) call %doc:print('top') end

    Here is the serialized document before the subtree is inserted:

    <top> <a> <b>05</b> </a> <c> <d att="value"/> </c> </top>

    Here is the document after the subtree is inserted:

    <top> <c> <d att="value"/> </c> <a> <b>05</b> </a> <c> <d att="value"/> </c> </top>

  2. In the following request, a source node is inserted before a sibling node, and the source node retains the URI value it had in the source XmlDoc:

    begin %outDoc is object xmlDoc auto new %inDoc is object xmlDoc auto new %top is object xmlNode %src is object xmlNode %sib is object xmlNode %top = %outDoc:addElement('top', , 'urn:top') %sib = %top:AddElement('sibling') %src = %inDoc:AddElement('sourceWrap', , 'urn:source') %src = %src:AddElement('source') %sib:InsertSubtreeBefore(%src) print 'Source document:' %inDoc:print print ' ' print 'Target document including copied subtree:' %outDoc:print end

    These lines result:

    Source document: <sourceWrap xmlns="urn:source"> <source/> </sourceWrap> Target document including copied subtree: <top xmlns="urn:top"> <source xmlns="urn:source"/> <sibling/> </top>

    The default namespace URI in scope at the source element (child of sourceWrap) is urn:source, and that is retained when the node is copied to its target.

    The result is different if a DefaultURI argument is specified for InsertSubtreeBefore as in the next example.

  3. in the following request fragment: a source node is copied to a target using a DefaultURI specification, and the source node retains the URI value it had in the source XmlDoc:

    %top = %outDoc:addElement('top', , 'urn:top') %sib = %top:addElement('sibling') %src = %inDoc:addElement('sourceWrap', , 'urn:source') %src = %src:addElement('source') %sib:insertSubtreeBefore(%src, defaultURI='urn:top') %top:print

    The URI of the source element after the subtree is inserted is the URI value specified in the DefaultURI argument:

    <top xmlns="urn:top"> <source/> <sibling/> </top>

    This source element URI would not be used if the declaration of the default namespace in scope at the source element were inside the source subtree, as in the next example.

  4. In the following User Language fragment, the namespace URI of an unprefixed node is preserved (despite the DefaultURI argument), since the namespace declaration is within the inserted subtree:

    %top = %outDoc:addElement('top', , 'urn:top') %sib = %top:addElement('sibling') %src = %inDoc:addElement('source', , 'urn:source') %sib:insertSubtreeBefore(%src, defaultURI='urn:top') %top:print

    The result is:

    <top xmlns="urn:top"> <source xmlns="urn:source"/> <sibling/> </top>

  5. In the following fragment, the DefaultURI function is used to provide a value for the DefaultURI argument so that the inserted subtree "inherits" the default namespace of the parent of the target sibling node:

    For example, in the following User Language fragment:

    %top = %outDoc:AddElement('top', , 'urn:top') %sib = %top:addElement('sibling') %src = %inDoc:addElement('sourceWrap', , 'urn:source') %src = %src:addElement('source') %sib:insertSubtreeBefore(%src, defaultURI=%top:DefaultURI) %top:print

    The result is:

    <top xmlns="urn:top"> <source/> <sibling/> </top>

    The following method call, which uses the XPath notation for parent node (..) in the DefaultURI function argument, will also produce the same result:

    %sib:insertSubtreeBefore(%src, - defaultURI=%sib:defaultURI('..'))

Request-cancellation errors

This list is not exhaustive: it does not include all the errors that are request cancelling.

  • Object nod is the Root node.
  • The sourceSubtreeNode argument is a Root node.
  • nod is the same as, or a descendant of, sourceSubtreeNode.
  • Source and target XmlDocs have different Namespace settings.
  • Any of the errors which would occur based on insertion of the top subtree node at the given target parent: for example,
    • Insertion of a duplicate Attribute
    • Insertion of a Text node before a target Text node, when the AdjacentText property setting is Disallow
    • Insertion of a Text node before a target sibling that follows a Text node, when the AdjacentText property setting is Disallow

    See the "Add" function corresponding to the type of the subtree node (for those examples just cited, AddAttribute and AddText, respectively).

  • Insufficient free space exists in CCATEMP.

See also

  • AddSubtree also copies a subtree node. InsertSubtreeBefore copies a subtree as the immediately preceding sibling of the node pointed to by the method object; AddSubtree copies a subtree as the last child of the node pointed to by the method object.
  • For hints about inserting a node after a sibling node, see the InsertElementBefore "Examples" section.