XmlNode Class Methods

Add methods create a new node of the specific type, append this new node to the child list, and return this newly created node, while Insert methods add the node to the specified position.

In this section, we discuss the XmlNode methods. The methods are discussed in alphabetical order.

Syntax

AddAttribute(Name, Value);

Description

Use the AddAttribute method to add an attribute to an XmlNode. A reference to the newly created attribute is returned.

If you specify an attribute name that already exists, the new value you use replaces the existing value, and a reference to the attribute is returned.

Attributes added by the AddAttribute method appear in an arbitrary order in the generated XML.

Parameters

Field or Control	Definition
`Name`	Specify the name of the Attribute that you want to create, as a string.
`Value`	Specify the value of the Attribute that you want to create, as a string.

Returns

None.

Example

Here is a set of XML response code.

<?xml version="1.0"?> 
<myroot> 
   <postreqresponse> 
      <candidate> 
         <user> 
            <location scenery="great" density="low" blank="eh?"/> 
            
         </user> 
      </candidate> 
   </postreqresponse> 
</myroot>

Here's the PeopleCode that builds it.

Local XmlDoc &inXMLDoc;
Local XmlNode &postReqNode;
Local XmlNode &candidatesNode;
Local XmlNode &userNode;
Local XmlNode &locationNode;
Local XmlNode &sceneryAtt;
Local XmlNode &densityAtt;
Local XmlNode &blankAtt;
Local boolean &ret;

&inXMLDoc = CreateXmlDoc("<?xml version='1.0'?><myroot/>");

&postReqNode = &inXMLDoc.DocumentElement.AddElement("postreqresponse");
&candidatesNode = &postReqNode.AddElement("candidates");
&userNode = &candidatesNode.AddElement("user");
&locationNode = &userNode.AddElement("location");

&locationNode.AddAttribute("scenery", "great");
&locationNode.AddAttribute("density", "low");
&locationNode.AddAttribute("blank", "eh?");

Syntax

AddAttributeNS(NamespaceURI, AttributeName, Value)

where NamespaceURI can have one of the following forms:

URL.URLname

OR a string URL, such as

http://www.example.com/

Description

Use the AddAttributeNS method to add a namespace attribute to an XmlNode. The new attribute is appended to the list of child nodes.

A reference to the newly created attribute is returned.

If you specify an attribute name that already exists, the new value you use replaces the existing value, and a reference to the attribute is returned.

Parameters

Field or Control	Definition
`NamespaceURI`	Specify the URI that contains the Namespaces for the XmlDoc, as a string.
`AttributeName`	Specify the name of the Attribute that you want to create, as a string.
`Value`	Specify the value of the Attribute that you want to create, as a string.

Returns

None.

Example

Local XmlDoc &inXMLDoc;
Local XmlNode &childNode;

&inXMLDoc = CreateXmlDoc("<?xml version='1.0'?><myroot/>");
&childNode = &inXMLDoc.DocumentElement.AddElement("child");
&childNode.AddAttributeNS("http://www.example.com", "scenery", "great");

Syntax

AddCDataSection(Data)

Description

Use the AddCDataSection to add a CDATA section to an XmlNode.

CDATA sections may occur anywhere character data may occur; they are used to escape blocks of text containing characters which would otherwise be recognized as markup.

To insert a CDATA section at a particular place in the list of nodes, use the InsertCDataSection method instead.

A reference to the newly created CDATA section is returned.

Note: You cannot use this method with a SoapDoc object.

Parameters

Field or Control	Definition
`Data`	Specify the data to be included in the CDATA section as a string.

Returns

A reference to the newly created CDATA section.

Example

For example:

Local XmlDoc &inXMLDoc;
Local XmlNode &childNode;
Local XmlNode &cdataNode;

&inXMLDoc = CreateXmlDoc("<?xml version='1.0'?><myroot/>");
&childNode = &inXMLDoc.DocumentElement.AddElement("child");
&cdataNode = &childNode.AddCDataSection("testing...");

The preceding PeopleCode program produces the following:

<?xml version="1.0"?>
<myroot>
  <child>
    <![CDATA[testing...]]>
  </child>
</myroot>

Syntax

AddComment(Text)

Description

Use the AddComment method to add a comment to an XmlNode. The new attribute is appended to the list of child nodes.

To insert a comment at a particular place in the list of nodes, use the InsertComment method instead.

A reference to the newly created comment is returned.

Parameters

