AddSubtree (XmlDoc/XmlNode function)

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

[Requires Janus SOAP]

This 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.
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 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. This parameter is available as of Sirius Mods version 6.9.

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 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.
• 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 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 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 the example 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 the example 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 the example 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 the example 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

• Nr is neither the Root nor an Element 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 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 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

• ?? reftxt=InsertSubtreeBefore refid=inssubt. 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.