XML_INSERT_BEFORE

Use the XML_INSERT_BEFORE script function to insert a new element before a specified existing and open element within the XML document.

Important! The XML structure is modified in the memory only. You do not see the changes of XML_INSERT_BEFORE on the structured documentation page.

Tip: Use the XML_OPEN script function to open the XML document. For more information, see XML_OPEN.

Syntax

XML_INSERT_BEFORE (Parent Element, Reference Element, Name, Value)

Parameters

Parameter	Description	Format
Parent Element	Reference to the element where the Reference Element is located.	Script literal or script variable
Reference Element	Reference to the element before which the new element should be inserted. It must refer to a direct sub-element of the Parent Element—otherwise, a runtime error occurs when the script element is executed.	Script literal or script variable
Name	Name of the new element. Note: Do not use blanks in the element name as they may lead to a runtime error.	Script literal or script variable
Value	Value of the new element.	Script literal or script variable

Return Codes

This script function returns the reference to the new element.

Examples

The following example opens the @Details Structured Documentation page as an XML document. The new element 'New_Element' is inserted before the sub-element 'Sub-Child-B' within the parent element 'Child1'. Subsequently, all sub-elements of the parent element are output and verified to ensure the element was successfully inserted:

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

:IF &XMLDOCU# <> ""

: SET &PARENT# = XML_SELECT_NODE(&XMLDOCU#,"Child1")

: SET &REF# = XML_SELECT_NODE(&XMLDOCU#,"Child1/Sub-Child-B")

: 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#

The activation report shows the following result: