InsertTextBefore (XmlNode function): Difference between revisions

From m204wiki
Jump to navigation Jump to search
mNo edit summary
m (move footer template to actual end (otherwise subsequent intervening text gets omitted); edits, tags and links)
Line 1: Line 1:
{{Template:XmlNode:InsertTextBefore subtitle}}
{{Template:XmlNode:InsertTextBefore subtitle}}
<var>InsertTextBefore</var> inserts a <var>Text</var> node as the immediate sibling preceding the method <var>XmlNode</var>.


This callable function inserts a Text node as the immediate
sibling preceding the method <var>XmlNode</var>.
==Syntax==
==Syntax==
{{Template:XmlNode:InsertTextBefore syntax}}
{{Template:XmlNode:InsertTextBefore syntax}}
Line 8: Line 7:
<table class="syntaxTable">
<table class="syntaxTable">
<tr><th>%outNod</th>
<tr><th>%outNod</th>
<td>If specified, an <var>XmlNode</var> that is set to point to the Text node that is inserted. </td></tr>
<td>If specified, an <var>XmlNode</var> that is set to point to the <var>Text</var> node that is inserted. </td></tr>
<tr><th>nod</th>
<tr><th>nod</th>
<td><var>XmlNode</var> that points to the node before which the Text node is inserted. The node may be any type except Root or Text. </td></tr>
<td><var>XmlNode</var> that points to the node before which the <var>Text</var> node is inserted. The node may be any type except <var>Root</var> or <var>Text</var>.</td></tr>
<tr><th>value</th>
<tr><th>value</th>
<td>The content of the Text node. This <var>Unicode</var> string value is stored without any normalization, entity substitution, etc.</td></tr>
<td>The content of the <var>Text</var> node. This <var>Unicode</var> string value is stored without any normalization, entity substitution, etc.</td></tr>
</table>
</table>


