AddElement (XmlDoc/XmlNode function)

Add Element to XmlDoc Root or to Element XmlNode (XmlDoc and XmlNode classes)

[Requires Janus SOAP]

This callable function adds an Element node as the last child of the Root node or Element node referenced by the method object. AddElement also lets you add a Text node as the child of the added Element, and lets you specify the namespace URI for the added element.

Syntax

[%nod =] nr:AddElement( name, [value], [uri])

Syntax terms

%nod	If specified, an XmlNode that is set to point to the Element node that is added.
nr	An XmlDoc or XmlNode that refers to the Root or Element node parent of the added Element.
name	The name of the added Element; if prefixed, the prefix must be declared, or a uri argument must be provided. Multiple Elements with the same name may be added to a single parent Element. The name must conform to the XML syntax rules for an element name; the maximum length of each of the prefix part and local name part is 300 characters (127 prior to version 7.9, and 100 characters prior to Version 7.7).
value	This optional argument is the content of a Text node that is added as a child of the added element. This content is stored without any normalization, entity substitution, etc. Since Text nodes cannot contain the null string, this argument is ignored if it is the null string.
uri	This optional argument is the URI of the added element's namespace, or it is an explicit disabling of any namespace association for the element. See "Usage Notes", below.

Usage notes

• If a uri argument is specified, the XmlDoc's Namespace property must be On, and uri must either be the null string, or it must have the format of an absolute URI. The effect depends on whether the name value includes a prefix:
  • If name has a prefix, uri must not be the null string, and uri is the declared namespace URI associated with that prefix and added element.
  • If name does not have a prefix:
    • If uri is the null string, the added element does not have a default namespace. Any in-scope default namespace the added element might have inherited, is not inherited.
    • If uri is not the null string, the added element has uri as the default namespace.

  If a non-null string uri argument is provided, and the namespace declaration resulting from it is not in scope for the added element, then a namespace declaration is added at that element.

• If the uri argument is not present, the added element's namespace is determined by the prefix and in-scope declarations:
  • If the name is prefixed, the namespace is given by the in-scope declaration of the prefix.
  • If the name has no prefix, the namespace is the default namespace, if any, in scope. If there is no default namespace in scope, the added element has no namespace.
• As of Sirius Mods Version 7.3, the AddElement arguments may include only non-null EBCDIC characters that translate to Unicode. As of Sirius Mods Version 7.6, these argument strings 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". For a Unicode-specific Add Element example, see "Adding characters that are represented by character references".
• When the return value of AddElement is not needed, you may want to Call it instead of saving its return value; the return value is typically needed only to add attributes or non-Text children of the Element.
• 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

Simple Element additions

1. In the following example, an Element 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 %n1 = %doc:selectSingleNode('top/a') %n1:addElement('c', '505') %doc:Print('top') end

   The example result follows:

   <top> <a> <b>05</b> <c>505</c> </a> </top>

2. The following statements add an Element node with a Text child and then add an Attribute node to the Element:

   %n1 = %n1:AddElement('weight', '10') %n1:AddAttribute('unit', 'gram')

Adding characters that are represented by character references

For a Sirius Mods Version 7.6 or higher request, the following example shows techniques for adding an Element node that contains a Unicode "copyright" character, and it also includes a statement to add a "trademark" character.

The AddElement statements use a hex character reference or an entity reference to represent the copyright character, and they use a character reference for the trademark. Those references must first be decoded so AddElement will interpret the value string as a single character and not as several individual characters.

• The first AddElement invocation uses the EbcdicToUnicode function and parameter setting that decode and convert a character reference to Unicode.
• The second AddElement invocation uses the U function, which is a compile-time equivalent of EbcdicToUnicode(CharacterDecode=True).
• The third and fourth AddElement invocations show what happens when character decoding is not specified; the fourth also illustrates that EBCDIC to Unicode conversion is automatically performed as needed. The value string is converted character by character, and the ampersand (&) is translated on output to a character reference (&).
• The fifth AddElement invocation uses the U function to decode and convert to Unicode the entity reference for the copyright character.
• The sixth AddElement invocation uses the U function to decode and convert to Unicode the character reference for the trademark character. Since this character does not translate to an EBCDIC character, the Print method displays its XML hexadecimal character reference.

