AddComment (XmlDoc/XmlNode function): Difference between revisions

From m204wiki
Jump to navigation Jump to search
mNo edit summary
 
(33 intermediate revisions by 6 users not shown)
Line 1: Line 1:
<span style="font-size:120%; color:black"><b>Add Comment to XmlDoc Root or to Element XmlNode</b></span>
{{Template:XmlDoc/XmlNode:AddComment subtitle}}
[[Category:XmlDoc methods|AddComment function]]
This <var>[[Notation_conventions_for_methods#Callable_methods|callable]]</var> function adds a [[XmlDoc API#XmlDoc node types|Comment node]] as the last child of the <var>Root</var> node or <var>Element</var> node referenced by the method object.
[[Category:XmlNode methods|AddComment function]]
[[Category:XmlDoc API methods]]
<!--DPL?? Category:XmlDoc methods|AddComment function: Add Comment to XmlDoc Root or to Element XmlNode-->
<!--DPL?? Category:XmlNode methods|AddComment function: Add Comment to XmlDoc Root or to Element XmlNode-->
<!--DPL?? Category:XmlDoc API methods|AddComment (XmlDoc/XmlNode function): Add Comment to XmlDoc Root or to Element XmlNode-->
<!--DPL?? Category:System methods|AddComment (XmlDoc/XmlNode function): Add Comment to XmlDoc Root or to Element XmlNode-->
<p>
AddComment is a member of the [[XmlDoc class|XmlDoc]] and [[XmlNode class|XmlNode]] classes.
</p>


This callable function adds a Comment node as the last child of the Root node
==Syntax==
or Element node referenced by the method object.
{{Template:XmlDoc/XmlNode:AddComment syntax}}
===Syntax===
  [%nod =] nr:AddComment(value)


====Syntax Terms====
===Syntax terms===
<dl>
<table class="syntaxTable">
<dt><i>%nod</i>
<tr><th nowrap>%nod</th>
<dd>If specified, an XmlNode that is set to point to the Comment node that is added.
<td>If specified, an <var>XmlNode</var> that is set to point to the <var>Comment</var> node that is added. </td></tr>
<dt><i>nr</i>
<tr><th>nr</th>
<dd>An XmlDoc or XmlNode that refers to the Root or Element node
<td>An <var>XmlDoc</var> or <var>XmlNode</var> that refers to the <var>Root</var> or <var>Element</var> node that is the parent of the added <var>Comment</var> node. </td></tr>
that is the parent of the added Comment node.
<tr><th>value</th>
<dt><i>value</i>
<td>A <var>Unicode</var> string that is the value of the added <var>Comment</var> node; stored exactly as is, that is, without whitespace normalization.</td></tr>
<dd>A Unicode string that is the value of the added Comment node;
</table>
stored exactly as is, that is, without
whitespace normalization.


</dl>
==Usage notes==
 
===Usage Notes===
<ul>
<ul>
<li>Since the return value of AddComment is frequently not needed,
<li>Since the return value of <var>AddComment</var> is frequently not needed, you may want to [[Notation_conventions_for_methods#Callable_methods|Call]] it instead of saving its return value.
you may want to Call it instead of saving its return value.
<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).
<li>Processing of an XmlDoc is likely to be more efficient if
<li>As of <var class="product">[[Sirius Mods]]</var> Version 7.3, <var class="term">value</var> may not include EBCDIC characters that do not translate to Unicode. As of <var class="product">Sirius Mods</var> Version 7.6, the content of an <var>XmlDoc</var> is maintained in <var>Unicode</var>. For more information about the effects of this Version 7.6 change, see <var>[[XmlNodelist_class#Strings_and_Unicode_with_the_XmlDoc_API|"Strings and Unicode"]]</var>.
you add nodes in document
<li>To modify the <var>value</var> stored in an <var>Comment</var> node, change the <var>[[Value_(XmlDoc/XmlNode_property)|Value]]</var> property of an <var>XmlNode</var> that points to the <var>Comment</var> node.
order (that is, top-to-bottom, left-to-right).
<li>As of ''Sirius Mods'' version 7.3, ''value'' may
include only non-null EBCDIC characters that translate to Unicode.
As of ''Sirius Mods'' version 7.6, all [[Janus SOAP]] string arguments and results are Unicode
or are converted to Unicode.
For more information about the effects of this version 7.6
change, see [[Strings and Unicode]].
<li>To modify the value stored in an Comment node,
change the Value property of an XmlNode that points to
the Comment node.
</ul>
</ul>


===Examples===
==Examples==
<ol>
<ol>
<li>In the following example, one Comment node is added as the last child
<li>In the following example, one <var>Comment</var> node is added as the last child of the <var>Root</var> node, and one is added as the last child of element "b":
of the root node, and one is added as the last child of element &ldquo;b&rdquo;:
<p class="code">begin
<pre>
  %doc is object xmlDoc
    Begin
  %doc = new
    %doc is Object XmlDoc
  %doc:[[LoadXml_(XmlDoc/XmlNode_function)|loadXml]]<nowiki>('<top><a><b>05</b></a></top>')</nowiki>
    %doc = New
  %n1 is object xmlNode
    %doc:LoadXml('<top><a><b>05</b></a></top>')
  call %doc:addComment('this is comment 1')
    %n1 is Object XmlNode
  %n1 = %doc:[[SelectSingleNode_(XmlDoc/XmlNode_function)|selectSingleNode]]('top/a/b')
    Call %doc:AddComment('this is comment 1')
  call %n1:addComment('this is comment 2')
    %n1 = %doc:SelectSingleNode('top/a/b')
  call %doc:Print
    Call %n1:AddComment('this is comment 2')
end
    Call %doc:Print
</p>
    End
</pre>


The example result, showing the serialized format of the comments, follows:
The example result, showing the serialized format of the comments, follows:
<pre>
<p class="code"><nowiki><top>
    <top>
  <a>
      <a>
      <b>
          <b>
        05
            05
        <!--this is comment 2-->
            <!--this is comment 2-->
      </b>
          </b>
  </a></nowiki>
      </a>
</top>
    </top>
<!--this is comment 1-->
    <!--this is comment 1-->
</p>
</pre>
 
<li>In the following example under ''Sirius Mods'' 7.6 or higher, a Unicode character
<li>In the following example under <var class="product">Sirius Mods</var> Version 7.6 or higher, a comment is added which uses a Unicode character, then printed twice. The Print statement succeeds only if its <var>CharacterEncodeAll</var> option is specified, because the Unicode character (trademark) does not translate to an EBCDIC character. For such a character in an Element or Attribute value, however, the <var>Print</var> method automatically displays the XML hex representation and does ''not'' require the <var>CharacterEncodeAll</var> option.
comment is added, then printed twice.
<p class="code">begin
The Print statement succeeds only if its <tt>CharacterEncodeAll</tt> option
  %d object xmlDoc auto new
is specified, because the Unicode character (trademark) does not translate
  %d:addComment('&amp;#x2122;':U)
to an EBCDIC character.
  %d:[[AddElement_(XmlDoc/XmlNode_function)|addElement]]('a')
For such a character in an Element or Attribute value, however, the Print
method automatically displays the XML hex representation and does ''not''
require the CharacterEncodeAll option.
<pre>
    Begin
    %d Object XmlDoc Auto New
    %d:AddComment('&amp;#x2122;':U)
    %d:AddElement('a')


    %d:Print(, 'CharacterEncodeAll')
  %d:print(, 'CharacterEncodeAll')
    %d:Print
  %d:print
    End
end
</pre>
</p>


The result is:
The result is:
<pre>
<p class="output"><nowiki><!--&amp;#x2122;-->
    <!--&amp;#x2122;-->
<a/>
    <a/>
CANCELLING REQUEST: MSIR.0750: Class XMLDOC, subroutine PRINT:
    CANCELLING REQUEST: MSIR.0750: Class XMLDOC, subroutine
  Unicode character without valid translation to EBCDIC in line 9</nowiki>
    PRINT: Unicode character without valid translation to
</p>
    EBCDIC in line 9
</pre>


For additional examples of working with Unicode characters in an XmlDoc,
<li>For additional examples of working with Unicode characters in an <var>XmlDoc</var>, see item [[AddElement_(XmlDoc/XmlNode_function)#Adding_characters_that_are_represented_by_character_references|Adding characters that are represented by character references]].
see item [[??]] refid=addunic..
</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>Nr</i> is neither the Root nor an Element node.
<li>Object <var class="term">nr</var> is neither the <var>Root</var> nor an <var>Element</var> node.
<li>Argument <i>value</i> violates the rules for an
<li>Argument <var class="term">value</var> violates the rules for an XML comment.
XML comment.
</ul>
</ul>


 
==See also==
===See Also===
 
<ul>
<ul>
<li>[[InsertCommentBefore (XmlNode function)|InsertCommentBefore]] also adds a Comment node.
<li><var>[[InsertCommentBefore (XmlNode function)|InsertCommentBefore]]</var> also adds a <var>Comment</var> node. <var>AddComment</var> adds a <var>Comment</var> as the last child of the node pointed to by the method object; <var>InsertCommentBefore</var> adds a <var>Comment</var> as the immediately preceding sibling of the node pointed to by the method object.
AddComment adds a Comment as the last child of the node pointed to by the
method object;
InsertCommentBefore adds a Comment as the immediately preceding
sibling of the node pointed to by the method object.
</ul>
</ul>
{{Template:XmlDoc/XmlNode:AddComment footer}}

Latest revision as of 21:00, 2 September 2015

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

[Requires Janus SOAP]

This callable function adds a Comment node as the last child of the Root node or Element node referenced by the method object.

Syntax

[%nod =] nr:AddComment( value)

Syntax terms

%nod If specified, an XmlNode that is set to point to the Comment node that is added.
nr An XmlDoc or XmlNode that refers to the Root or Element node that is the parent of the added Comment node.
value A Unicode string that is the value of the added Comment node; stored exactly as is, that is, without whitespace normalization.

Usage notes

  • Since the return value of AddComment is frequently not needed, you may want to Call it instead of saving its return value.
  • 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).
  • As of Sirius Mods Version 7.3, value may not include EBCDIC characters that do not translate to Unicode. As of Sirius Mods Version 7.6, the content of an XmlDoc is maintained in Unicode. For more information about the effects of this Version 7.6 change, see "Strings and Unicode".
  • To modify the value stored in an Comment node, change the Value property of an XmlNode that points to the Comment node.

Examples

  1. In the following example, one Comment node is added as the last child of the Root node, and one is added as the last child of element "b":

    begin %doc is object xmlDoc %doc = new %doc:loadXml('<top><a><b>05</b></a></top>') %n1 is object xmlNode call %doc:addComment('this is comment 1') %n1 = %doc:selectSingleNode('top/a/b') call %n1:addComment('this is comment 2') call %doc:Print end

    The example result, showing the serialized format of the comments, follows:

    <top> <a> <b> 05 <!--this is comment 2--> </b> </a> </top>

  2. In the following example under Sirius Mods Version 7.6 or higher, a comment is added which uses a Unicode character, then printed twice. The Print statement succeeds only if its CharacterEncodeAll option is specified, because the Unicode character (trademark) does not translate to an EBCDIC character. For such a character in an Element or Attribute value, however, the Print method automatically displays the XML hex representation and does not require the CharacterEncodeAll option.

    begin %d object xmlDoc auto new %d:addComment('&#x2122;':U) %d:addElement('a') %d:print(, 'CharacterEncodeAll') %d:print end

    The result is:

    <!--&#x2122;--> <a/> CANCELLING REQUEST: MSIR.0750: Class XMLDOC, subroutine PRINT: Unicode character without valid translation to EBCDIC in line 9

  3. For additional examples of working with Unicode characters in an XmlDoc, see item Adding characters that are represented by character references.

Request-cancellation errors

This list is not exhaustive: it does not include all the errors that are request cancelling.

  • Object nr is neither the Root nor an Element node.
  • Argument value violates the rules for an XML comment.

See also

  • InsertCommentBefore also adds a Comment node. AddComment adds a Comment as the last child of the node pointed to by the method object; InsertCommentBefore adds a Comment as the immediately preceding sibling of the node pointed to by the method object.
Retrieved from "https://m204wiki.rocketsoftware.com/index.php?title=AddComment_(XmlDoc/XmlNode_function)&oldid=80430"