AddTopElement (XmlDoc function)

Add new top element to XmlDoc (XmlDoc class)

[Introduced in Sirius Mods 7.7; requires Janus SOAP]

This callable function adds an Element node as the new top-level element of the XmlDoc that is the object method. This makes all the former children of the XmlDoc Root node become children of the new element. AddTopElement also lets you specify the element namespace URI for the added element.

Syntax

[%nod =] doc:AddTopElement( name, [uri], [MoveNamespace= boolean])

Syntax terms

%nod	If specified, an `XmlNode` that is set to point to the new top Element node that is added.
doc	An `XmlDoc` object variable.
name	The name (a `Unicode` string) to be given to the added Element. If the name is prefixed, a `uri` argument must be provided. 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 127 characters (100 characters prior to version 7.7 of Janus SOAP).
uri	This optional, `Unicode` string, argument defaults to the null string: If `name` contains a prefix, then `uri` specifies the URI (Uniform Resource Identifier) associated with that prefix for the element, so it must be a non-null string that is a valid URI. If `name` does not contain a prefix, then the old top element of the XmlDoc must be in a non-null default namespace, e.g., of the form `<nameWithoutPrefix xmlns="uri">`. (Note: prior to version 7.9, `uri` must be omitted or must be the null string if `name` does not contain a prefix.)
MoveNamespace	This optional, name required argument is used to avoid a redundant namespace declaration on the old top element of the `XmlDoc`. If `MoveNamespace=True` and a `uri` argument (with a non-null string) is provided, then if the "old" top element contains a namespace declaration which is the same as the declaration inserted due to the `uri` argument, the declaration is deleted from the old top element. Note: You should use `MoveNamespace=True` only when some consumer of the XML document cares about not having the redundant declaration. This would be an unusual situation, because the information content of the document does not change. Using `MoveNamespace=True` might trigger a scan of the entire `XmlDoc`, which `AddTopElement` does not normally do.

Usage notes

If a URI argument is specified, the XmlDoc's Namespace property must be On.
When you need to change the structure of an XML document and that need can be accomplished with AddTopElement, it is a more efficient approach than using AddSubtree. See the example in "Examples," below.

Examples

Add prefixed SOAP wrappers

The following request makes a copy of an XML document, then adds "SOAP wrappers" to it:

Begin %doc is Object XmlDoc %doc2 is Object XmlDoc %doc = New %doc:LoadXml('<top><a></a></top>') Call %doc:Print Print '*********************' %doc2 = %doc:DeepCopy %doc2:AddTopElement('soap:Body', - 'http://schemas.xmlsoap.org/soap/envelope/') %doc2:AddTopElement('soap:Envelope', - 'http://schemas.xmlsoap.org/soap/envelope/') Call %doc2:Print End

The result is:

In the example:

The order of the AddTopElement invocations is the reverse of the final order of the elements, that is, the second invocation creates the first element in the final document.
If you have no need to preserve the original XmlDoc, then both AddTopElement invocations can use %doc as the object method, and the DeepCopy can be omitted.
The redundant namespace declaration on the soap:Body element above would be deleted if the MoveNamespace=True argument is used, although usually the redundant declaration is acceptable and MoveNamespace should be avoided.

Add unprefixed SOAP wrappers

The following example is similar, except that the SOAP elements use a default namespace declaration. AddTopElement only allows this when the old top element is in a default namespace (here http:mydata).

Begin %doc is Object XmlDoc %doc2 is Object XmlDoc %doc = New %doc:LoadXml('<top xmlns="http:mydata"><a></a></top>') Call %doc:Print Print '*********************' %doc2 = %doc:DeepCopy %doc2:AddTopElement('Body', - 'http://schemas.xmlsoap.org/soap/envelope/') %doc2:AddTopElement('Envelope', - 'http://schemas.xmlsoap.org/soap/envelope/') Call %doc2:Print End

The result is:

Request-Cancellation Errors

Argument elementName violates the rules for an XML element name.
elementName is prefixed, but the XmlDoc Namespace property is None.
elementName is prefixed and Namespace is On, but URI is missing.
URI is invalid.
URI is present, but the Namespace property is not On, or, URI is the null string and elementName is prefixed.
Insufficient free space exists in CCATEMP.

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