Field or Control	Definition
`Text`	Specify the text to be used as the comment, as a string.

Returns

A reference to the newly created comment.

Example

For example:

Local XmlDoc &inXMLDoc;
Local XmlNode &childNode;
Local XmlNode &commentNode;

&inXMLDoc = CreateXmlDoc("<?xml version='1.0'?><myroot/>");
&childNode = &inXMLDoc.DocumentElement.AddElement("child");
&commentNode = &childNode.AddComment("This is an example of a comment.");

The preceding PeopleCode program produces the following XML:

<?xml version="1.0"?>
<myroot>
  <child>
    <!--This is an example of a comment.-->
  </child>
</myroot>

Syntax

AddElement(TagName)

Description

Use the AddElement method to add an element to the XmlNode. The new element is appended to the list of child nodes.

To insert an element at a particular place in the list of nodes, use the InsertElement method instead.

A reference to the newly created element is returned.

Parameters

Field or Control	Definition
`TagName`	Specify the tag for the new element that you are adding, as a string.

Returns

A reference to the newly created element.

Example

For example:

Local XmlDoc &inXMLDoc;
Local XmlNode &childNode;

&inXMLDoc = CreateXmlDoc("<?xml version='1.0'?><myroot/>");
&childNode = &inXMLDoc.DocumentElement.AddElement("child");

The preceding PeopleCode program produces the following XML:

<?xml version="1.0"?>
<myroot>
  <child/>
</myroot>

Syntax

AddElementNS(NamespaceURI, TagName)

Where NamespaceURI can have one of the following forms:

URL.URLName

Or a string URL, such as:

http://www.example.com/

Description

Use AddElementNS to add a namespace element to an XmlNode. The new element is appendced to the list of child nodes.

To insert a Namespace element at a particular place in the list of nodes, use the InsertElementNS method instead. A reference to the newly created element is returned. If you specify an element name that already exists, the new value you use replaces the existing value, and a reference to the element is returned.

Parameters

Field or Control	Definition
`NamespaceURI`	Specify the URI that contains the Namespaces for the XmlDoc, as a string.
`TagName`	Specify the name of the Element that you want to create, as a string.

Returns

A reference to the newly created element if successful. If not successful, the IsNull property is set to True.

Example

Local XmlDoc &inXMLDoc;
Local XmlNode &childNode;

&inXMLDoc = CreateXmlDoc("<?xml version='1.0'?><myroot/>");
&childNode = &inXMLDoc.DocumentElement.AddElementNS("http://www.example.com", "child");

Syntax

AddEntityReference(Name)

Description

Use the AddEntityReference method to add an entity reference. An entity reference refers to the content of the named entity. The new entity reference is appended to the list of child nodes. In the generated XML, the entity reference is automatically prefaced with the '&' character and suffixed with a semi-colon.

The named entity must exist in the document type declaration (DTD).

To insert an entity reference at a particular place in the list of nodes, use the InsertEntityReference method instead.

Parameters

Field or Control	Definition
`Name`	Specify the name of the entity to which this reference refers to.

Returns

A reference to the newly created entity reference.

Example

For example:

Local XmlDoc &inXMLDoc;
Local XmlNode &childNode;
Local XmlNode &entityRef;

&inXMLDoc = CreateXmlDoc("<?xml version='1.0'?><myroot/>");
&childNode = &inXMLDoc.DocumentElement.AddElement("child");
&entityRef = &childNode.AddEntityReference("MyURL");

The preceding PeopleCode program produces the following XML:

<?xml version="1.0"?>
<myroot>
  <child>
&MyURL;  </child>
</myroot>

Syntax

AddNode(&XmlNode)

Description

Use the AddNode method to add an XmlNode to the XmlDoc. The new node is appended to the list of child nodes.

To insert a node at a particular place in the list of nodes, use the InsertNode method instead.

A reference to the newly created node is returned.

Parameters

Field or Control	Definition
`&XmlNode`	Specify an already instantiated XmlNode that you want to add.

Returns

None.

Example

Local XmlDoc &inXMLDoc, &firstDoc;
Local XmlNode &childNode;

&firstDoc = CreateXmlDoc("<?xml version='1.0'?><myroot><child><subchild/></child></myroot>");
&inXMLDoc = CreateXmlDoc("<?xml version='1.0'?><root/>");
&childNode = &firstDoc.DocumentElement.FindNode("/child");
&inXMLDoc.DocumentElement.AddNode(&childNode);

