InsertSubtreeBefore (XmlNode function)

Insert copy of subtree before this node (XmlNode class)

[Requires Janus SOAP]

This 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

%nod	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=string	Optional and NameRequired 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 properties 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 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 value 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 ?? refid=insub2.. 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 ?? refid=insub3.. 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 ?? refid=insub4..
• 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 ?? refid=insub5..

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>05</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> 05 </a> <c> <d att="value"/> </c> </top>

   Here is the document after the subtree is inserted:

   <top> <c> <d att="value"/> </c> <a> 05 </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

• Nod is the Root node.
• sourceSubtreeNod is a Root node.
• Nr is the same as, or a descendant of, sourceSubtreeNod.
• 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

XmlDoc class XmlNode class XmlNodelist class	List of XmlDoc methods List of XmlNode methods List of XmlNodelist methods List of XmlDoc API methods	XmlDoc methods syntax XmlNode methods syntax XmlNodelist methods syntax
Notation conventions for methods

• 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 "Example" section in InsertElementBefore.