InsertSubtreeBefore (XmlNode function): Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (1 revision)
 
(10 intermediate revisions by 5 users not shown)
Line 1: Line 1:
{{Template:XmlNode:InsertSubtreeBefore subtitle}}
{{Template:XmlNode:InsertSubtreeBefore subtitle}}
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.


This 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.
==Syntax==
==Syntax==
{{Template:XmlNode:InsertSubtreeBefore syntax}}
{{Template:XmlNode:InsertSubtreeBefore syntax}}
Line 11: 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 subtree 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 subtree 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 subtree 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 and NameRequired <var>Unicode</var> string parameter that controls the URI of the default namespace of some of the Element nodes of the inserted subtree.
<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>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>
If a <tt>DefaultURI</tt> 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.
<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>
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.</td></tr>
 
</table>
</table>


==Usage notes==
==Usage notes==
<ul>
<ul>
<li>Since the return value of <var>InsertSubtreeBefore</var> is frequently not needed,
<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.
you may want to Call 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
<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:
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
<tt>On</tt> or both <tt>Off</tt>.
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 Namespace=None and the target <var>XmlDoc</var> has
<li>The source <var>XmlDoc</var> has <code>Namespace=None</code> and the target <var>XmlDoc</var> has <code>Namespace=Ignore</code>.
Namespace=Ignore.
<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.
<li>The source <var>XmlDoc</var> has Namespace=None and the target <var>XmlDoc</var> has
Namespace=On, if the <tt>DefaultURI</tt> argument is specified.
</ul>
</ul>
<li>There is a very small "one-time" processing cost
<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).
if certain XPath operations are performed after using this method, because
<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>.
Insert-Before methods are guaranteed to add a node out of document order.
<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>.
In general, processing an <var>XmlDoc</var> is likely to be more efficient if
<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>.
you add nodes in document order (that is, top-to-bottom, left-to-right).
<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>.
<li>A subtree that is a Text node may not be inserted adjacent to
See [[#InsertSubtreeBeforeExample2|Example 2]].
(that is, as a sibling of) another Text node, unless the [[AdjacentText (XmlDoc property)|AdjacentText]] property setting is <tt>Combine</tt>.
<p>
<li>A node that is added to an <var>XmlDoc</var> whose [[AllowNull (XmlDoc property)|AllowNull]] property setting is <tt>True</tt>,
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>
may not later be the source node of a subtree to be inserted
<p>
into a target <var>XmlDoc</var> in which <tt>AllowNull=False</tt>.
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>If the <tt>DefaultURI</tt> argument is specified, the value of the Namespace
<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]].
property of the method object of <var>InsertSubtreeBefore</var> must be <tt>On</tt>.
<li>If the <tt>DefaultURI</tt> 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..
 
If a <tt>DefaultURI</tt> 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..
 
The namespace URI of an unprefixed
node is preserved if the namespace declaration is within the inserted subtree,
whether the <tt>DefaultURI</tt> argument is specified or not.
See example [[??]] refid=insub4..
<li>You can apply the [[DefaultURI (XmlDoc/XmlNode function)|DefaultURI]] 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..
</ul>
</ul>


==Examples==
==Examples==
<ol>
<ol>
<li>In the following example,
<li><div id="InsertSubtreeBeforeExample1"></div>In the following example, a subtree (node "c") is inserted before node "a":
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]]   -
Call %doc:LoadXml   -
      ('<top><a><nowiki><b>05</b></nowiki></a><c><d att="value"></d></c></top>')
  ('<top><a><nowiki><b>05</b></nowiki></a><c><d att="value"></d></c></top>')
  %n1 is object xmlNode
%n1 is Object XmlNode
  %n2 is object xmlNode
%n2 is Object XmlNode
  %n1 = %doc:[[SelectSingleNode_(XmlDoc/XmlNode_function)|selectSingleNode]]('top/c')
%n1 = %doc:SelectSingleNode('top/c')
  %n2 = %doc:selectSingleNode('top/a')
%n2 = %doc:SelectSingleNode('top/a')
  call %n2:insertSubtreeBefore(%n1)