Syntax

AddProcessInstruction(Target, Data)

Description

Use the AddProcessInstruction method to add a processing instruction to an XmlNode. The new process instruction is appended to the end of the child list.

To insert a processing instruction at a particular place, use the InsertProcessInstruction method instead.

A reference to the newly created processing instruction is returned.

Note: You cannot use this method with a SoapDoc object.

Parameters

Field or Control	Definition
`Target`	Specify the application to which the instruction is directed, as a string.
`Data`	Specify the data used with the processing instruction.

Returns

A reference to the newly created processing instruction.

Example

For example:

Local XmlDoc &inXMLDoc;
Local XmlNode &procInst;

&inXMLDoc = CreateXmlDoc("<?xml version='1.0'?><myroot/>");
&procInst = &inXMLDoc.DocumentElement.AddProcessInstruction("xml-stylesheet", "href=""book.css"" type=""text/css""");

The preceding PeopleCode program produces the followingXML :

<?xml version="1.0"?>
<myroot>
  <?xml-stylesheet href="book.css" type="text/css"?>
</myroot>

Syntax

AddText(Data)

Description

Use the AddText method to add a text node to an XmlNode.

Note: A text node is not the same as a text declaration. The text declaration is added automatically with the CreateXmlDoc function. A text node just contains text within an XmlDoc.

To insert a text node at a particular place, use the InsertText method instead.

A reference to the newly created text node is returned.

Parameters

Field or Control	Definition
`Data`	Specify the data to be used as the text node, as a string.

Returns

A reference to the newly created text node.

Example

For example:

Local XmlDoc &inXMLDoc;
Local XmlNode &childNode;
Local XmlNode &textNode;

&inXMLDoc = CreateXmlDoc("<?xml version='1.0'?><myroot/>");
&childNode = &inXMLDoc.DocumentElement.AddElement("child");
&textNode = &childNode.AddText("This is text");

The preceding PeopleCode program produces the following XML:

<?xml version="1.0"?>
<myroot>
  <child>This is text</child>
</myroot>

Syntax

CopyNode(&Node)

Description

Use the CopyNode method to copy a node specified by &Node and all of its child nodes into the current node, as a child node. The new node is appended to the end of the list of child nodes. The specified node can belong to a different XmlDoc.

If you just want to copy a top-level node, without copying its children, you can just create a new node with the name of the node you want.

Parameters

Field or Control	Definition
`&Node`	Specify an already instantiated node that you want to copy.

Returns

None.

Example

Suppose that your XmlDoc has the following structure:

<?xml version="1.0"?>
<myroot>
  <child>
    <subchild/>
  </child>
</myroot>

The following PeopleCode copies the node child and copies it into another doc.

Local XmlDoc &inXMLDoc, &firstDoc;
Local XmlNode &childNode;

&firstDoc = CreateXmlDoc("<?xml version='1.0'?><myroot><child><subchild/></child></myroot>");
&inXMLDoc = CreateXmlDoc("<?xml version='1.0'?><root/>");
&childNode = &firstDoc.DocumentElement.FindNode("/child");
&inXMLDoc.DocumentElement.CopyNode(&childNode);

The following is the new structure:

<?xml version="1.0"?>
<root>
  <child>
    <subchild/>
  </child>
</root>

Syntax

FindNode(Path)

Description

Use the FindNode method to return a reference to an XmlNode.

The path is specified as the list of tag names, to the node that you want to find, each separated by a slash (/).

Parameters

Field or Control	Definition
`Path`	Specify the tag names up to and including the name of the node that you want returned, starting with a slash and each separated by a slash (/). This is known as the XPath query language. See XML Path Language (XPath) Version 1.0.

Field or Control

Definition

Path

Specify the tag names up to and including the name of the node that you want returned, starting with a slash and each separated by a slash (/). This is known as the XPath query language.

See XML Path Language (XPath) Version 1.0.

Returns

An XmlNode matching the path if successful. If not successful, the IsNull property on the XmlNode is set to True.

Example

Suppose your XmlDoc has the following structure:

<?xml version="1.0"?> 
<myroot> 
   <postreqresponse> 
      <candidate> 
         <user> 
            <location scenery="great" density="low" blank="eh?"/>
         </user> 
      </candidate> 
   </postreqresponse> 
</myroot>

You want to return a reference to the location attribute. Use the following Path to do it:

