InsertCommentBefore (XmlNode function): Difference between revisions

Latest revision as of 21:17, 2 September 2015

Insert a Comment before this node (XmlNode class)

[Requires Janus SOAP]

The InsertCommentBefore callable function inserts a Comment node as the immediate sibling preceding the method XmlNode.

Syntax

[%outNod =] nod:InsertCommentBefore( value)

Syntax terms

%outNod	If specified, an `XmlNode` that is set to point to the `Comment` node that is added.
nod	`XmlNode` pointing to the (non-Root) node before which the `Comment` node is inserted.
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 InsertCommentBefore is frequently not needed, you may want to Call it instead of saving its return value.
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 with the XmlDoc API".
There is a very small "one-time" processing cost if certain Xpath expression operations are performed after using this method, because "Insert-Before" methods are guaranteed to add a node out of document order. In general, processing an XmlDoc is likely to be more efficient if you add nodes in document order (that is, top-to-bottom, left-to-right).
To modify the value stored in a Comment node, change the Value property of an XmlNode that points to the Comment node.

Examples

In the following example, a Comment node is inserted before node "a":

begin %doc is object xmlDoc %doc = new Call %doc:loadXml('<top><a><b>05</b></a></top>') %n1 is object xmlNode %n1 = %doc:selectSingleNode('top/a') call %n1:insertCommentBefore('legacy code follows') call %doc:Print end

The example results follow:

Request-cancellation errors

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

The nod argument is the Root node.
The value argument violates the rules for an XML comment.

AddComment also adds a Comment node. InsertCommentBefore adds a Comment as the immediately preceding sibling of the node pointed to by the method object; AddComment adds the Comment as the last child of the node pointed to by the method object.
For hints about inserting a node after a sibling node, see the InsertElementBefore examples.

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

@@ Line 1: / Line 1: @@
 {{Template:XmlNode:InsertCommentBefore subtitle}}
-The <var>InsertCommentBefore</var> callable function inserts a <var>Comment</var> node as the immediate sibling preceding the method <var>XmlNode</var>.
+The <var>InsertCommentBefore</var> [[Notation_conventions_for_methods#Callable_methods|callable]] function inserts a [[XmlDoc API#XmlDoc node types|Comment node]] as the immediate sibling preceding the method <var>XmlNode</var>.
 ==Syntax==
 {{Template:XmlNode:InsertCommentBefore syntax}}
 ===Syntax terms===
 <table class="syntaxTable">
-<tr><th>%outNod</th>
+<tr><th nowrap>%outNod</th>
 <td>If specified, an <var>XmlNode</var> that is set to point to the <var>Comment</var> node that is added. </td></tr>
 <tr><th>nod</th>
 <td><var>XmlNode</var> pointing to the (non-Root) node before which the <var>Comment</var> node is inserted. </td></tr>
 <tr><th>value</th>
 <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>
@@ Line 17: / Line 20: @@
 <ul>
 <li>Since the return value of <var>InsertCommentBefore</var> is frequently not needed, you may want to <var>[[Notation_conventions_for_methods#Callable_methods|Call]]</var> it instead of saving its return value.
-<li>As of <var class="product">[[Sirius Mods]]</var> Version 7.3, <var class="term">value</var> may include only non-null EBCDIC characters that translate to <var>Unicode</var>.  As of <var class="product">"Sirius Mods"</var> Version 7.6, all <var class="product">[[Janus SOAP|"Janus Soap"]]</var> string arguments and results are <var>Unicode</var> or are converted to <var>Unicode</var>.  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"]].
-<li>There is a very small "one-time" processing cost if certain [[XPath]] operations are performed after using this method, because Insert-Before methods are guaranteed to add a node out of document order.  In general, processing 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>As of <var class="product">[[Sirius Mods]]</var> Version 7.3, <var class="term">value</var> may include only non-null EBCDIC characters that translate to Unicode.  As of <var class="product">Sirius Mods</var> Version 7.6, all <var class="product">[[Janus SOAP]]</var> string arguments and results are <var>Unicode</var> or are converted to <var>Unicode</var>.  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"]].
+<li>There is a very small "one-time" processing cost if [[XPath#ordScan|certain Xpath expression]] operations are performed after using this method, because "Insert-Before" methods are guaranteed to add a node out of document order.  In general, processing 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>To modify the value stored in a <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.
 </ul>
 ==Examples==
-<ol><li>
 In the following example, a <var>Comment</var> node is inserted before node "a":
 <p class="code">begin
@@ Line 42: / Line 47: @@
     </a>
 </top>
-</p></ol>
+</p>
-==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>
-<li><var class="term">Nod</var> is the Root node.
+<li>The <var class="term">nod</var> argument is the <var>Root</var> node.
-<li><var class="term">value</var> violates the rules for an XML comment.
+<li>The <var class="term">value</var> argument violates the rules for an XML comment.
 </ul>
@@ Line 53: / Line 59: @@
 <ul>
 <li><var>[[AddComment_(XmlDoc/XmlNode_function)|AddComment]]</var> also adds a <var>Comment</var> node. <var>InsertCommentBefore</var> adds a <var>Comment</var> as the immediately preceding sibling of the node pointed to by the method object; <var>AddComment</var> adds the <var>Comment</var> as the last child of the node pointed to by the method object.
-<li>For hints about inserting a node ''after'' a sibling node, see the [[InsertElementBefore_(XmlNode_function)#Examples|"InsertElementBefore: Examples"]].
+<li>For hints about inserting a node ''after'' a sibling node, see the <var>InsertElementBefore</var> [[InsertElementBefore_(XmlNode_function)#Examples|examples]].
 </ul>
 {{Template:XmlNode:InsertCommentBefore footer}}