begin %doc is object xmlDoc auto new %doc:loadXml('<top/>') %n is object XmlNode %n = %doc:selectSingleNode('top') %n:addElement('a1', - '&#xA9;':ebcdicToUnicode(CharacterDecode=True)) %n:addElement('a2', '&#xA9;':U) %n:addElement('a3', '&amp;#xA9;':EbcdicToUnicode) %n:addElement('a4', '&#xA9;') %n:addElement('a5', '&copy;':U) %n:addElement('a6', '&#x2122;':U) %doc:print end

The example result follows:

<top> <a1>©</a1> <a2>©</a2> <a3>&amp;amp;#xA9;</a3> <a4>&amp;#xA9;</a4> <a5>©</a5> <a6>&#x2122;</a6> </top>

Working with URIs

The following example contains several AddElement invocations and shows the effects of the uri argument:

• An initial invocation of AddElement adds the first element of the document. The method object in this case is an XmlDoc. This invocation fails if the document already contains an element node.
• A second AddElement invocation, this time with a node as the method object, adds an element as the child of the first element. This second element has a prefixed name but no uri value. Since the prefix matches that of the parent element, the second element receives the namespace URI of the first.
• A third AddElement invocation adds an element (to the first). Although the AddElement arguments include no name prefix and no uri, the added element may still be associated with a namespace — the default namespace of its nearest ancestor. In this case, however, no default namespace is in scope (the parent's namespace is associated with its prefix), so this child has no namespace association at all.
• A fourth AddElement invocation adds an element (to the first). The function arguments specify a non-prefixed name and also a uri value. This new URI is the added element's default namespace.
• A fifth AddElement invocation adds an element to the element added by the previous AddElement. The function arguments include no name prefix and no uri value, so the added element receives the in-scope default namespace which, in this case, is also the URI of its parent.

begin %doc is object xmlDoc %doc = new %n1 is object xmlNode %n2 is object xmlNode %n3 is object xmlNode %n4 is object xmlNode %n5 is object xmlNode %n1 = %doc:addElement('SOAP-ENV:Envelope',, - 'http://schemas.xmlsoap.org/soap/envelope/') %n2 = %n1:AddElement('SOAP-ENV:Stuff2') %n3 = %n1:AddElement('Stuff3') %n4 = %n1:AddElement('Stuff4', , - 'http://sirius-software.com') %n5 = %n4:AddElement('Stuff5') %doc:Print print 'Stuff2 URI is ' %n2:URI print 'Stuff3 URI is ' %n3:URI print 'Stuff4 URI is ' %n4:URI print 'Stuff5 URI is ' %n5:URI end

The example result follows:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Stuff2/> <Stuff3/> <Stuff4 xmlns="http://sirius-software.com"> <Stuff5/> </Stuff4> </SOAP-ENV:Envelope> Stuff2 URI is http://schemas.xmlsoap.org/soap/envelope/ Stuff3 URI is Stuff4 URI is http://sirius-software.com Stuff5 URI is http://sirius-software.com

Request-cancellation errors

This list is not exhaustive: it does not include all the errors that are request cancelling.

• The nr object is neither the Root nor an Element node.
• nr is the Root node which already has an Elementchild.
• The name argument violates the rules for an XML element name.
• name is prefixed, but the XmlDoc Namespace property value is None.
• name prefixed and Namespace value is On, but uri missing and no declaration for prefix in scope.
• The value argument violates the rules for an XML element value (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 the InvalidChar "Usage notes".
• The uri argument is invalid.
• uri is present, but the Namespace value is not On, or, uri is the null string and name is prefixed.
• Insufficient free space exists in CCATEMP.

See also

• For more information about namespace declarations, see "Names and namespaces".
• For more information about URIs, see "Uniform Resource Identifier syntax".
• InsertElementBefore also adds an Element node. AddElement adds an Element as the last child of the node pointed to by the method object; InsertElementBefore adds an Element as the immediately preceding sibling of the node pointed to by the method object.
• These methods are useful for working with namespaces:
  • AddNamespace
  • SelectionNamespace

XmlDoc class XmlNode class XmlNodelist class	List of XmlDoc methods List of XmlNode methods List of XmlNodelist methods List of XmlDoc API methods	XmlDoc methods syntax XmlNode methods syntax XmlNodelist methods syntax
Notation conventions for methods