AddComment (XmlDoc/XmlNode function)

Add Comment to XmlDoc Root or to Element XmlNode

AddComment is a member of the XmlDoc and XmlNode classes.

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 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.
• 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>
       <!--this is comment 1-->
   

2. In the following example under Sirius Mods 7.6 or higher, a Unicode character comment is added, 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('™':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
   

   For additional examples of working with Unicode characters in an XmlDoc, see item ?? refid=addunic..

Request-Cancellation Errors

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