AddElement (XmlDoc/XmlNode function): Difference between revisions

From m204wiki
Jump to navigation Jump to search
mNo edit summary
 
(16 intermediate revisions by 5 users not shown)
Line 1: Line 1:
{{Template:XmlDoc/XmlNode:AddElement subtitle}}
{{Template:XmlDoc/XmlNode:AddElement subtitle}}
This [[Notation_conventions_for_methods#Callable_methods|callable]] function adds an [[XmlDoc API#XmlDoc node types|Element node]] as the last child of the <var>Root</var> node or <var>Element</var> node referenced by the method object.  <var>AddElement</var> also lets you add a <var>Text</var> node as the child of the added <var>Element</var>, and lets you specify the namespace URI for the added element.


This callable function adds an Element node as the last child of the Root node
or Element node referenced by the method object.
<var>AddElement</var> also lets you add a Text node as the child of the added
Element, and lets you specify the namespace URI for the added element.
==Syntax==
==Syntax==
{{Template:XmlDoc/XmlNode:AddElement syntax}}
{{Template:XmlDoc/XmlNode:AddElement syntax}}
===Syntax terms===
===Syntax terms===
<table class="syntaxTable">
<table class="syntaxTable">
<tr><th>%nod</th>
<tr><th nowrap>%nod</th>
<td>If specified, an <var>XmlNode</var> that is set to point to the Element node that is added. </td></tr>
<td>If specified, an <var>XmlNode</var> that is set to point to the Element node 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 Root or Element node parent of the added Element. </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 <var>Element</var>. </td></tr>
<tr><th>name</th>
<tr><th>name</th>
<td>The name of the added Element; if prefixed, the prefix must be declared, or a <var class="term">uri</var> argument must be provided.
<td>The name of the added <var>Element</var>; if prefixed, the prefix must be declared, or a <var class="term">uri</var> argument must be provided.


Multiple Elements with the same name may be added to a single parent Element.
Multiple Elements with the same name may be added to a single parent Element.
The name must conform to the XML syntax rules for an element name; the maximum length of each of the prefix part and local name part is 127 characters (100 characters prior to version 7.7 of [[Janus SOAP]]). </td></tr>
 
The name must conform to the XML syntax rules for an element name; the maximum length of each of the prefix part and local name part is 300 characters (127 prior to version 7.9, and 100 characters prior to Version 7.7). </td></tr>
<tr><th>value</th>
<tr><th>value</th>
<td>This optional argument is the content of a Text node that is added as a child of the added element. This content is stored without any normalization, entity substitution, etc.
<td>This optional argument is the content of a <var>Text</var> node that is added as a child of the added element. This content is stored without any normalization, entity substitution, etc.


Since Text nodes cannot contain the null string, this argument is ignored if it is the null string. </td></tr>
Since <var>Text</var> nodes cannot contain the null string, this argument is ignored if it is the null string. </td></tr>
<tr><th>uri</th>
<tr><th>uri</th>
<td>This optional argument is the URI of the added element's namespace, or it is an explicit disabling of any namespace association for the element. See "Usage Notes," below.</td></tr>
<td>This optional argument is the URI of the added element's namespace, or it is an explicit disabling of any namespace association for the element. See [[AddElement_(XmlDoc/XmlNode_function)#Usage_notes|"Usage Notes"]], below.</td></tr>
</table>
</table>


==Usage notes==
==Usage notes==
<ul>
<ul>
<li>If a <i>URI</i> argument is specified, the <var>XmlDoc</var>'s Namespace property
<li>If a <var class="term">uri</var> argument is specified, the <var>XmlDoc</var>'s <var>Namespace</var> property must be <code>On</code>, and <var class="term">uri</var> must either
must be <tt>On</tt>, and <i>URI</i> must either
be the null string, or it must have the format of an absolute URI. The effect depends on whether the <var class="term">name</var> value includes a prefix:
be the null string, or it must have the format of an absolute URI.
The effect depends on whether the <i>name</i> value includes
a prefix:
<ul>
<ul>
<li>If <i>name</i> has a prefix, <i>URI</i> must '''not''' be
<li>If <var class="term">name</var> has a prefix, <var class="term">uri</var> must '''not''' be the null string, and <var class="term">uri</var> is the declared namespace URI associated with that prefix and added element.
the null string, and <i>URI</i> is the declared namespace URI
<li>If <var class="term">name</var> does not have a prefix:
associated with that prefix and added element.
<li>If <i>name</i> does not have a prefix:
<ul>
<ul>
<li>If <i>URI</i> is the null string,
<li>If <var class="term">uri</var> is the null string, the added element does not have a default namespace. Any in-scope default namespace the added element might have inherited,
the added element does not have a default namespace.
Any in-scope default namespace the added element might have inherited,
is not inherited.
is not inherited.
<li>If <i>URI</i> is '''not''' the null string,
<li>If <var class="term">uri</var> is '''not''' the null string, the added element has <var class="term">uri</var> as the default namespace.
the added element has <i>URI</i> as the default namespace.
</ul>
</ul>
</ul>
</ul>
 
If a non-null string <var class="term">uri</var> argument is provided, and the namespace declaration resulting from it is not in scope for the added element, then a namespace declaration is added at that element.
If a non-null string <i>URI</i> argument is provided, and the namespace
<li>If the <var class="term">uri</var> argument is '''not''' present, the added element's namespace is determined by the prefix and in-scope declarations:
declaration resulting from it is not in scope for the added element, then
a namespace declaration is added at that element.
<li>If the <i>URI</i> argument is '''not''' present, the added element's namespace
is determined by the prefix and in-scope declarations:
<ul>
<ul>
<li>If the <i>name</i> is prefixed, the namespace is given by the
<li>If the <var class="term">name</var> is prefixed, the namespace is given by the in-scope declaration of the prefix.
in-scope declaration of the prefix.
<li>If the <var class="term">name</var> has no prefix, the namespace is the default namespace, if any, in scope. If there is no default namespace in scope, the added element has no namespace.
<li>If the <i>name</i> has no prefix, the namespace is
the default namespace, if any, in scope.
If there is no default namespace in scope, the added element has
no namespace.
</ul>
</ul>
<li>As of ''Sirius Mods'' version 7.3, the <var>AddElement</var> arguments may
<li>As of <var class="product">[[Sirius Mods|Sirius Mods]]</var> Version 7.3, the <var>AddElement</var> arguments may include only non-null EBCDIC characters that translate to Unicode.  As of <var class="product">Sirius Mods</var> Version 7.6, these argument strings are <var>Unicode</var> or are converted to <var>Unicode</var>.
include only non-null EBCDIC characters that translate to <var>Unicode</var>.
As of ''Sirius Mods'' version 7.6, these argument strings are <var>Unicode</var> or are
converted to <var>Unicode</var>.


For more information about the effects of this version 7.6
For more information about the effects of this Version 7.6 change, see [[XmlDoc API#Strings and Unicode with the XmlDoc API|"Strings and Unicode with the XmlDoc API"]]. For a Unicode-specific <var>Add Element</var> example, see [[#Adding characters that are represented by character references|"Adding characters that are represented by character references"]].
change, see [[Strings and Unicode]].
<li>When the return value of <var>AddElement</var> is not needed, you may want to <var>[[Notation_conventions_for_methods#Callable_methods|Call]]</var> it instead of saving its return value; the return value is typically needed only to add attributes or non-Text children of the Element.
For a <var>Unicode</var>-specific Add Element example, see
<li>Processing of an <var>XmlDoc</var> is likely to be more efficient if you add nodes in document
item [[??]] refid=addunic..
<li>When the return value of <var>AddElement</var> is not needed,
you may want to Call it instead of saving its return value;
the return value is typically needed only
to add attributes or non-Text children of the Element.
<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).
order (that is, top-to-bottom, left-to-right).
</ul>
</ul>


==Examples==
==Examples==
====Simple Element additions====
<ol>
<ol>
<li>In the following example, an Element node is added as the last child
<li>In the following example, an <var>Element</var> node is added as the last child (that is, located after element "b") of element "a":
(that is, located after element "b") of element "a":
<p class="code">begin
<p class="code">Begin
  %doc is object xmlDoc
%doc is Object XmlDoc
  %doc = new
%doc = New
  %doc:[[LoadXml_(XmlDoc/XmlNode_function)|loadXml]]<nowiki>('<top><a><b>05</b></a></top>')</nowiki>
%doc:LoadXml<nowiki>('<top><a><b>05</b></a></top>')</nowiki>
  %n1 is object xmlNode
%n1 is Object XmlNode
  %n1 = %doc:[[SelectSingleNode_(XmlDoc/XmlNode_function)|selectSingleNode]]('top/a')
%n1 = %doc:SelectSingleNode('top/a')
  %n1:addElement('c', '505')
%n1:AddElement('c', '505')
  %doc:Print('top')
%doc:Print('top')
end
End
</p>
</p>


Line 103: Line 75:
</p>
</p>


<li>The following statements add an
<li>The following statements add an <var>Element</var> node with a <var>Text</var> child and then add an <var>Attribute</var> node to the <var>Element</var>:
Element node with a Text child and then add an Attribute node to
the Element:
<p class="code">%n1 = %n1:AddElement('weight', '10')
<p class="code">%n1 = %n1:AddElement('weight', '10')
%n1:AddAttribute('unit', 'gram')
%n1:AddAttribute('unit', 'gram')
</p>
</p>
<li>For a ''Sirius Mods'' version 7.6 or higher request, the following example
</ol>
shows techniques for adding an Element node
====Adding characters that are represented by character references====
that contains a <var>Unicode</var> "copyright" character, and it also
For a <var class="product">Sirius Mods</var> Version 7.6 or higher request, the following example shows techniques for adding an <var>Element</var> node that contains a Unicode "copyright" character, and it also includes a statement to add a "trademark" character.
includes a statement to add a "trademark" character.


The Add Element statements use a hex character reference or an entity reference
The <var>AddElement</var> statements use a hex character reference or an entity reference to represent the copyright character, and they use a character reference for the trademark. Those references must first be decoded so <var>AddElement</var> will interpret the value string as a single character and not as several individual characters.
to represent the copyright character, and they use a character reference for
the trademark.
Those references must first be decoded so Add Element will interpret the value
string as a single character and not as several individual characters.
<ul>
<ul>
<li>The first <var>AddElement</var> invocation uses the EbcdicTo<var>Unicode</var> function
<li>The first <var>AddElement</var> invocation uses the <var>[[EbcdicToUnicode (String function)|EbcdicToUnicode]]</var> function and parameter setting that decode and convert a character reference to <var>Unicode</var>.
([[??]] refid=fue2u.) and parameter setting that
 
decode and convert a character reference to <var>Unicode</var>.
<li>The second <var>AddElement</var> invocation uses the [[U (String function)|U]] function, which is a compile-time equivalent of <var>EbcdicToUnicode(CharacterDecode=True)</var>.
<li>The second <var>AddElement</var> invocation uses the U function ([[??]] refid=umeth.),
 
which is a compile-time equivalent of EbcdicTo<var>Unicode</var>(CharacterDecode=True).
<li>The third and fourth <var>AddElement</var> invocations show what happens when character decoding is not specified; the fourth also illustrates that EBCDIC to Unicode conversion is automatically performed as needed. The value string is converted character by character, and the ampersand (<code>&amp;</code>) is translated on output to a character reference (<code>&amp;amp;</code>).
<li>The third and fourth
 
<var>AddElement</var> invocations show what happens when character decoding is not
<li>The fifth <var>AddElement</var> invocation uses the <var>U</var> function to decode and convert to <var>Unicode</var> the [[XML processing in Janus SOAP#Entity references|entity reference]] for the copyright character.
specified; the fourth
 
also illustrates that EBCDIC to <var>Unicode</var> conversion is
<li>The sixth <var>AddElement</var> invocation uses the <var>U</var> function to decode and convert to <var>Unicode</var> the character reference for the trademark character. Since this character does not translate to an EBCDIC character, the [[Print_(XmlDoc/XmlNode_subroutine)|Print]] method displays its XML hexadecimal character reference.
automatically performed as needed.
The value string is converted character by character, and the
ampersand (<tt>&</tt>) is translated on output to a character
reference (<tt>&amp;amp;</tt>).
<li>The fifth <var>AddElement</var> invocation uses the U function to
decode and convert to <var>Unicode</var> the entity reference ([[??]] refid=entrefs.)
for the copyright character.
<li>The sixth <var>AddElement</var> invocation uses the U function to
decode and convert to <var>Unicode</var> the character reference for the trademark character.
Since this character does not translate to an EBCDIC character,
the Print method displays its XML hexadecimal character reference.
</ul>
</ul>
<p class="code">Begin
<p class="code">begin
%doc is Object XmlDoc Auto New
  %doc is object xmlDoc auto new
%doc:LoadXml('<top/>')
  %doc:[[LoadXml_(XmlDoc/XmlNode_function)|loadXml]]('<top/>')
%n is Object XmlNode
  %n is object XmlNode


%n = %doc:SelectSingleNode('top')
  %n = %doc:[[SelectSingleNode_(XmlDoc/XmlNode_function)|selectSingleNode]]('top')
%n:AddElement('a1', -
  %n:addElement('a1', -
  '&amp;#xA9;':EbcdicToUnicode(CharacterDecode=True))
      '&amp;#xA9;':[[EbcdicToUnicode (String function)|ebcdicToUnicode]](CharacterDecode=True))
%n:AddElement('a2', '&amp;#xA9;':U)
  %n:addElement('a2', '&amp;#xA9;':U)
%n:AddElement('a3', '&amp;#xA9;':EbcdicToUnicode
  %n:addElement('a3', '&amp;amp;#xA9;':EbcdicToUnicode)
%n:AddElement('a4', '&amp;#xA9;')
  %n:addElement('a4', '&amp;#xA9;')
%n:AddElement('a5', '&amp;copy;':U)
  %n:addElement('a5', '&amp;copy;':U)
%n:AddElement('a6', '&amp;#x2122;':U)
  %n:addElement('a6', '&amp;#x2122;':U)


%doc:Print
  %doc:print
End
end
</p>
</p>


The example result follows:
The example result follows:
<p class="output"><top>
<p class="output"><top>
   <a1>&copy.</a1>
   <a1>©</a1>            
   <a2>&copy.</a2>
   <a2>©</a2>            
   <a3>&amp;amp;#xA9;</a3>
   <a3>&amp;amp;amp;#xA9;</a3>
   <a4>&amp;amp;#xA9;</a4>
   <a4>&amp;amp;#xA9;</a4>  
   <a5>&copy.</a5>
   <a5>©</a5>            
   <a6>&amp;#x2122;</a6>
   <a6>&amp;#x2122;</a6>    
</top>
</top>
</p>
</p>
<br>
 
<li>The following example contains several <var>AddElement</var> invocations and
====Working with URIs====
shows the effects of the <i>URI</i> argument:
The following example contains several <var>AddElement</var> invocations and shows the effects of the <var class="term">uri</var> argument:
<ul>
<ul>
<li>An initial invocation of <var>AddElement</var> adds the first element of the document.
<li>An initial invocation of <var>AddElement</var> adds the first element of the document. The method object in this case is an <var>XmlDoc</var>. This invocation fails if the document already contains an element node.
The method object in this case is an <var>XmlDoc</var>.
<li>A second <var>AddElement</var> invocation, this time with a node as the method object, adds an element as the child of the first element. This second element has a prefixed name but no <var class="term">uri</var> value. Since the prefix matches that of the parent element, the second element receives the namespace URI of the first.
This invocation fails if the document already contains an element node.
<li>A third <var>AddElement</var> invocation adds an element (to the first). Although the <var>AddElement</var> arguments include no name prefix and no <var class="term">uri</var>, the added element may still be associated with a namespace &mdash; the default namespace of its nearest ancestor. In this case, however, no default namespace is in scope (the parent's namespace is associated with its prefix), so this child has no namespace association at all.
<li>A second <var>AddElement</var> invocation, this time with a node as the method object,
<li>A fourth <var>AddElement</var> invocation adds an element (to the first). The function arguments specify a non-prefixed name and also a <var class="term">uri</var> value. This new URI is the added element's default namespace.
adds an element as the child of the first element.
<li>A fifth <var>AddElement</var> invocation adds an element to the element added by the previous <var>AddElement</var>. The function arguments include no name prefix and no <var class="term">uri</var> value,
This second element has a prefixed name
so the added element receives the in-scope default namespace which, in this case, is also the URI of its parent.
but no <i>URI</i> value.
Since the prefix matches that of the parent element,
the second element receives the namespace URI of the first.
<li>A third <var>AddElement</var> invocation adds an element (to the first).
Although the <var>AddElement</var> arguments include no name prefix and no <i>URI</i>,
the added element may still be associated with
a namespace &mdash; the default namespace of its nearest ancestor.
In this case, however,
no default namespace is in scope
(the parent's namespace is associated with its prefix),
so this child has no namespace association at all.
<li>A fourth <var>AddElement</var> invocation adds an element (to the first).
The function arguments specify a non-prefixed name
and also a <i>URI</i> value.
This new URI is the added element's default namespace.
<li>A fifth <var>AddElement</var> invocation adds an element to the element added
by the previous <var>AddElement</var>.
The function arguments include no name prefix and no <i>URI</i> value,
so the added element receives
the in-scope default namespace which, in this case, is also
the URI of its parent.
</ul>
</ul>
<p class="code">Begin
<p class="code"><nowiki>begin
%doc is Object XmlDoc
  %doc is object xmlDoc
%doc = New
  %doc = new
%n1 is Object XmlNode
  %n1 is object xmlNode
%n2 is Object XmlNode
  %n2 is object xmlNode
%n3 is Object XmlNode
  %n3 is object xmlNode
%n4 is Object XmlNode
  %n4 is object xmlNode
%n5 is Object XmlNode
  %n5 is object xmlNode
%n1 = %doc:AddElement('SOAP-ENV:Envelope',, -
  %n1 = %doc:addElement('SOAP-ENV:Envelope',, -
  'http://schemas.xmlsoap.org/soap/envelope/')
      'http://schemas.xmlsoap.org/soap/envelope/')
%n2 = %n1:AddElement('SOAP-ENV:Stuff2')
  %n2 = %n1:AddElement('SOAP-ENV:Stuff2')
%n3 = %n1:AddElement('Stuff3')
  %n3 = %n1:AddElement('Stuff3')
%n4 = %n1:AddElement('Stuff4', ,  -
  %n4 = %n1:AddElement('Stuff4', ,  -
  'http://sirius-software.com')
      'http://sirius-software.com')
%n5 = %n4:AddElement('Stuff5')
  %n5 = %n4:AddElement('Stuff5')
%doc:Print
  %doc:Print
Print 'Stuff2 URI is ' %n2:URI
  print 'Stuff2 URI is ' %n2:URI
Print 'Stuff3 URI is ' %n3:URI
  print 'Stuff3 URI is ' %n3:URI
Print 'Stuff4 URI is ' %n4:URI
  print 'Stuff4 URI is ' %n4:URI
Print 'Stuff5 URI is ' %n5:URI
  print 'Stuff5 URI is ' %n5:URI
End
end
</p>
</nowiki></p>


The example result follows:
The example result follows:
<p class="output"><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:Stuff2/>
   <SOAP-ENV:Stuff2/>
   <Stuff3/>
   <Stuff3/>
Line 236: Line 169:
Stuff4 URI is http://sirius-software.com
Stuff4 URI is http://sirius-software.com
Stuff5 URI is http://sirius-software.com
Stuff5 URI is http://sirius-software.com
</p>
</nowiki></p>
</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>Nr</i> is neither the Root nor an Element node.
<li>The <var class="term">nr</var> object is neither the <var>Root</var> nor an <var>Element</var> node.
<li><i>Nr</i> is the Root node which already has an Element child.
<li><var class="term">nr</var> is the <var>Root</var> node which already has an <var>Element</var>child.
<li>Argument <i>name</i> violates the rules for an XML element name.
<li>The <var class="term">name</var> argument violates the rules for an XML element name.
<li><i>Name</i> is prefixed, but the <var>XmlDoc</var> Namespace property
<li><var class="term">name</var> is prefixed, but the <var>XmlDoc</var> <var>[[Namespace (XmlDoc property)|Namespace]]</var> property value is <var>None</var>.
is None.
<li><var class="term">name</var> prefixed and <var>Namespace</var> value is <var>On</var>, but <var class="term">uri</var> missing and no declaration for prefix in scope.
<li><i>Name</i> prefixed and Namespace On, but URI missing and no
<li>The <var class="term">value</var> argument violates the rules for an XML element value (that is, it contains an invalid character).  
declaration for prefix in scope.
Note that as of <var class="product">Sirius Mods</var> Version 7.6, this check can no longer be bypassed using the <var>[[InvalidChar_(XmlDoc_property)|InvalidChar]]</var> method &mdash; see the <var>InvalidChar</var> [[InvalidChar (XmlDoc property)#Usage notes|"Usage notes"]].
<li><i>Value</i> violates the rules for an
<li>The <var class="term">uri</var> argument is invalid.
XML element value (that is, it contains an invalid character).
<li><var class="term">uri</var> is present, but the <var>Namespace</var> value is not <var>On</var>, or, <var class="term">uri</var> is the null string and <var class="term">name</var> is prefixed.
Note that as of
''Sirius Mods'' version 7.6, this check can no longer be bypassed using the InvalidChar
method &mdash; see [[InvalidChar (XmlDoc property)#Usage notes|Usage Notes for the InvalidChar property]].
<li><i>URI</i> is invalid.
<li><i>URI</i> is present, but the
Namespace property is not <tt>On</tt>,
or, <i>URI</i> is the null string and <i>name</i> is prefixed.
<li>Insufficient free space exists in CCATEMP.
<li>Insufficient free space exists in CCATEMP.
</ul>
</ul>


==See also==
==See also==
{{Template:XmlDoc/XmlNode:AddElement footer}}
<ul>
<ul>
<li>For more information about
<li>For more information about namespace declarations, see [[XML processing in Janus SOAP#Names and namespaces|"Names and namespaces"]].
namespace declarations, see [[??]] refid=namsp..
<li>For more information about URIs, see [[XML processing in Janus SOAP#Uniform Resource Identifier syntax|"Uniform Resource Identifier syntax"]].
<li>For more information about URIs, see [[??]] refid=nsuri..
<li><var>[[InsertElementBefore (XmlNode function)|InsertElementBefore]]</var> also adds an <var>Element</var> node. <var>AddElement</var> adds an <var>Element</var> as the last child of the node pointed to by the
<li>[[InsertElementBefore (XmlNode function)|InsertElementBefore]] also adds an Element node.
method object; <var>InsertElementBefore</var> adds an <var>Element</var> as the immediately preceding sibling of the node pointed to by the method object.
<var>AddElement</var> adds an Element as the last child of the node pointed to by the
method object;
InsertElementBefore adds an Element as the immediately preceding
sibling of the node pointed to by the method object.
<li>These methods are useful for working with namespaces:
<li>These methods are useful for working with namespaces:
<ul>
<ul>
<li>[[AddNamespace (XmlNode subroutine)|AddNamespace]]
<li><var>[[AddNamespace (XmlNode subroutine)|AddNamespace]]</var>
<li>[[SelectionNamespace (XmlDoc property)|SelectionNamespace]]
<li><var>[[SelectionNamespace (XmlDoc property)|SelectionNamespace]]</var>
</ul>
</ul>
</ul>
</ul>
{{Template:XmlDoc/XmlNode:AddElement footer}}

Latest revision as of 21:00, 2 September 2015

Add Element to XmlDoc Root or to Element XmlNode (XmlDoc and XmlNode classes)

[Requires Janus SOAP]

This callable function adds an Element node as the last child of the Root node or Element node referenced by the method object. AddElement also lets you add a Text node as the child of the added Element, and lets you specify the namespace URI for the added element.

Syntax

[%nod =] nr:AddElement( name, [value], [uri])

Syntax terms

%nod If specified, an XmlNode that is set to point to the Element node that is added.
nr An XmlDoc or XmlNode that refers to the Root or Element node parent of the added Element.
name The name of the added Element; if prefixed, the prefix must be declared, or a uri argument must be provided.

Multiple Elements with the same name may be added to a single parent Element.

The name must conform to the XML syntax rules for an element name; the maximum length of each of the prefix part and local name part is 300 characters (127 prior to version 7.9, and 100 characters prior to Version 7.7).
value This optional argument is the content of a Text node that is added as a child of the added element. This content is stored without any normalization, entity substitution, etc. Since Text nodes cannot contain the null string, this argument is ignored if it is the null string.
uri This optional argument is the URI of the added element's namespace, or it is an explicit disabling of any namespace association for the element. See "Usage Notes", below.

Usage notes

  • If a uri argument is specified, the XmlDoc's Namespace property must be On, and uri must either be the null string, or it must have the format of an absolute URI. The effect depends on whether the name value includes a prefix:
    • If name has a prefix, uri must not be the null string, and uri is the declared namespace URI associated with that prefix and added element.
    • If name does not have a prefix:
      • If uri is the null string, the added element does not have a default namespace. Any in-scope default namespace the added element might have inherited, is not inherited.
      • If uri is not the null string, the added element has uri as the default namespace.

    If a non-null string uri argument is provided, and the namespace declaration resulting from it is not in scope for the added element, then a namespace declaration is added at that element.

  • If the uri argument is not present, the added element's namespace is determined by the prefix and in-scope declarations:
    • If the name is prefixed, the namespace is given by the in-scope declaration of the prefix.
    • If the name has no prefix, the namespace is the default namespace, if any, in scope. If there is no default namespace in scope, the added element has no namespace.
  • As of Sirius Mods Version 7.3, the AddElement arguments may include only non-null EBCDIC characters that translate to Unicode. As of Sirius Mods Version 7.6, these argument strings are Unicode or are converted to Unicode. For more information about the effects of this Version 7.6 change, see "Strings and Unicode with the XmlDoc API". For a Unicode-specific Add Element example, see "Adding characters that are represented by character references".
  • When the return value of AddElement is not needed, you may want to Call it instead of saving its return value; the return value is typically needed only to add attributes or non-Text children of the Element.
  • 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).

Examples

Simple Element additions

  1. In the following example, an Element node is added as the last child (that is, located after element "b") of element "a":

    begin %doc is object xmlDoc %doc = new %doc:loadXml('<top><a><b>05</b></a></top>') %n1 is object xmlNode %n1 = %doc:selectSingleNode('top/a') %n1:addElement('c', '505') %doc:Print('top') end

    The example result follows:

    <top> <a> <b>05</b> <c>505</c> </a> </top>

  2. The following statements add an Element node with a Text child and then add an Attribute node to the Element:

    %n1 = %n1:AddElement('weight', '10') %n1:AddAttribute('unit', 'gram')

Adding characters that are represented by character references

For a Sirius Mods Version 7.6 or higher request, the following example shows techniques for adding an Element node that contains a Unicode "copyright" character, and it also includes a statement to add a "trademark" character.

The AddElement statements use a hex character reference or an entity reference to represent the copyright character, and they use a character reference for the trademark. Those references must first be decoded so AddElement will interpret the value string as a single character and not as several individual characters.

  • The first AddElement invocation uses the EbcdicToUnicode function and parameter setting that decode and convert a character reference to Unicode.
  • The second AddElement invocation uses the U function, which is a compile-time equivalent of EbcdicToUnicode(CharacterDecode=True).
  • The third and fourth AddElement invocations show what happens when character decoding is not specified; the fourth also illustrates that EBCDIC to Unicode conversion is automatically performed as needed. The value string is converted character by character, and the ampersand (&) is translated on output to a character reference (&amp;).
  • The fifth AddElement invocation uses the U function to decode and convert to Unicode the entity reference for the copyright character.
  • The sixth AddElement invocation uses the U function to decode and convert to Unicode the character reference for the trademark character. Since this character does not translate to an EBCDIC character, the Print method displays its XML hexadecimal character reference.

begin %doc is object xmlDoc auto new %doc:loadXml('<top/>') %n is object XmlNode %n = %doc:selectSingleNode('top') %n:addElement('a1', - '&#xA9;':ebcdicToUnicode(CharacterDecode=True)) %n:addElement('a2', '&#xA9;':U) %n:addElement('a3', '&amp;#xA9;':EbcdicToUnicode) %n:addElement('a4', '&#xA9;') %n:addElement('a5', '&copy;':U) %n:addElement('a6', '&#x2122;':U) %doc:print end

The example result follows:

<top> <a1>©</a1> <a2>©</a2> <a3>&amp;amp;#xA9;</a3> <a4>&amp;#xA9;</a4> <a5>©</a5> <a6>&#x2122;</a6> </top>

Working with URIs

The following example contains several AddElement invocations and shows the effects of the uri argument:

  • An initial invocation of AddElement adds the first element of the document. The method object in this case is an XmlDoc. This invocation fails if the document already contains an element node.
  • A second AddElement invocation, this time with a node as the method object, adds an element as the child of the first element. This second element has a prefixed name but no uri value. Since the prefix matches that of the parent element, the second element receives the namespace URI of the first.
  • A third AddElement invocation adds an element (to the first). Although the AddElement arguments include no name prefix and no uri, the added element may still be associated with a namespace — the default namespace of its nearest ancestor. In this case, however, no default namespace is in scope (the parent's namespace is associated with its prefix), so this child has no namespace association at all.
  • A fourth AddElement invocation adds an element (to the first). The function arguments specify a non-prefixed name and also a uri value. This new URI is the added element's default namespace.
  • A fifth AddElement invocation adds an element to the element added by the previous AddElement. The function arguments include no name prefix and no uri value, so the added element receives the in-scope default namespace which, in this case, is also the URI of its parent.

begin %doc is object xmlDoc %doc = new %n1 is object xmlNode %n2 is object xmlNode %n3 is object xmlNode %n4 is object xmlNode %n5 is object xmlNode %n1 = %doc:addElement('SOAP-ENV:Envelope',, - 'http://schemas.xmlsoap.org/soap/envelope/') %n2 = %n1:AddElement('SOAP-ENV:Stuff2') %n3 = %n1:AddElement('Stuff3') %n4 = %n1:AddElement('Stuff4', , - 'http://sirius-software.com') %n5 = %n4:AddElement('Stuff5') %doc:Print print 'Stuff2 URI is ' %n2:URI print 'Stuff3 URI is ' %n3:URI print 'Stuff4 URI is ' %n4:URI print 'Stuff5 URI is ' %n5:URI end

The example result follows:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Stuff2/> <Stuff3/> <Stuff4 xmlns="http://sirius-software.com"> <Stuff5/> </Stuff4> </SOAP-ENV:Envelope> Stuff2 URI is http://schemas.xmlsoap.org/soap/envelope/ Stuff3 URI is Stuff4 URI is http://sirius-software.com Stuff5 URI is http://sirius-software.com

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.
  • nr is the Root node which already has an Elementchild.
  • The name argument violates the rules for an XML element name.
  • name is prefixed, but the XmlDoc Namespace property value is None.
  • name prefixed and Namespace value is On, but uri missing and no declaration for prefix in scope.
  • The value argument violates the rules for an XML element value (that is, it contains an invalid character). Note that as of Sirius Mods Version 7.6, this check can no longer be bypassed using the InvalidChar method — see the InvalidChar "Usage notes".
  • The uri argument is invalid.
  • uri is present, but the Namespace value is not On, or, uri is the null string and name is prefixed.
  • Insufficient free space exists in CCATEMP.

See also