&XmlNode = &MyDoc.FindNode("/myroot/postreqresponse/candidate/user/location");

Syntax

FindNodes(Path)

Description

Use the FindNodes method to return a reference to an array containing all the XmlNodes that match the path.

The path is specified as the list of tag names, to the node that you want to find, each separated by a slash (/) when a namespace is not specified.

Parameters

Field or Control	Definition
`Path`	Specify the tag names up to and including the name of the node that you want returned, each separated by a slash (/). This is known as the XPath query language. See XML Path Language (XPath) Version 1.0.

Field or Control

Definition

Path

Specify the tag names up to and including the name of the node that you want returned, each separated by a slash (/). This is known as the XPath query language.

See XML Path Language (XPath) Version 1.0.

Returns

An array of XmlNode objects. If there is no match for the specified path, an array with 0 elements is returned.

Example

Using the following input:

<?xml version="1.0"?>
<PSmessage>
    <MsgData>
        <Transaction>
            <Record1 class="R">
                <Field1>one</Field1>
                <Field1>two</Field1>
                <Field1>three</Field1>
            </Record1>
        </Transaction>
    </MsgData>
</PSmessage>

The following PeopleCode program finds all of the Field1 nodes:

Local array of XmlNode &field1List;

&field1List = &inXMLDoc.DocumentElement.FindNodes("MsgData/Transaction/Record1/Field1");

If &field1List.Len = 0 Then
   /* do error processing, no nodes returned */
Else
   /* do regular processing */
End-If;

Syntax

GenXmlString()

Description

Use the GenXmlString method to generate an XML string of the XmlNode.

Parameters

None.

Returns

An XML String.

Example

&MyXML = &MyNode.GenXmlString();

Syntax

GetAttributeName(Index)

Description

Use the GetAttributeName method to return the specified attribute.

Parameters

Field or Control	Definition
`Index`	Specify an integer representing the attribute you want to access.

Returns

A string.

Example

Local XmlDoc &inXMLDoc;
Local string &attName;

&inXMLDoc = CreateXmlDoc("<?xml version='1.0'?><root/>");
&inXMLDoc.DocumentElement.AddAttribute("name", "Joe");
&inXMLDoc.DocumentElement.AddAttribute("address", "1234 West Eastland");

&attName = &inXMLDoc.DocumentElement.GetAttributeName(2);

Syntax

GetAttributeValue({Name | Index})

Description

Use the GetAttributeValue method to return the specific attribute value, given an attribute name. The attribute name is case-sensitive, so you must specify the exact name.

Parameters

Field or Control	Definition
`Name` \| `Index`	Specify the name or index of the attribute whose value you want to access.

Returns

A string containing the value of the specified attribute.

Example

Local XmlDoc &inXMLDoc;
Local string &attName;
Local string &attValue;

&inXMLDoc = CreateXmlDoc("<?xml version='1.0'?><root/>");
&inXMLDoc.DocumentElement.AddAttribute("name", "Joe");
&inXMLDoc.DocumentElement.AddAttribute("address", "1234 West Eastland");

&attName = &inXMLDoc.DocumentElement.GetAttributeName(2);
&attValue = &inXMLDoc.DocumentElement.GetAttributeValue(&attName);

Syntax

GetCDataValue()

Description

Use the GetCDataValue method to return the value of the first CDATA section in an XmlNode.

Parameters

None.

Returns

A reference to the value of the first CDATA section as a string.

Example

Local XmlDoc &inXMLDoc;
Local XmlNode &dataNode;
Local XmlNode &cdataNode;
Local string &theData;

&inXMLDoc = CreateXmlDoc("<?xml version='1.0'?><root/>");
&dataNode = &inXMLDoc.DocumentElement.AddElement("data");
&cdataNode = &dataNode.AddCDataSection("this is a bunch of text");

&theData = &dataNode.GetCDataValue();

Syntax

GetCDataValues()

Description

Use the GetCDataValues method to return an array of string containing the values of the CDATA section in an XmlNode.

Parameters

None.

Returns

An array of string.

Example

Local XmlDoc &inXMLDoc;
Local XmlNode &dataNode;
Local XmlNode &cdataNode;
Local array of string &theData;

&inXMLDoc = CreateXmlDoc("<?xml version='1.0'?><root/>");
&dataNode = &inXMLDoc.DocumentElement.AddElement("data");
&cdataNode = &dataNode.AddCDataSection("this is a bunch of text");
&cdataNode = &dataNode.AddCDataSection("more text");
&cdataNode = &dataNode.AddCDataSection("still more text");

