Automation Engine Script Guide > Ordered by Function > Read or Modify Objects > XML_INSERT_BEFORE

XML_INSERT_BEFORE

Script function: Creates a new XML element and inserts this in front of another element.

Syntax

XML_INSERT_BEFORE(parent element, reference element, name, value)

Syntax part	Description/format
Parent element	Reference to the element where the reference element is located. Format: script literal or script variable
Reference element	Reference to the element, in front of which the new element should be inserted. Must be located within the parent element. Format: script literal or script variable
Name	Name of the new element Format: script literal or script variable
Value	Value of the new element Format: script literal or script variable

Return code
Reference to the new element.

Notes

The script element inserts a new element in front of a specified existing element within the XML document that is open (XML_OPEN). The parent element, the reference element it contains, and the name including the value of the new element need to be specified.

The reference element entered must refer to a direct sub-element of the parent element. Otherwise, there will be a runtime error when the script element is executed.

The script element only changes the XML structure in the memory. The contents of the Documentation tab is not affected.

Please note that spaces are not permitted in the element name and lead to a runtime error.

Example

The following example opens a structured Documentation tab as an XML document. The new element 'New_Element' will be inserted before the sub-element 'SubChild2' within the parent element 'Child'.

Subsequently, all sub-elements of the parent element will be output and checked to see whether the element was successfully inserted.

:SET &XMLDOCU#=XML_OPEN(DOCU,,"@Details")

:IF &XMLDOCU# <> ""
:SET &PARENT# = XML_SELECT_NODE(&XMLDOCU#,"Child")
:SET &REF# = XML_SELECT_NODE(&XMLDOCU#,"Child/SubChild2")

:SET &NEW# = XML_INSERT_BEFORE(&PARENT#,&REF#,"New_Element","Test")

:SET &ELEMENT# = XML_GET_FIRST_CHILD(&PARENT#)
:WHILE &ELEMENT# <> ""
: SET &NAME# = XML_GET_NODE_NAME(&ELEMENT#)
: P 'Element: &NAME#'
: SET &ELEMENT# = XML_GET_NEXTSIBLING(&ELEMENT#)
:ENDWHILE

:ENDIF

:XML_CLOSE &XMLDOCU#

Result in the activation log:

2013-08-14 13:32:27 – U0020408 Element: SubChild1
2013-08-14 13:32:27 – U0020408 Element: New_Element
2013-08-14 13:32:27 – U0020408 Element: SubChild2

Script element	Description
XML_OPEN	Opens an XML document for processing.
:XML_CLOSE	Closes an XML document.