InsertTextBefore (XmlNode function): Difference between revisions

From m204wiki
Jump to navigation Jump to search
mNo edit summary
 
mNo edit summary
Line 1: Line 1:
<span style="font-size:120%; color:black"><b>Insert Text before XmlNode</b></span>
{{Template:XmlNode:InsertTextBefore subtitle}}
[[Category:XmlNode methods|InsertTextBefore function]]
[[Category:XmlNode methods|InsertTextBefore function]]
[[Category:XmlDoc API methods]]
[[Category:XmlDoc API methods]]
Line 11: Line 11:
This callable function inserts a Text node as the immediate
This callable function inserts a Text node as the immediate
sibling preceding the method XmlNode.
sibling preceding the method XmlNode.
===Syntax===
==Syntax==
  [%nod =] nod:InsertTextBefore(value)
{{Template:XmlNode:InsertTextBefore syntax}}
 
===Syntax terms===
====Syntax Terms====
<dl>
<dl>


Line 29: Line 28:
</dl>
</dl>


===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 Text node is not inserted,
Line 52: Line 51:
===Example===
===Example===


In the following example, a Text node is inserted before node &ldquo;b&rdquo;
In the following example, a Text node is inserted before node "b"
(that is, as its immediately preceding sibling):
(that is, as its immediately preceding sibling):
<pre>
<pre>
Line 71: Line 70:
The example result follows.
The example result follows.
Note that this XML document structure
Note that this XML document structure
(element &ldquo;a&rdquo; having &ldquo;mixed content,&rdquo;
(element "a" having "mixed content,"
both an Element and Text child) is common to '''document'''
both an Element and Text child) is common to '''document'''
usage with XML.
usage with XML.

Revision as of 16:58, 22 January 2011

Insert Text node before this node (XmlNode class)

[Requires Janus SOAP]

InsertTextBefore is a member of the XmlNode class.

This callable function inserts a Text node as the immediate sibling preceding the method XmlNode.

Syntax

[%outNod =] nod:InsertTextBefore( value)

Syntax terms

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

Example

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.