lr_xml_insert

XML Functions (lr_xml)

Inserts a new XML fragment into an XML string.

int lr_xml_insert( <List of specifications> [, <List of optional specifications> ] [, LAST]);
List of specifications

For the following list of required specifications, use the following string format:"Specification=value"

XML: the XML Input String to query
ResultParam: The output parameter containing the XML data after inserting the new fragment
Query: the XML Query on the input string XML.

Choose one of the following:
XmlFragment: the string to insert. It can be a new element or a attribute of an existing element.
or:
XmlFragmentParam: the name of the parameter containing the string value to insert

List of optional specifications

For the following list of optional specifications, use the following string format:"Specification=value"

SelectAll: If "yes", all elements matching the query will be processed. If "no", only the first match will be processed. Default is "no". See Multiple Query Matching

Position: the position to insert the XML fragment. Choose one of:

  • before: place the fragment before the tag returned by a Query
  • after: place the fragment after the tag returned by a Query (this is the default value)
  • child: place the fragment as a child of the tag returned by a Query
  • attribute: indicates an attribute of an element returned by a Query

NotFound: See Continue on Error

LAST A marker which indicates the end of the List of optional specifications

The lr_xml_insert function queries the XML input string XML for values matching the Query criteria. It then inserts XmlFragment or XmlFragmentParam at the position (or positions) in the XML string returned by the Query.

Position specifies whether the insertion is done before or after the point returned. Additionally, the childPosition specifies that the fragment is inserted before the end of the tag found by the query. For example, if the input string is

<a>53</a>

an inserted fragment ("<b>ZZ</b>") in the child position will result in the string:

<a>53<b>ZZ</b></a>

The resulting string after insertion is placed in ResultParam, using the source document encoding. The output preserves the XML Character Encoding of the original document, independent of the input encoding. The input encoding uses the client's local encoding.

Return Values

See Return Values

Parameterization

See Parameterization

Example

The following example inserts an "extension" tag to an employee record. It searches the input string xml_input for the tag "<employee>" and inserts an XML fragment which contains the extension information. ("XmlFragment=<extension>2145</extension>").

Note that the Position specification is child, so the inserted string fragment is placed just before the employee tag ends (at "</employee>").

The resulting string is contained in the ResultParam parameter, Result.

For more examples of the use of lr_xml_insert, see Examples: common actions.

#include "as_web.h"

char *xml_input = 
"<acme_org>"
     "<employee>"
          " <name>John Smith</name>"
          "<cubicle>227</cubicle>"
     "</employee>"
"</acme_org>";

Action() {

     lr_save_string(xml_input, "XML_Input_Param");

     lr_xml_insert("XML={XML_Input_Param}", "ResultParam=Result",
          "XmlFragment=<extension>2145</extension>", 
          "Query=/acme_org/employee", 
          "Position=child", LAST );

     lr_output_message(lr_eval_string("String after insertion: {Result}"));

     return 0;
}

Example: Output:
Action.c(15): "lr_xml_insert" was successful, 1 match processed
Action.c(20): String after insertion:
<acme_org><employee> <name>John Smith</name>
<cubicle>227</cubicle><extension>2145</extension>
</employee></acme_org>