AddText (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:AddText subtitle}}
{{Template:XmlNode:AddText subtitle}}
The <var>AddText</var> callable function adds a <var>Text</var> node as the last child of the method <var>Element</var> node.


This callable function adds a Text
node as the last child of the method Element node.
==Syntax==
==Syntax==
{{Template:XmlNode:AddText syntax}}
{{Template:XmlNode:AddText 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 added. </td></tr>
<td>If specified, an <var>XmlNode</var> that is set to point to the <var>Text</var> node that is added.</td></tr>
<tr><th>nod</th>
<tr><th>nod</th>
<td>An <var>XmlNode</var> that points to the Element node parent of the inserted Text node. </td></tr>
<td>An <var>XmlNode</var> that points to the <var>Element</var> node parent of the inserted <var>Text</var> node.</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. Prior to ''Sirius Mods'' version 7.6, this is an EBCDIC string.</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. Prior to <var class="product">[[Sirius Mods|"Sirius Mods"]]</var> Version 7.6, this is an EBCDIC string.</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 <i>value</i> 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>A <var>Text</var> node may not be added 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>.
<li>A Text node may not be added adjacent to (that is, as a sibling of)
<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"]].
another Text node, unless the [[AdjacentText (XmlDoc property)|AdjacentText]] property setting is <tt>Combine</tt>.
<li>Since the return value of <var>AddText</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 ''Sirius Mods'' version 7.3, ''value'' may
<li>To modify the value stored in an <var>Text</var> node, change the <var class="term">Value</var> property of an <var>XmlNode</var> that points to the <var>Text</var> node.
include only non-null EBCDIC characters that translate to <var>Unicode</var>.
<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).
As of ''Sirius Mods'' version 7.6, all [[Janus SOAP]] 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 [[Strings and Unicode]].
<li>Since the return value of <var>AddText</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).
</ul>
</ul>


===Example===
==Examples==
 
<ol><li>
In the following example, a Text node is added as the last child
In the following example, a <var>Text</var> node is added as the last child (that is, located after element "b") of element "a":
(that is, located after element "b") of element "a":
<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><nowiki><b>05</b></nowiki></a></top>')
%doc:LoadXml('<top><a><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 ='In general, use Longstring %variables where'-
%ls ='In general, use Longstring %variables where'-
      with ' you might use String Len 255 %variables.'
  With ' you might use String Len 255 %variables.'
  %n1 = %doc:[[SelectSingleNode_(XmlDoc/XmlNode_function)|selectSingleNode]]('top/a')
%n1 = %doc:SelectSingleNode('top/a')
  %n2 = %n1:addText(%ls)
%n2 = %n1:AddText(%ls)
  %doc:print('top')
%doc:Print('top')
end
End
</p>
</p>


The example result follows.
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 <var>document</var> usage with XML. But it is unusual for <var>data</var> usage with XML (in fact, the SOAP standard disallows mixed content):
Note that this XML document structure
<p class="output"><nowiki><top>
(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">.in -1
<top>
   <a>
   <a>
       <nowiki><b>05</b></nowiki>
       <b>05</b>
       In general, use Longstring %variables where you might
       In general, use Longstring %variables where you might
       use STRING LEN 255 %variables.
       use STRING LEN 255 %variables.
   </a>
   </a>
</top>
</top></nowiki>
</p>
</p></ol>


===Request-Cancellation Errors===
==Request-Cancellation Errors==
<ul>
<ul>
<li><i>Nod</i> does not point to an Element node.
<li><var class="term">Nod</var> does not point to an <var>Element</var> node.
<li><i>Nod</i> points to an Element node whose last
<li><var class="term">Nod</var> points to an <var>Element</var> node whose last child is a <var>Text</var> node, and the <var>[[AdjacentText_(XmlDoc_property)|AdjacentText]]</var> property setting is <code>Disallow</code>.
child is a Text node, and the AdjacentText property
<li><var class="term">Value</var> violates the rules for XML <var>Element</var> content (that is, it contains an invalid character). Note that as of <var class="product">[[Sirius Mods|"Sirius Mods"]]</var> Version 7.6, this check can no longer be bypassed using the <var>[[InvalidChar (XmlDoc property)|InvalidChar]]</var> property.
setting is <tt>Disallow</tt>.
<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:AddText footer}}
<ul>
<ul>
<li>[[InsertTextBefore (XmlNode function)|InsertTextBefore]] also adds a Text node.
<li><var>[[InsertTextBefore (XmlNode function)|InsertTextBefore]]</var> also adds a <var>Text</var> node. <var>AddText</var> adds a <var>Text</var> as the last child of the node pointed to by the method object; <var>InsertTextBefore</var> adds a <var>Text</var> node as the immediately preceding sibling of the node pointed to by the method object.
<var>AddText</var> adds a Text as the last child of the node pointed to by the
method object;
InsertTextBefore adds a Text as the immediately preceding
sibling of the node pointed to by the method object.
</ul>
</ul>
{{Template:XmlNode:AddText footer}}

Revision as of 10:08, 4 May 2011

Add Text child to Element node (XmlNode class)

[Requires Janus SOAP]

The AddText callable function adds a Text node as the last child of the method Element node.

Syntax

[%outNod =] nod:AddText( value)

Syntax terms

%outNod If specified, an XmlNode that is set to point to the Text node that is added.
nod An XmlNode that points to the Element node parent of the inserted Text node.
value The content of the Text node. This Unicode string value is stored without any normalization, entity substitution, etc. Prior to "Sirius Mods" Version 7.6, this is an EBCDIC string.

Usage notes

  • If value is the null string, a Text node is not inserted, and %nod is set to Null.
  • A Text node may not be added adjacent to (that is, as a sibling of) another Text node, unless the AdjacentText property setting is Combine.
  • 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 AddText 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).

Examples

  1. In the following example, a Text node is added as the last child (that is, located after element "b") of element "a":

    begin %doc is object xmlDoc %doc = new %doc:loadXml('<top><a><b>05</b></a></top>') %n1 is object xmlNode %n2 is object xmlNode %ls is longstring %ls ='In general, use Longstring %variables where'- with ' you might use String Len 255 %variables.' %n1 = %doc:selectSingleNode('top/a') %n2 = %n1:addText(%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> <b>05</b> In general, use Longstring %variables where you might use STRING LEN 255 %variables. </a> </top>

Request-Cancellation Errors

  • Nod does not point to an Element node.
  • Nod points to an Element node whose last child is a Text node, and the AdjacentText property setting is Disallow.
  • 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 property.
  • Insufficient free space exists in CCATEMP.

See also

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