AddSubtree (XmlDoc/XmlNode function): Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (move footer template to actual end (otherwise subsequent intervening text gets omitted); edits, tags and links)
 
 
(17 intermediate revisions by 4 users not shown)
Line 1: Line 1:
{{Template:XmlDoc/XmlNode:AddSubtree subtitle}}
{{Template:XmlDoc/XmlNode:AddSubtree subtitle}}
The <var>AddSubtree</var> callable function copies a <var>subtree</var> of an <var>XmlDoc</var> to the method parent node, where it becomes the last child of that node.  A <var>subtree</var> is a node, all of its attributes and namespace declarations, and all descendants of the node and their attributes and namespace declarations.
The <var>AddSubtree</var> [[Notation_conventions_for_methods#Callable_methods|callable]] function copies a subtree of an <var>XmlDoc</var> to the method parent node, where it becomes the last child of that node.  A <strong>subtree</strong> is a node, all of its attributes and namespace declarations, and all descendants of the node and their attributes and namespace declarations.


==Syntax==
==Syntax==
{{Template:XmlDoc/XmlNode:AddSubtree syntax}}
{{Template:XmlDoc/XmlNode:AddSubtree syntax}}
===Syntax terms===
===Syntax terms===
<table class="syntaxTable">
<table class="syntaxTable">
<tr><th>%nod</th>
<tr><th>%nod</th>
<td>If specified, an <var>XmlNode</var> that is set to point to the top of the <var>subtree</var> that is added.</td></tr>
<td>If specified, an <var>XmlNode</var> that is set to point to the top of the subtree that is added.</td></tr>
 
<tr><th>nr</th>
<tr><th>nr</th>
<td>An <var>XmlDoc</var> or <var>XmlNode</var> that refers to the <var>Root</var> or <var>Element</var> node parent of the added <var>subtree</var>.</td></tr>
<td>An <var>XmlDoc</var> or <var>XmlNode</var> that refers to the <var>Root</var> or <var>Element</var> node parent of the added subtree.</td></tr>
 
<tr><th>sourceSubtreeNode</th>
<tr><th>sourceSubtreeNode</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>DefaultURI</th>
 
<td>This optional, but <var>[[Methods#Named parameters|Name-Required]]</var> parameter <var>Unicode</var> is a string that controls the URI of the default namespace of some of the <var>Element</var> nodes of the added subtree.
<tr><th><var>DefaultURI</var></th>
<p>If a <var class="term">DefaultURI</var> argument is specified, its value becomes the URI that is used for all unprefixed elements in the added <var>subtree</var> that are not already in the scope of a default namespace declaration within the added <var>subtree</var>. For more details, see the [[AddSubtree_(XmlDoc/XmlNode_function)#Usage_notes|"Usage Notes"]] and [[AddSubtree_(XmlDoc/XmlNode_function)#Examples|"Examples"]] sections, below.</p>
<td>This optional, [[Methods#Named parameters|name required]] parameter is a <var>Unicode</var> string that controls the URI of the default namespace of some of the <var>Element</var> nodes of the added subtree.
<p>This parameter is available as of <var class="product">[[Sirius Mods|"Sirius Mods"]]</var> Version 6.9.</p></td></tr>
<p>If a <var>DefaultURI</var> argument is specified, its value becomes the URI that is used for all unprefixed elements in the added subtree that are not already in the scope of a default namespace declaration within the added subtree. For more details, see the [[AddSubtree_(XmlDoc/XmlNode_function)#Usage_notes|Usage notes]] and [[AddSubtree_(XmlDoc/XmlNode_function)#Examples|Examples]] sections, below.</p>
</td></tr>
</table>
</table>


Line 22: Line 26:
<li>Since the return value of <var>AddSubtree</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>Since the return value of <var>AddSubtree</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 <var>subtree</var> nodes can either be in the same or in different <var>XmlDoc</var>s.
<li>The target parent and <var>subtree</var> 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>.
Line 28: Line 32:
</ul>
</ul>
<li>Processing of 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>Processing of 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 added 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 <var>subtree</var> that is a <var>Text</var> node may not be added adjacent to (that is, as a sibling of) another <var>Text</var> node, unless the <var>[[AdjacentText (XmlDoc property)|AdjacentText]]</var> property value is <var>Combine</var>.
<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 <var>subtree</var> to be copied to 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 <var>subtree</var> to be copied to 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>AddSubtree</var> must be <code>On</code>.
<li>If the <var>DefaultURI</var> argument is specified, the value of the <var>Namespace</var> property of the method object of <var>AddSubtree</var> must be <var>On</var>.
<li>If the <var class="term">DefaultURI</var> argument is ''not'' specified, each node added by <var>AddSubtree</var> retains the URI value it had in the source <var>XmlDoc</var>.  See the [[#adsub2|example]] below.
<li>If the <var>DefaultURI</var> argument is ''not'' specified, each node added by <var>AddSubtree</var> retains the URI value it had in the source <var>XmlDoc</var>.  See [[#adsub2|example 2]] below.
 
<p>If a <var>DefaultURI</var> argument is present, its value is used as the URI of any unprefixed node whose namespace declaration is located at a source <var>XmlDoc</var> element that is ''not'' part of the added subtree.  See [[#adsub3|example 3]] below.</p>
If a <var class="term">DefaultURI</var> argument is present, its value is used as the URI of any unprefixed node whose namespace declaration is located at a source <var>XmlDoc</var> element that is ''not'' part of the added <var>subtree</var>.  See the [[#adsub3|example]] below.
<p>The namespace URI of an unprefixed node is preserved if the namespace declaration is within the copied subtree, whether the <var>DefaultURI</var> argument is specified or not. See [[#adsub4|example 4]] below.</p>
 
<li>You can apply the <var>[[DefaultURI (XmlDoc/XmlNode function)|DefaultURI]]</var> function to the <var>AddSubtree</var> method object to cause an added subtree to "inherit" the default namespace of that node.  See [[#adsub5|example 5]] below.
The namespace URI of an unprefixed node is preserved if the namespace declaration is within the copied <var>subtree</var>, whether the <var class="term">DefaultURI</var> argument is specified or not. See the [[#adsub4|example]] below.
<li>You can apply the <var>[[DefaultURI (XmlDoc/XmlNode function)|DefaultURI]]</var> function to the <var>AddSubtree</var> method object to cause an added <var>subtree</var> to "inherit" the default namespace of that node.  See the [[#adsub5|example]] below.
</ul>
</ul>


==Examples==
==Examples==
<ol>
<ol>
<li>In the following example,
<li>In the following example, the top-level Element (and its descendants) from <var>XmlDoc</var> <code>%doc2</code> are copied as the "body" of a SOAP request document in <code>%doc1</code>:
the top-level Element (and its descendants) from <var>XmlDoc</var> <tt>%doc2</tt> are
<p class="code">begin
copied as the "body" of a SOAP request document in <tt>%doc1</tt>:
  %doc1 is object xmlDoc
<p class="code">Begin
  %doc1 = new
%doc1 is Object XmlDoc
  %n1 is object xmlNode
%doc1 = new
  %n2 is object xmlNode
%n1 is Object XmlNode
  %n1 = %doc1:[[AddElement_(XmlDoc/XmlNode_function)|addElement]]('SOAP-ENV:Envelope', ,  -
%n2 is Object XmlNode
      <nowiki>'http://schemas.xmlsoap.org/soap/envelope/'</nowiki>)
%n1 = %doc1:AddElement('SOAP-ENV:Envelope', ,  -
  %n1 = %n1:addElement('SOAP-ENV:Body')
  'http://schemas.xmlsoap.org/soap/envelope/')
  %doc2 is object xmlDoc
%n1 = %n1:AddElement('SOAP-ENV:Body')
  %doc2 = new
%doc2 is Object XmlDoc
  %doc2:[[LoadXml_(XmlDoc/XmlNode_function)|loadXml]]<nowiki>('<top><a><b>05</b></a></top>')</nowiki>
%doc2 = new
  %n2 = %doc2:selectSingleNode('top')
%doc2:LoadXml<nowiki>('<top><a><b>05</b></a></top>')</nowiki>
  %n1:addSubtree(%n2)
%n2 = %doc2:SelectSingleNode('top')
  %doc1:print
%n1:AddSubtree(%n2)
end
%doc1:Print
End
</p>
</p>
Here is "doc1" before the subtree is added:
Here is "doc1" before the subtree is added:
<p class="code"><SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<p class="output"><nowiki><SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
   <SOAP-ENV:Body/>
   <SOAP-ENV:Body/>
</SOAP-ENV:Envelope>
</SOAP-ENV:Envelope></nowiki>
</p>
</p>
Here is "doc1" after the subtree is added:
Here is "doc1" after the subtree is added:
<p class="output"><nowiki><SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<p class="output"><nowiki><SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
Line 77: Line 75:
   </SOAP-ENV:Body>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope></nowiki>
</SOAP-ENV:Envelope></nowiki>
</p>
</p><div id="adsub2"></div>
<br>
<li>In the following request, a source node is added to a target node, and the source node retains the URI value it had in the source <var>XmlDoc</var>:
<div id="adsub2"></div>
<p class="code">begin
<li>In the following request, a source node is added to a target node,
  %outDoc is object xmlDoc auto new
and the source node retains the URI value it had in the source <var>XmlDoc</var>:
  %inDoc is object xmlDoc auto new
<p class="code">Begin
  %tar is object xmlNode
%outDoc is Object XmlDoc Auto New
  %src is object xmlNode
%inDoc is Object XmlDoc Auto New
%tar is Object XmlNode
%src is Object XmlNode


%tar = %outDoc:AddElement('target', , 'urn:target')
  %tar = %outDoc:addElement('target', , 'urn:target')
%src = %inDoc:AddElement('sourceWrap', , 'urn:source')
  %src = %inDoc:addElement('sourceWrap', , 'urn:source')
%src = %src:AddElement('source')
  %src = %src:addElement('source')
%tar:AddSubtree(%src)
  %tar:addSubtree(%src)
Print 'Source document:'
  print 'Source document:'
%inDoc:Print
  %inDoc:print
Print '    '
  print '    '
Print 'Target document including copied subtree:'
  print 'Target document including copied subtree:'
%outDoc:Print
  %outDoc:Print
End
end
</p>
</p>
These lines result:
These lines result:
<p class="code">Source document:
<p class="code">Source document:
Line 105: Line 99:
   <source/>
   <source/>
</sourceWrap>
</sourceWrap>
Target document including copied subtree:
Target document including copied subtree:
<target xmlns="urn:target">
<target xmlns="urn:target">
Line 111: Line 104:
</target>
</target>
</p>
</p>
 
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 <var>DefaultURI</var> argument is specified for <var>AddSubtree</var> as in the next example.
The default namespace URI in scope at the <tt>source</tt> element (child
of <tt>sourceWrap</tt>) is <tt>urn:source</tt>, and that is retained when the node is copied to its target.
 
The result is different if a <tt>DefaultURI</tt> argument is specified for
<var>AddSubtree</var> as in the next example.
<div id="adsub3"></div>
<div id="adsub3"></div>
<li>In the following request fragment,
<li>In the following request fragment, a source node is added to a target node 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 added to a target node using a <tt>DefaultURI</tt> specification,
and the source node retains the URI value it had in the source <var>XmlDoc</var>:


<p class="code">%tar = %outDoc:AddElement('target', , 'urn:target')
<p class="code">%tar = %outDoc:AddElement('target', , 'urn:target')
Line 129: Line 115:
</p>
</p>


The URI of the <tt>source</tt> element after the subtree is added is the URI
The URI of the <code>source</code> element after the subtree is added is the URI value specified in the <var>DefaultURI</var> argument:
value specified in the <tt>DefaultURI</tt> argument:
<p class="code"><target xmlns="urn:target">
<p class="code"><target xmlns="urn:target">
   <source/>
   <source/>
Line 136: Line 121:
</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 <var>source</var> element were inside the source subtree, as in the next example.
the declaration of the default namespace in scope at the <tt>source</tt>
element were inside the source subtree, as in the next example.
<div id="adsub4"></div>
<div id="adsub4"></div>
<li>In the following User Language fragment, the namespace URI of an unprefixed
 
node is preserved
<li>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 added subtree:
(despite the <tt>DefaultURI</tt> argument),
since the namespace declaration is within the added subtree:
<p class="code">%tar = %outDoc:AddElement('target', , 'urn:target')
<p class="code">%tar = %outDoc:AddElement('target', , 'urn:target')
%src = %inDoc:AddElement('source', , 'urn:source')
%src = %inDoc:addElement('source', , 'urn:source')
%tar:AddSubtree(%src, DefaultURI='urn:target')
%tar:addSubtree(%src, DefaultURI='urn:target')
%tar:Print
%tar:print
</p>
</p>
The result is:
The result is:
Line 155: Line 136:
</p>
</p>
<div id="adsub5"></div>
<div id="adsub5"></div>
<li>In the following fragment,
<li>In the following fragment, the <var>DefaultURI</var> function is used to provide a value for the <var>DefaultURI</var> argument so that the added subtree "inherits" the default namespace of the target node:
the [[DefaultURI (XmlDoc/XmlNode function)|DefaultURI]] function
is used to provide a value for the <tt>DefaultURI</tt> argument so that
the added subtree "inherits" the default namespace of the target node:
<p class="code">%tar = %outdoc:AddElement('target', , 'urn:target')
<p class="code">%tar = %outdoc:AddElement('target', , 'urn:target')
%src = %inDoc:AddElement('sourceWrap', , 'urn:source')
%src = %inDoc:AddElement('sourceWrap', , 'urn:source')
Line 173: Line 151:
</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">Nr</var> is neither the <var>Root</var> nor an <var>Element</var> node.
<li>The <var class="term">nr</var> object is neither the <var>Root</var> nor an <var>Element</var> node.
<li><var class="term">SourceSubtreeNod</var> is a <var>Root</var> node.
 
<li><var class="term">Nr</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>Any of the errors that would occur based on insertion of the top <var>subtree</var> node at the given target parent, for example, insertion of a duplicate attribute, or insertion of an adjacent Text node when the AdjacentText property setting is <code>Disallow</code>.  See the "Add" function corresponding to the type of the <var>subtree</var> node (for those examples just cited, [[AddAttribute (XmlNode function)|AddAttribute]] and [[AddText (XmlNode function)|AddText]], respectively).  
<li><var class="term">nr</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 (XmlDoc property)|Namespace]]</var> settings.
 
<li>Any of the errors that would occur based on insertion of the top subtree node at the given target parent, for example, insertion of a duplicate attribute, or insertion of an adjacent Text node when the <var>[[AdjacentText (XmlDoc property)|AdjacentText]]</var> property value is <var>Disallow</var>.  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 185: Line 169:
==See also==
==See also==
<ul>
<ul>
<li><var>[[InsertSubtreeBefore_(XmlNode_function)|InsertSubtreeBefore]]</var> also copies a <var>subtree</var>.  <var>AddSubtree</var> copies a <var>subtree</var> as the last child of the node pointed to by the
<li><var>[[InsertSubtreeBefore_(XmlNode_function)|InsertSubtreeBefore]]</var> also copies a subtree.  <var>AddSubtree</var> copies a subtree as the last child of the node pointed to by the
method object; <var>InsertSubtreeBefore</var> copies a <var>subtree</var> as the immediately preceding sibling of the node pointed to by the method object.
method object; <var>InsertSubtreeBefore</var> copies a subtree as the immediately preceding sibling of the node pointed to by the method object.
</ul>
</ul>
{{Template:XmlDoc/XmlNode:AddSubtree footer}}
{{Template:XmlDoc/XmlNode:AddSubtree footer}}

Latest revision as of 16:55, 4 September 2015

Copy subtree to XmlDoc Root or to Element XmlNode (XmlDoc and XmlNode classes)

[Requires Janus SOAP]

The AddSubtree callable function copies a subtree of an XmlDoc to the method parent node, where it becomes the last child of that node. 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

[%nod =] nr:AddSubtree( sourceSubtreeNode, [DefaultURI= unicode])

Syntax terms

%nod If specified, an XmlNode that is set to point to the top of the subtree that is added.
nr An XmlDoc or XmlNode that refers to the Root or Element node parent of the added subtree.
sourceSubtreeNode XmlNode that points to the non-Root node that is the top of the subtree to be copied.
DefaultURI This optional, name required parameter is a Unicode string that controls the URI of the default namespace of some of the Element nodes of the added subtree.

If a DefaultURI argument is specified, its value becomes the URI that is used for all unprefixed elements in the added subtree that are not already in the scope of a default namespace declaration within the added subtree. For more details, see the Usage notes and Examples sections, below.

Usage notes

  • Since the return value of AddSubtree 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.
  • Processing of 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 added adjacent to (that is, as a sibling of) another Text node, unless the AdjacentText property value 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 copied to a target XmlDoc in which AllowNull=False.
  • If the DefaultURI argument is specified, the value of the Namespace property of the method object of AddSubtree must be On.
  • If the DefaultURI argument is not specified, each node added by AddSubtree retains the URI value it had in the source XmlDoc. See example 2 below.

    If a DefaultURI argument is present, its value is used as the URI of any unprefixed node whose namespace declaration is located at a source XmlDoc element that is not part of the added subtree. See example 3 below.

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

  • You can apply the DefaultURI function to the AddSubtree method object to cause an added subtree to "inherit" the default namespace of that node. See example 5 below.

Examples

  1. In the following example, the top-level Element (and its descendants) from XmlDoc %doc2 are copied as the "body" of a SOAP request document in %doc1:

    begin %doc1 is object xmlDoc %doc1 = new %n1 is object xmlNode %n2 is object xmlNode %n1 = %doc1:addElement('SOAP-ENV:Envelope', , - 'http://schemas.xmlsoap.org/soap/envelope/') %n1 = %n1:addElement('SOAP-ENV:Body') %doc2 is object xmlDoc %doc2 = new %doc2:loadXml('<top><a><b>05</b></a></top>') %n2 = %doc2:selectSingleNode('top') %n1:addSubtree(%n2) %doc1:print end

    Here is "doc1" before the subtree is added:

    <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Body/> </SOAP-ENV:Envelope>

    Here is "doc1" after the subtree is added:

    <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Body> <top> <a> <b>05</b> </a> </top> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

  2. In the following request, a source node is added to a target 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 %tar is object xmlNode %src is object xmlNode %tar = %outDoc:addElement('target', , 'urn:target') %src = %inDoc:addElement('sourceWrap', , 'urn:source') %src = %src:addElement('source') %tar:addSubtree(%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: <target xmlns="urn:target"> <source xmlns="urn:source"/> </target>

    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 AddSubtree as in the next example.

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

    %tar = %outDoc:AddElement('target', , 'urn:target') %src = %inDoc:AddElement('sourceWrap', , 'urn:source') %src = %src:AddElement('source') %tar:AddSubtree(%src, DefaultURI='urn:target') %tar:Print

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

    <target xmlns="urn:target"> <source/> </target>

    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 added subtree:

    %tar = %outDoc:AddElement('target', , 'urn:target') %src = %inDoc:addElement('source', , 'urn:source') %tar:addSubtree(%src, DefaultURI='urn:target') %tar:print

    The result is:

    <target xmlns="urn:target"> <source xmlns="urn:source"/> </target>

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

    %tar = %outdoc:AddElement('target', , 'urn:target') %src = %inDoc:AddElement('sourceWrap', , 'urn:source') %src = %src:AddElement('source') %tar:AddSubtree(%src, DefaultURI=%tar:DefaultURI) %tar:Print

    The result is:

    <target xmlns="urn:target"> <source/> </target>

Request-cancellation errors

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

  • The nr object is neither the Root nor an Element node.
  • The sourceSubtreeNode argument is a Root node.
  • nr is the same as, or a descendant of, sourceSubtreeNode.
  • Source and target XmlDocs have different Namespace settings.
  • Any of the errors that would occur based on insertion of the top subtree node at the given target parent, for example, insertion of a duplicate attribute, or insertion of an adjacent Text node when the AdjacentText property value 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

  • InsertSubtreeBefore also copies a subtree. AddSubtree copies a subtree as the last child of the node pointed to by the method object; InsertSubtreeBefore copies a subtree as the immediately preceding sibling of the node pointed to by the method object.