Call %n2:InsertSubtreeBefore(%n1)
  call %doc:[[Print_(XmlDoc/XmlNode_subroutine)|print]]('top')
Call %doc:Print('top')
end
End
</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 100: Line 66:
</top>
</top>
</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 114: Line 79:
</top>
</top>
</p>
</p>
<li>In the following request, a source node is inserted before a
<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>:
sibling node,
<p class="code">begin
and the source node retains the URI value it had in the source <var>XmlDoc</var>:
  %outDoc is object xmlDoc auto new
<p class="code">Begin
  %inDoc is object xmlDoc auto new
%outDoc is Object XmlDoc Auto New
  %top is object xmlNode
%inDoc is Object XmlDoc Auto New
  %src is object xmlNode
%top is Object XmlNode
  %sib is object xmlNode
%src is Object XmlNode
%sib is Object XmlNode


%top = %outDoc:AddElement('top', , 'urn:top')
  %top = %outDoc:[[AddElement_(XmlDoc/XmlNode_function)|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)
  %sib:InsertSubtreeBefore(%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="output">Source document:
<sourceWrap xmlns="urn:source">
<sourceWrap xmlns="urn:source">
   <source/>
   <source/>
Line 149: Line 111:
</top>
</top>
</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 default namespace URI in scope at the <tt>source</tt> element (child
The result is different if a <var>DefaultURI</var> argument is specified for <var>InsertSubtreeBefore</var> as in the next example.
of <tt>sourceWrap</tt>) is <tt>urn:source</tt>, and that is retained
<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>:
when the node is copied to its target.
<p class="code">%top = %outDoc:addElement('top', , 'urn:top')
 
%sib = %top:addElement('sibling')
The result is different if a <tt>DefaultURI</tt> argument is specified for
%src = %inDoc:addElement('sourceWrap', , 'urn:source')
<var>InsertSubtreeBefore</var> as in the next example.
%src = %src:addElement('source')
<li>in the following request fragment:
%sib:insertSubtreeBefore(%src, defaultURI='urn:top')
a source node is copied to a target using a <tt>DefaultURI</tt> specification,
%top:print
and the source node retains the URI value it had in the source <var>XmlDoc</var>:
<p class="code">%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
</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 175: 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 194: 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 216: 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><i>Nod</i> is the Root node.
<li>Object <var class="term">nod</var> is the <var>Root</var> node.
<li><i>sourceSubtreeNod</i> is a Root node.
 
<li><i>Nr</i> is the same as, or a descendant of,
<li>The <var class="term">sourceSubtreeNode</var> argument is a <var>Root</var> node.
<i>sourceSubtreeNod</i>.
 
<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>Any of the errors which would occur based on insertion of the
 
top subtree
<li>Source and target <var>XmlDoc</var>s have different <var>Namespace</var> settings.
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 Text node before a target Text node,
<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>
when the AdjacentText property setting is <tt>Disallow</tt>
<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 Text node before a
target sibling that follows a Text node,
when the AdjacentText property setting is <tt>Disallow</tt>
</ul>
</ul>
See the "Add" function corresponding to the type of the
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).
subtree node (for those examples just cited,
 
[[AddAttribute (XmlNode function)|AddAttribute]] and
[[AddText (XmlNode function)|AddText]], respectively).
<li>Insufficient free space exists in CCATEMP.
<li>Insufficient free space exists in CCATEMP.
</ul>
</ul>


==See also==
==See also==
{{Template:XmlNode:InsertSubtreeBefore footer}}
<ul>
<ul>
<li>[[AddSubtree (XmlDoc/XmlNode function)|AddSubtree]]
<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.
also copies a Subtree node.
<li>For hints about inserting a node ''after'' a sibling node, see the <var>InsertElementBefore</var> [[InsertElementBefore_(XmlNode_function)#Examples|"Examples"]] section.
<var>InsertSubtreeBefore</var> 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.
<li>For hints about inserting a node ''after'' a sibling node, see
the "Example" section in [[InsertElementBefore (XmlNode function)|InsertElementBefore]].
</ul>
</ul>
{{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.