Inserts an XML element at a specified location in an XML document or add an attribute to an existing XML element.

Syntax:

XMLInsert (generation, I/O entry, element path, attribute, value [,before/after flag, reference element, auto convert])

Parameters:

generation – A number that represents the task's hierarchic position in the runtime task tree. 0 represents the current task, 1 its immediate ancestor, and so on.

I/O entry – A number that represents the sequence number of the I/O entry in the current task.

element path – A string representing the XML element path. If the element path includes a single element name, a root element is added. The XML element path syntax is:
/element name[[index]] [/element name[[index]]…]

where:

element name is the name of an XML element. You can assign an alias that is separated from the element name by a colon symbol (:), for example, al1:My_Element.

index is the index of a specified occurrence of an element that has multiple occurrences. The index value must be greater than 0. Negative values are invalid. When inserting an element, the attribute parameter has an empty string, you cannot specify the index for the rightmost element in the element path.

attribute – A string representing the attribute name that is added to the XML element specified by the element path. If this parameter has an empty string, an XML element is added, as specified by the element path.

value – An Alpha, or BLOB (Rich Edit) string type containing the value of the inserted element or attribute.

before/after flag (optional) – Represents one of the following values:

A – The element is added after the reference element.

B – The element is added before the reference element.

If this parameter is empty for an XML element, the XML element is added as the last element inside its parent element.

For an attribute, this parameter is ignored.

reference element (optional) – A string representing an XML element name used as a reference for the insertion of the new XML element. For an attribute, this parameter is ignored.

If there is no reference element value, the new element will be added as the first or last element depending on the before/after flag value. If this parameter is set to A, the element is added as the last element inside the parent element. If this parameter is set to B, the element is added as the first element inside the parent element.

auto convert (optional) – Enter one of the following logical values:

True – Converts the value into a valid XML string, which does not have the same effect as the XMLVal function.

False – Does not convert the value into an XML string.

Returns:

A numeric value. If a new element has been entered successfully, the function returns the index of the newly inserted element. If a new attribute has been inserted successfully, the function returns 0.

When the function fails, Magic xpa returns the following error codes, highlighted below:

-1 – Invalid I/O file

-2 – Inserted element or attribute alias is not defined

-3 – The I/O file not opened in Write mode

-4 – Element path not found

-6 – Attribute already defined for element

-7 – Invalid Before/After flag

-8 – Reference element not found

-9 – The document contains a root element. Multiple roots not permitted.

-10 – Invalid auto convert flag

-11 – Invalid path, non-valid index

-13 – Invalid alias, qualified name

-20 – Invalid XML file (XML parsing failed)

For a full list of error codes, see XML Error Codes.

Note:

This function will redecorate the XML with spaces.

Exceptions:

This function is not supported for Rich Client tasks.

Example:

XML Insert Examples

See also:

XML Namespaces

How Do I Retrieve / Update / Insert Data According to a Certain Path in an XML Document?

The Online and Rich Client Samples projects (program XM16 and RXM16)