==Usage notes==
==Usage notes==
<ul>
<ul>
<li>If <i>value</i> is the null string, a Text node is not inserted,
<li>If <var class="term">value</var> is the null string, a <var>Text</var> node is not inserted, and <var class="term">%nod</var> is set to <var>Null</var>.
and <i>%nod</i> is set to Null.
<li>As of <var class="product">[[Sirius Mods|"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>As of ''Sirius Mods'' version 7.3, ''value'' may
<li>Since the return value of <var>InsertTextBefore</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.
include only non-null EBCDIC characters that translate to <var>Unicode</var>.
<li>To modify the value stored in an <var>Text</var> node, change the <var>[[Value_(XmlDoc/XmlNode_property)|Value]]</var> property of an <var>XmlNode</var> that points to the <var>Text</var> node.
As of ''Sirius Mods'' version 7.6, all [[Janus SOAP]] string arguments and results
<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).  
are <var>Unicode</var> or are converted to <var>Unicode</var>.
<li>A <var>Text</var> node may not be inserted adjacent to (that is, as a sibling of) another <var>Text</var> node, unless the <var>[[AdjacentText (XmlDoc property)|AdjacentText]]</var> property setting is <code>Combine</code>.
For more information about the effects of this version 7.6
change, see [[Strings and Unicode]].
<li>Since the return value of <var>InsertTextBefore</var> is frequently not needed,
you may want to Call it instead of saving its return value.
<li>To modify the value stored in an Text node,
change the Value property of an <var>XmlNode</var> that points to the Text node.
<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>A Text node may not be inserted adjacent to (that is, as a sibling of)
another Text node, unless the [[AdjacentText (XmlDoc property)|AdjacentText]] property setting is <tt>Combine</tt>.
</ul>
</ul>


===Example===
==Examples==
 
<ol><li>
In the following example, a Text node is inserted before node "b"
In the following example, a <var>Text</var> node is inserted before node "b" (that is, as its immediately preceding sibling):
(that is, as its immediately preceding sibling):
<p class="code">begin
<p class="code">Begin
  %doc is object xmlDoc
%doc is Object XmlDoc
  %doc = new
%doc = New
  %doc:[[LoadXml_(XmlDoc/XmlNode_function)|loadXml]]('<top><a><c/><nowiki><b>05</b></nowiki></a></top>')
%doc:LoadXml('<top><a><c/><nowiki><b>05</b></nowiki></a></top>')
  %n1 is object xmlNode
%n1 is Object XmlNode
  %n2 is object xmlNode
%n2 is Object XmlNode
  %ls is longstring
%ls is longstring
  %ls = 'Text node never contains the null string'
%ls = 'Text node never contains the null string'
  %n1 = %doc:[[SelectSingleNode_(XmlDoc/XmlNode_function)|selectSingleNode]]('top/a/b')
%n1 = %doc:SelectSingleNode('top/a/b')
  %n2 = %n1:InsertTextBefore(%ls)
%n2 = %n1:InsertTextBefore(%ls)
  %doc:Print('top')
%doc:Print('top')
end
End
</p>
</p>
 
The example result follows. Note that this XML document structure (element "a" having "mixed content," both an <var>Element</var> and <var>Text</var> child) is common to '''document''' usage with XML. But it is unusual for '''data''' usage with XML (in fact, the SOAP standard disallows mixed content):
The example result follows.
<p class="output"><top>
Note that this XML document structure
(element "a" having "mixed content,"
both an Element and Text child) is common to '''document'''
usage with XML.
But it is unusual for '''data''' usage with
XML (in fact, the SOAP standard disallows mixed content):
<p class="code"><top>
  <a>
  <a>
     <c/>
     <c/>
Line 68: Line 48:
  </a>
  </a>
</top>
</top>
</p>
</p></ol>


===Request-Cancellation Errors===
==Request-Cancellation Errors==
<ul>
<ul>
<li><i>Nod</i> is the Root node.
<li><var class="term">Nod</var> is the <var>Root</var> node.
<li><i>Nod</i> is a Text node, or the sibling
<li><var class="term">Nod</var> is a <var>Text</var> node, or the sibling following a <var>Text</var> node, and the <var>[[AdjacentText (XmlDoc property)|AdjacentText]]</var> property setting is <code>Disallow</code>.
following a Text node, and the [[AdjacentText (XmlDoc property)|AdjacentText]] property setting is <tt>Disallow</tt>.
<li><var class="term">Nod</var> is a child of the <var>Root</var> node.
<li><i>Nod</i> is a child of the Root node.
<li><var class="term">Value</var> violates the rules for XML Element content (that is, it contains an invalid character). Note that as of <var class="product">"Sirius Mods"</var> Version 7.6, this check can no longer be bypassed using the <var>InvalidChar</var> method &mdash; see <var>[[InvalidChar (XmlDoc property)#Usage notes|"Usage notes for the InvalidChar property"]]</var>.
<li><i>Value</i> violates the rules for
XML Element content (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 &mdash; see [[InvalidChar (XmlDoc property)#Usage notes|Usage notes for the InvalidChar property]].
<li>Insufficient free space exists in CCATEMP.
<li>Insufficient free space exists in CCATEMP.
</ul>
</ul>


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

Revision as of 05:30, 7 May 2011

Insert Text node before this node (XmlNode class)

[Requires Janus SOAP]

InsertTextBefore inserts a Text node as the immediate sibling preceding the method XmlNode.

Syntax

[%outNod =] nod:InsertTextBefore( value)

Syntax terms

%outNod If specified, an XmlNode that is set to point to the Text node that is inserted.
nod XmlNode that points to the node before which the Text node is inserted. The node may be any type except Root or Text.
value The content of the Text node. This Unicode string value is stored without any normalization, entity substitution, etc.

Usage notes

  • If value is the null string, a Text node is not inserted, and %nod is set to Null.
  • 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".
  • Since the return value of InsertTextBefore is frequently not needed, you may want to Call it instead of saving its return value.
  • To modify the value stored in an Text node, change the Value property of an XmlNode that points to the Text node.
  • 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).
  • A Text node may not be inserted adjacent to (that is, as a sibling of) another Text node, unless the AdjacentText property setting is Combine.

Examples

  1. In the following example, a Text node is inserted before node "b" (that is, as its immediately preceding sibling):

    begin %doc is object xmlDoc %doc = new %doc:loadXml('<top><a><c/><b>05</b></a></top>') %n1 is object xmlNode %n2 is object xmlNode %ls is longstring %ls = 'Text node never contains the null string' %n1 = %doc:selectSingleNode('top/a/b') %n2 = %n1:InsertTextBefore(%ls) %doc:Print('top') end

    The example result follows. Note that this XML document structure (element "a" having "mixed content," both an Element and Text child) is common to document usage with XML. But it is unusual for data usage with XML (in fact, the SOAP standard disallows mixed content):

    <top> <a> <c/> Text node never contains the null string <b>05</b> </a> </top>

Request-Cancellation Errors

  • Nod is the Root node.
  • Nod is a Text node, or the sibling following a Text node, and the AdjacentText property setting is Disallow.
  • Nod is a child of the Root node.
  • Value violates the rules for XML Element content (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 "Usage notes for the InvalidChar property".
  • Insufficient free space exists in CCATEMP.

See also

  • AddText also adds a Text node. InsertTextBefore adds a Text as the immediately preceding sibling of the node pointed to by the method object. AddText adds a Text as the last child of the node pointed to by the method object.
Retrieved from "https://m204wiki.rocketsoftware.com/index.php?title=InsertTextBefore_(XmlNode_function)&oldid=10745"