InsertCommentBefore (XmlNode function): Difference between revisions
Jump to navigation
Jump to search
m (1 revision) |
m (1 revision) |
||
| Line 2: | Line 2: | ||
This callable function inserts a Comment node as the immediate | This callable function inserts a Comment node as the immediate | ||
sibling preceding the method XmlNode. | sibling preceding the method <var>XmlNode</var>. | ||
==Syntax== | ==Syntax== | ||
{{Template:XmlNode:InsertCommentBefore syntax}} | {{Template:XmlNode:InsertCommentBefore syntax}} | ||
| Line 8: | Line 8: | ||
<table class="syntaxTable"> | <table class="syntaxTable"> | ||
<tr><th><i>%nod</i></th> | <tr><th><i>%nod</i></th> | ||
<td>If specified, an XmlNode that is set to point to the Comment node that is added. </td></tr> | <td>If specified, an <var>XmlNode</var> that is set to point to the Comment node that is added. </td></tr> | ||
<tr><th><i>nod</i></th> | <tr><th><i>nod</i></th> | ||
<td>XmlNode pointing to the (non-Root) node before which the Comment node is inserted. </td></tr> | <td><var>XmlNode</var> pointing to the (non-Root) node before which the Comment node is inserted. </td></tr> | ||
<tr><th><i>value</i></th> | <tr><th><i>value</i></th> | ||
<td>A Unicode string that is the value of the added Comment node; stored exactly as is, that is, without whitespace normalization.</td></tr> | <td>A <var>Unicode</var> string that is the value of the added Comment node; stored exactly as is, that is, without whitespace normalization.</td></tr> | ||
</table> | </table> | ||
==Usage notes== | ==Usage notes== | ||
<ul> | <ul> | ||
<li>Since the return value of InsertCommentBefore is frequently not needed, | <li>Since the return value of <var>InsertCommentBefore</var> is frequently not needed, | ||
you may want to Call it instead of saving its return value. | you may want to Call it instead of saving its return value. | ||
<li>As of ''Sirius Mods'' version 7.3, ''value'' may | <li>As of ''Sirius Mods'' version 7.3, ''value'' may | ||
include only non-null EBCDIC characters that translate to Unicode. | include only non-null EBCDIC characters that translate to <var>Unicode</var>. | ||
As of ''Sirius Mods'' version 7.6, all [[Janus SOAP]] string arguments and results | As of ''Sirius Mods'' version 7.6, all [[Janus SOAP]] string arguments and results | ||
are Unicode or are converted to Unicode. | 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 [[Strings and Unicode]]. | change, see [[Strings and Unicode]]. | ||
| Line 28: | Line 28: | ||
if certain XPath operations are performed after using this method, because | if certain XPath operations are performed after using this method, because | ||
Insert-Before methods are guaranteed to add a node out of document order. | 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 | 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). | you add nodes in document order (that is, top-to-bottom, left-to-right). | ||
<li>To modify the value stored in a Comment node, | <li>To modify the value stored in a Comment node, | ||
change the Value property of an XmlNode that points to the Comment node. | change the Value property of an <var>XmlNode</var> that points to the Comment node. | ||
</ul> | </ul> | ||
| Line 39: | Line 39: | ||
a Comment node is inserted before node "a": | a Comment node is inserted before node "a": | ||
<p class="code">Begin | <p class="code">Begin | ||
%doc is Object XmlDoc | %doc is <var>Object</var> <var>XmlDoc</var> | ||
%doc = New | %doc = New | ||
Call %doc:LoadXml('<top><a><b>05</b></a></top>') | Call %doc:LoadXml('<top><a><b>05</b></a></top>') | ||
%n1 is Object XmlNode | %n1 is <var>Object</var> <var>XmlNode</var> | ||
%n1 = %doc:SelectSingleNode('top/a') | %n1 = %doc:SelectSingleNode('top/a') | ||
Call %n1:InsertCommentBefore('legacy code follows') | Call %n1:<var>InsertCommentBefore</var>('legacy code follows') | ||
Call %doc:Print | Call %doc:Print | ||
End | End | ||
| Line 72: | Line 72: | ||
<li>AddComment ([[??]] reftxt=AddComment refid=addcom.) | <li>AddComment ([[??]] reftxt=AddComment refid=addcom.) | ||
also adds a Comment node. | also adds a Comment node. | ||
InsertCommentBefore adds a Comment as the immediately preceding | <var>InsertCommentBefore</var> adds a Comment as the immediately preceding | ||
sibling of the node pointed to by the method object; | 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 | AddComment adds a Comment as the last child of the node pointed to by the | ||
Revision as of 17:46, 25 January 2011
Insert a Comment before this node (XmlNode class)
[Requires Janus SOAP]
This callable function inserts a Comment node as the immediate
sibling preceding the method XmlNode.
Syntax
[%outNod =] nod:InsertCommentBefore( value)
Syntax terms
| %nod | 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.
- 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 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.
Example
In the following example, a Comment node is inserted before node "a":
Begin %doc is Object XmlDoc %doc = New Call %doc:LoadXml('<top><a>05</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:
<top> <a> 05 </a> </top>
Request-Cancellation Errors
- Nod is the Root node.
- Argument value violates the rules for an XML comment.
See also
- AddComment (?? reftxt=AddComment refid=addcom.) 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 a 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 "Example" section in InsertElementBefore.