AddElement (XmlDoc/XmlNode function): Difference between revisions

From m204wiki
Jump to navigation Jump to search
mNo edit summary
 
(5 intermediate revisions by 3 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 <var>Element</var> 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 [[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.


==Syntax==
==Syntax==
Line 6: Line 6:
===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>
Line 81: Line 81:
</ol>
</ol>
====Adding characters that are represented by character references====
====Adding characters that are represented by character references====
For a <var class="product">[[Sirius Mods|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.
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.


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.
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.
<ul>
<ul>
<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>.
<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>.
<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 (String function)|U]] function, which is a compile-time equivalent of <var>EbcdicToUnicode(CharacterDecode=True)</var>.
<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 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 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.
<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.
<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.
<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.
</ul>
</ul>
Line 94: Line 98:
   %doc is object xmlDoc auto new
   %doc is object xmlDoc auto new
   %doc:[[LoadXml_(XmlDoc/XmlNode_function)|loadXml]]('<top/>')
   %doc:[[LoadXml_(XmlDoc/XmlNode_function)|loadXml]]('<top/>')
   %n is object xXmlNode
   %n is object XmlNode


   %n = %doc:[[SelectSingleNode_(XmlDoc/XmlNode_function)|selectSingleNode]]('top')
   %n = %doc:[[SelectSingleNode_(XmlDoc/XmlNode_function)|selectSingleNode]]('top')
Line 100: Line 104:
       '&amp;#xA9;':[[EbcdicToUnicode (String function)|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)
Line 111: Line 115:
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>
====Working with URIs====
====Working with URIs====
The following example contains several <var>AddElement</var> invocations and shows the effects of the <var class="term">uri</var> argument:
The following example contains several <var>AddElement</var> invocations and shows the effects of the <var class="term">uri</var> argument:
Line 167: Line 172:


==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>The <var class="term">nr</var> object 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.

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