&theData = &dataNode.GetCDataValues();

Syntax

GetChildNode(index)

Description

Use the GetChildNode method to return the specified child node of an XmlNode.

Parameters

Field or Control	Definition
`Index`	Specify an integer representing the child node that you want to access.

Returns

A reference to an XmlNode. If the specified XmlNode isn't found, the IsNull property for the XmlNode is set to True.

Example

Local XmlDoc &inXMLDoc;
Local XmlNode &dataNode;

&inXMLDoc = CreateXmlDoc("<?xml version='1.0'?><root/>");
&dataNode = &inXMLDoc.DocumentElement.AddElement("data");
&dataNode = &inXMLDoc.DocumentElement.AddElement("data2");

&dataNode = &inXMLDoc.DocumentElement.GetChildNode(2);

Syntax

GetElement()

Description

Use the GetElement method to return the first child element node in the list of child nodes.

Parameters

None.

Returns

A reference to an element.

Example

Local XmlDoc &inXMLDoc;
Local XmlNode &dataNode;

&inXMLDoc = CreateXmlDoc("<?xml version='1.0'?><root/>");
&dataNode = &inXMLDoc.DocumentElement.AddElement("data");
&dataNode = &inXMLDoc.DocumentElement.AddElement("data2");

&dataNode = &inXMLDoc.DocumentElement.GetElement();

Syntax

GetElements()

Description

Use the GetElements method to return an array of all the XmlNode objects that are elements.

Parameters

None.

Returns

An array of XmlNode of all the element nodes. If there are no element nodes, an array with 0 elements is returned.

Example

Local XmlDoc &inXMLDoc;
Local XmlNode &dataNode;
Local array of XmlNode &dataList;

&inXMLDoc = CreateXmlDoc("<?xml version='1.0'?><root/>");
&dataNode = &inXMLDoc.DocumentElement.AddElement("data");
&dataNode = &inXMLDoc.DocumentElement.AddElement("data2");

&dataList = &inXMLDoc.DocumentElement.GetElements();

If &dataList.Len = 0 Then
   /* do error processing, no nodes returned */
Else
   /* do regular processing */
End-If;

Syntax

GetElementsByTagName(TagName)

Description

Use the GetElementsByTagName method to return an array of XmlNode objects that match the specified tag name.

Parameters

Field or Control	Definition
`TagName`	Specify the tag name that you want to look for.

Returns

An array of XmlNode. If you specify an invalid tag name, the returned array has 0 elements.

Example

Using the following input:

<?xml version="1.0"?>
<PSmessage>
    <MsgData>
        <Transaction>
            <Record1 class="R">
                <Field1>one</Field1>
                <Field1>two</Field1>
                <Field1>three</Field1>
            </Record1>
        </Transaction>
    </MsgData>
</PSmessage>

The following PeopleCode program finds all Field1 nodes:

Local array of XmlNode &field1List;

&field1List = &inXMLDoc.DocumentElement.GetElementsByTagName("Field1");

If &field1List.Len = 0 Then
   /* do error processing, no nodes returned */
Else
   /* do regular processing */
End-If;

Syntax

GetElementsByTagNameNS(NamespaceURI, TagName)

Where NamespaceURI can have one of the following forms:

URL.URLName

Or a string URL, such as:

http://www.example.com/

Description

Use the GetElementsByTagNameNS method to return an array of XmlNode objects that match the specified namespace and qualified name.

Parameters

Field or Control	Definition
`NamespaceURI`	Specify the URI that contains the Namespace for the XmlDoc, as a string.
`TagName`	Specify the name of the element that you want to retrieve.

Returns

An array of XmlNode. If you specify an invalid NamespaceURI, the returned array has 0 elements.

Example

Using the following input:

<?xml version="1.0"?>
<Psmessage xmlns="http://www.example.com">
    <MsgData>
        <Transaction>
            <Record1 class="R">
                <Field1>one</Field1>
                <Field1>two</Field1>
                <Field1>three</Field1>
            </Record1>
        </Transaction>
    </MsgData>
</PSmessage>

The following PeopleCode program finds all Field1 nodes:

Local array of XmlNode &field1List;

&field1List = &inXMLDoc.DocumentElement.GetElementsByTagNameNS("http://www.example.com", "Field1");

