InsertElementBefore (XmlNode function)
Insert an Element before this node (XmlNode class)
[Requires Janus SOAP]
The InsertElementBefore callable function inserts an Element node as the sibling immediately preceding the method XmlNode. InsertElementBefore also lets you add a Text node as the child of the inserted Element, and it lets you specify the namespace URI for the inserted element.
Syntax
[%outNod =] nod:InsertElementBefore( name, [value], [uri])
Syntax terms
| %outNod | If specified, an XmlNode that is set to point to the Element node that is inserted. |
|---|---|
| nod | XmlNode that points to the (non-Root) node before which the Element node is inserted. |
| name | A Unicode string that is the name of the inserted Element; if prefixed, the prefix must be declared, or 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 300 characters (127 characters prior to Sirius Mods 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 inserted element. This Unicode string 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 value 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 InsertElementBefore method 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 Xml API".
- When the return value of InsertElementBefore 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.
- There is a very small "one-time" processing cost if certain Xpath expression operations are performed after using this method, because "Insert-Before" methods are guaranteed to add a node out of document order. In general, processing an XmlDoc is likely to be more efficient if you add nodes in document order (that is, top-to-bottom, left-to-right).
Examples
- In the following example, an element node with text is inserted as a sibling before node "b". An AddElement call then adds a child node to the parent of "b", and this child becomes a sibling of "b" located after it.
begin %doc is object xmlDoc %doc = new call %doc:loadXml('<top><a><c/><b>05</b></a></top>') %n1 is object xmlNode %n2 is object xmlNode %n1 = %doc:selectSingleNode('top/a/b') call %n1:insertElementBefore('d', 'This comes before') %n2 = %n1:selectSingleNode('..') call %n2:addElement('e', 'This comes after') call %doc:print('top') end
The example results follow:
<top> <a> <c/> <d>This comes before</d> <b>05</b> <e>This comes after</e> </a> </top>
- The following fragment shows a way to insert a sibling node after the current node in cases where the document contents are not well known:
%nod2 = %nod1:selectSingleNode('following-sibling::node()') if %nod2 is null Then %nod2 = %nod1:aelectSingleNode('..') call %nod2:addElement('foo') else call %nod2:insertElementBefore('foo') end if
Request-cancellation errors
- The nod argument is the Root node.
- nod is a child of the Root node and XmlDoc already has an Element.
- The name argument violates the rules for an XML element name.
- name is prefixed, but the XmlDoc Namespace property value is None.
- name is prefixed and Namespace property value is On, but uri is missing and no declaration for prefix is 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 "Usage Notes for the InvalidChar property".
- The uri value 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".
- AddElement also adds an Element node. InsertElementBefore adds an Element as the immediately preceding sibling of the node pointed to by the method object; AddElement adds an Element as the last child of the node pointed to by the method object.
- These methods are useful for working with namespaces: