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

 

See also:

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