If &field1List.Len = 0 Then
   /* do error processing, no nodes returned */
Else
   /* do regular processing */
End-If;

Syntax

InsertCDataSection(Data, Position)

Description

Use the InsertCDataSection method to insert a CDATA section in an XmlNode, at the location specified by Position.

Note: You cannot use this method with a SoapDoc object.

Parameters

Field or Control	Definition
`Data`	Specify the data for the CDATA section as a string.
`Position`	Specify where you want to insert the CDATA Section, as a number.

Returns

A reference to the newly created CDATA section.

Example

For example:

Local XmlDoc &inXMLDoc;
Local XmlNode &dataNode;
Local XmlNode &cdataNode;

&inXMLDoc = CreateXmlDoc("<?xml version='1.0'?><root/>");
&dataNode = &inXMLDoc.DocumentElement.AddElement("data");
&cdataNode = &dataNode.AddCDataSection("this is a bunch of text");
&cdataNode = &dataNode.AddCDataSection("still more text");

&cdataNode = &dataNode.InsertCDataSection("more text", 2);

This is the XML document before the insert:

<?xml version="1.0"?>
<root>
  <data>
    <![CDATA[this is a bunch of text]]>
    <![CDATA[still more text]]>
  </data>
</root>

This is the XML document after the insert:

<?xml version="1.0"?>
<root>
  <data>
    <![CDATA[this is a bunch of text]]>
    <![CDATA[more text]]>
    <![CDATA[still more text]]>
  </data>
</root>

Syntax

InsertComment(Data, Position)

Description

Use the InsertComment method to insert a comment in an XmlNode at the location specified by Position.

Parameters

Field or Control	Definition
`Data`	Specify the data for the comment as a string.
`Position`	Specify where you want to insert the comment, as a number.

Returns

A reference to the newly created comment.

Example

For example:

Local XmlDoc &inXMLDoc;
Local XmlNode &dataNode;
Local XmlNode &commentNode;

&inXMLDoc = CreateXmlDoc("<?xml version='1.0'?><root/>");
&dataNode = &inXMLDoc.DocumentElement.AddElement("data");
&commentNode = &dataNode.AddComment("this is a comment");
&commentNode = &dataNode.AddComment("still another comment");

&commentNode = &dataNode.InsertComment("more comments", 2);

This is the XML document before the insert:

<?xml version="1.0"?>
<root>
  <data>
    <!--this is a comment-->
    <!--still another comment-->
  </data>
</root>

This is the XML document after the insert:

<?xml version="1.0"?>
<root>
  <data>
    <!--this is a comment-->
    <!--more comments-->
    <!--still another comment-->
  </data>
</root>

Syntax

InsertElement(TagName, Position)

Description

Use the InsertElement method to insert an element in an XmlNode at the location specified by Position.

Parameters

Field or Control	Definition
`TagName`	Specify the tagname for the element as a string.
`Position`	Specify where you want to insert the element, as a number.

Returns

A reference to the newly created element.

Example

For example:

Local XmlDoc &inXMLDoc;
Local XmlNode &dataNode;
Local XmlNode &elementNode;

&inXMLDoc = CreateXmlDoc("<?xml version='1.0'?><root/>");
&dataNode = &inXMLDoc.DocumentElement.AddElement("data");
&elementNode = &dataNode.AddElement("first");
&elementNode = &dataNode.AddElement("second");

&commentNode = &dataNode.InsertElement("third", 2);

This is the XML document before the insert:

<?xml version="1.0"?>
<root>
  <data>
    <first/>
    <second/>
  </data>
</root>

This is the XML document after the insert:

<?xml version="1.0"?>
<root>
  <data>
    <first/>
    <third/>
    <second/>
  </data>
</root>

Syntax

InsertElementNS(NamespaceURI, TagName, Position)

where NamespaceURI can have one of the following forms:

URL.URLname

OR a string URL, such as

http://www.example.com/

Description

Use InsertElementNS to insert a new element in an XmlNode, at the location specified by Position.

Parameters

Field or Control	Definition
`NamespaceURI`	Specify the URI that contains the Namespaces for the XmlDoc.
`TagName`	Specify the name of the element that you want to create, as a string.
`Position`	Specify where you want to insert the element, as a number.

Returns

A reference to the newly created element.

Example

For example:

Local XmlDoc &inXMLDoc;
Local XmlNode &dataNode;
Local XmlNode &elementNode;

