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)

Script Function and Parameters

  • XML_INSERT_BEFORE
    Creates a new XML element and inserts this before another element

  • Parent Element
    Reference to the element where the Reference Element is located.
    Format: 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.
    Format: script literal or script variable

  • Name
    Name of the new element
    Format: script literal or script variable
    Note: Do not use blanks in the element name as they may lead to a runtime error.

  • Value
    Value of the new element
    Format: script literal or script variable

Return Code

This script function returns the reference to the new element.

Example

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.

Screenshot showing the @Details Structured Documentation page with the Child1 element which incuds Sub-Child-A and Sub-Child-B, the Child2 element with the Sub-Child_C element, and Child3 with the Sub-Child-D element

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

Screenshot of the activation report of XML_INSERT_BEFORE that lists Sub-Child-A, New_Element, and Sub-Child-B

See also:

seealso

Script Functions for XML Elements

b