AddText (XmlNode function)

Add Text child to Element XmlNode

AddText is a member of the XmlNode class.

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

Syntax

  [%nod =] nod:AddText(value)

Syntax Terms

%nod

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 (??AdjacentText) 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.
• 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).

Example

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):

    .in -1
    <top>
       <a>
          <b>05</b>
          In general, use Longstring %variables where you might
          use STRING LEN 255 %variables.
       </a>
    </top>
    .in 0

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 method — see Usage Notes for 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 as the immediately preceding sibling of the node pointed to by the method object.