&inXMLDoc = CreateXmlDoc("<?xml version='1.0'?><root xmlns='http://www.example.com'/>");
&dataNode = &inXMLDoc.DocumentElement.AddElement("data");
&elementNode = &dataNode.AddElement("first");
&elementNode = &dataNode.AddElement("second");

&elementNode = &dataNode.InsertElementNS("http://www.example.com", "third", 2);

This is the XML document before the insert:

<?xml version="1.0"?>
<root xmlns="http://www.example.com">
  <data>
    <first/>
    <second/>
  </data>
</root>

This is the XML document after the insert:

<?xml version="1.0"?>
<root xmlns="http://www.example.com">
  <data>
    <first/>
    <third/>
    <second/>
  </data>
</root>

Syntax

InsertEntityReference(Name, Position)

Description

Use the InsertEntityReference method to add an entity reference. An entity reference refers to the content of the named entity.

Parameters

Field or Control	Definition
`Name`	Specify the name of the entity to which this reference refers to.
`Position`	Specify where you want to insert the entity reference, as a number.

Returns

A reference to the newly created entity reference.

Example

For example:

Local XmlDoc &inXMLDoc;
Local XmlNode &dataNode;
Local XmlNode &entityRef;

&inXMLDoc = CreateXmlDoc("<?xml version='1.0'?><root/>");
&dataNode = &inXMLDoc.DocumentElement.AddElement("data");
&entityRef = &dataNode.AddEntityReference("first");
&entityRef = &dataNode.AddEntityReference("second");

&entityRef = &dataNode.InsertEntityReference("third", 2);

This is the XML document before the insert:

<?xml version="1.0"?>
<root>
  <data>
&first;&second;  </data>
</root>

This is the XML document after the insert:

<?xml version="1.0"?>
<root>
  <data>
&first;&third;&second;  </data>
</root>

Syntax

InsertNode(&NewNode, {&RefNode | Position})

Description

Use the InsertNode method to insert a new node. The node is inserted either before the node specified by &RefNode, or at the location specified by Position.

&NewNode refers to an already instantiated XmlNode object. You must create the node before you can insert it.

&RefNode refers to an already instantiated XmlNode object.

Parameters

Field or Control	Definition
`&NewNode`	Specify the name of an already instantiated XmlNode that you want to insert.
`&RefNode` \| `Position`	Specify either the name of an existing node or the location where you want the node to be inserted.

Returns

A reference to the newly inserted node.

Example

The following PeopleCode program inserts a node using a position:

Local XmlDoc &inXMLDoc, &firstDoc;
Local XmlNode &childNode;

&firstDoc = CreateXmlDoc("<?xml version='1.0'?><myroot><third><child/></third></myroot>");
&inXMLDoc = CreateXmlDoc("<?xml version='1.0'?><root><first/><second/></root>");
&childNode = &firstDoc.DocumentElement.FindNode("third");

&inXMLDoc.DocumentElement.InsertNode(&childNode, 2);

The following PeopleCode program inserts a node using a reference node:

Local XmlDoc &inXMLDoc, &firstDoc;
Local XmlNode &childNode, &secondNode;

&firstDoc = CreateXmlDoc("<?xml version='1.0'?><myroot><third><child/></third></myroot>");
&inXMLDoc = CreateXmlDoc("<?xml version='1.0'?><root><first/><second/></root>");
&childNode = &firstDoc.DocumentElement.FindNode("third");
&secondNode = &inXMLDoc.DocumentElement.FindNode("second");

&inXMLDoc.DocumentElement.InsertNode(&childNode, &secondNode);

The following is the XML document before the insert:

<?xml version="1.0"?>
<root>
  <first/>
  <second/>
</root>

The following is the XML document after the insert:

<?xml version="1.0"?>
<root>
  <first/>
  <third>
    <child/>
  </third>
  <second/>
</root>

Syntax

InsertProcessInstruction(Target, Data, Position)

Description

Use the InsertProcessInstruction method to insert a processing instruction to an XmlNode at the location specified by Position.

Note: Youcannot use this method with a SoapDoc object.

Parameters

Field or Control	Definition
`Target`	Specify the application to which the instruction is directed, as a string.
`Data`	Specify the data to be used with the instruction.
`Position`	Specify where you want to insert the process instruction, as a number.

Returns

A reference to the newly created processing instruction.

Example

For example:

Local XmlDoc &inXMLDoc;
Local XmlNode &procInst;

&inXMLDoc = CreateXmlDoc("<?xml version='1.0'?><root/>");
&procInst = &inXMLDoc.DocumentElement.AddProcessInstruction("first", "firstvalue");
&procInst = &inXMLDoc.DocumentElement.AddProcessInstruction("second", "secondvalue");

&procInst = &inXMLDoc.DocumentElement.InsertProcessInstruction("third", "thirdvalue", 2);

This is the XML document before the insert:

<?xml version="1.0"?>
<root>
  <?first firstvalue?>
  <?second secondvalue?>
</root>

This is the XML document after the inser:

<?xml version="1.0"?>
<root>
  <?first firstvalue?>
  <?third thirdvalue?>
  <?second secondvalue?>
</root>

Syntax

InsertText(Data, Position)

Description

Use the InsertText method to insert a text node. The node is inserted at the location indicated by Position.

Note: A text node is not the same as a text declaration. The text declaration is added automatically with the CreateXmlDoc function. A text node just contains text within an XmlDoc.

Parameters

Field or Control	Definition
`Data`	Specify the data to be used for the text node, as a string.
`Position`	Specify where you want to insert the text ndoe, as a number.

Returns

A reference to the newly created text node.

Example

For example:

Local XmlDoc &inXMLDoc;
Local XmlNode &textNode;

&inXMLDoc = CreateXmlDoc("<?xml version='1.0'?><root/>");
&textNode = &inXMLDoc.DocumentElement.AddText("first text");
&textNode = &inXMLDoc.DocumentElement.AddText("second text");

&textNode = &inXMLDoc.DocumentElement.InsertText("third text", 2);

This is the XML document before the insert:

<?xml version="1.0"?>
<root>
first textsecond text</root>

This is the XML document after the insert:

<?xml version="1.0"?>
<root>
first textthird textsecond text</root>

Syntax

RemoveAllChildNode()

Description

Use the RemoveAllChildNode method to remove all child nodes for an XmlNode.

Parameters

None.

Returns

None.

Example

For example:

Local XmlDoc &inXMLDoc;
Local XmlNode &elementNode;

&inXMLDoc = CreateXmlDoc("<?xml version='1.0'?><root/>");
&elementNode = &inXMLDoc.DocumentElement.AddElement("first");
&elementNode = &inXMLDoc.DocumentElement.AddElement("second");
&elementNode = &inXMLDoc.DocumentElement.AddElement("third");

&inXMLDoc.DocumentElement.RemoveAllChildNode();

This is the XML document before the removal:

<?xml version="1.0"?>
<root>
  <first/>
  <second/>
  <third/>
</root>

This is the XML document after the removal:

<?xml version="1.0"?>
<root/>

Syntax

RemoveChildNode({Position | Node})

Description

Use the RemoveChildNode method to remove the child node in an XmlNode specified by Node, or located at Position.

Parameters

Field or Control	Definition
`Position` \| `Node`	Specify the child node that you want to delete, either using its position number or its name.

Returns

A reference to the removed XmlNode.

Example

The following PeopleCode program uses a position:

Local XmlDoc &inXMLDoc;
Local XmlNode &elementNode, &removedNode;

&inXMLDoc = CreateXmlDoc("<?xml version='1.0'?><root/>");
&elementNode = &inXMLDoc.DocumentElement.AddElement("first");
&elementNode = &inXMLDoc.DocumentElement.AddElement("second");
&elementNode = &inXMLDoc.DocumentElement.AddElement("third");

&removedNode = &inXMLDoc.DocumentElement.RemoveChildNode(2);

The following PeopleCode program uses a reference node:

Local XmlDoc &inXMLDoc;
Local XmlNode &elementNode, &removedNode;

&inXMLDoc = CreateXmlDoc("<?xml version='1.0'?><root/>");
&elementNode = &inXMLDoc.DocumentElement.AddElement("first");
&elementNode = &inXMLDoc.DocumentElement.AddElement("second");
&elementNode = &inXMLDoc.DocumentElement.AddElement("third");

&elementNode = &inXMLDoc.DocumentElement.FindNode("/second");
&removedNode = &inXMLDoc.DocumentElement.RemoveChildNode(&elementNode);

This is the XML document before the removal:

<?xml version="1.0"?>
<root>
  <first/>
  <second/>
  <third/>
</root>

This is XML document after the removal:

<?xml version="1.0"?>
<root>
  <first/>
  <third/>
</root>