Microsoft XML Core Services (MSXML) 5.0 for Microsoft Office - DOM Reference

replaceChild Method

Replaces the specified old child node with the supplied new child node.

[Script]

Script Syntax

var objXMLDOMNode = oXMLDOMNode.replaceChild(newChild, oldChild);

Parameters

newChild
An object. The address of the new child that is to replace the old child. If Null, oldChild is removed without a replacement.
oldChild
An object. The address of the old child that is to be replaced by the new child.

Return Value

An object. Returns the old child that is replaced.

Example

The following example creates a new IXMLDOMNode object, newElem, and replaces the specified child node with newElem.

var xmlDoc = new ActiveXObject("Msxml2.DOMDocument.5.0");
var root;
var newElem;
xmlDoc.async = false;
xmlDoc.load("books.xml");
if (xmlDoc.parseError.errorCode <> 0) {
   var myErr = xmlDoc.parseError;
   alert("You have error " + myErr.reason);
} else {
   root = xmlDoc.documentElement;
   newElem = xmlDoc.createElement("PAGES");
   root.childNodes.item(1).replaceChild(newElem,    root.childNodes.item(1).childNodes.item(0));
   alert(root.childNodes.item(1).xml);
}
[Visual Basic]

Visual Basic Syntax

Set objXMLDOMNode = oXMLDOMNode.replaceChild(newChild, oldChild)

Parameters

newChild
An object. The address of the new child that is to replace the old child. If Null, the oldChild parameter is removed without a replacement.
oldChild
An object. The address of the old child that is to be replaced by the new child.

Return Value

An object. Returns the old child that is replaced.

Example

The following Microsoft® Visual Basic® example creates a new IXMLDOMNode object, newElem, and replaces the specified child node with newElem.

Dim xmlDoc As New Msxml2.DOMDocument50
Dim root As IXMLDOMElement
Dim newElem As IXMLDOMElement
xmlDoc.async = False
xmlDoc.Load ("books.xml")
If (xmlDoc.parseError.errorCode <> 0) Then
   Dim myErr
   Set myErr = xmlDoc.parseError
   MsgBox("You have error " & myErr.reason)
Else
   Set root = xmlDoc.documentElement
   Set newElem = xmlDoc.createElement("PAGES")
   root.childNodes.Item(1).replaceChild newElem,    root.childNodes.Item(1).childNodes.Item(0)
   MsgBox root.childNodes.Item(1).xml
End If
[C/C++]

C/C++ Syntax

HRESULT replaceChild(
    IXMLDOMNode *newChild,
    IXMLDOMNode *oldChild,
    IXMLDOMNode **outOldChild);

Parameters

newChild [in]
The address of the new child that is to replace the old child. If Null, the oldChild parameter is removed without a replacement.
oldChild [in]
The address of the old child that is to be replaced by the new child.
outOldChild [out, retval]
The old child that is replaced. If Null, no object is created.

C/C++ Return Values

S_OK
The value returned if successful.
E_INVALIDARG
The value returned if the newChild node cannot be inserted as a child of this node, when the specified oldChild is not a child of this node, or if the oldChild parameter is Null.
E_FAIL
The value returned if an error occurs.

Remarks

This operation depends on the value of the nodeType property.

NODE_ATTRIBUTE

This operation depends on the value of the newChild parameter:

NODE_ATTRIBUTE, NODE_CDATA_SECTION, NODE_COMMENT, NODE_DOCUMENT, NODE_DOCUMENT_TYPE, NODE_ELEMENT, NODE_ENTITY, NODE_NOTATION, NODE_PROCESSING_INSTRUCTION Returns an error. These node types cannot be children of an attribute.
NODE_DOCUMENT_FRAGMENT Replaces oldChild with the children of the document fragment in newChild and returns oldChild.
NODE_ENTITY_REFERENCE, NODE_TEXT Replaces the specified oldChild with the supplied newChild and returns oldChild.
NODE_CDATA_SECTION, NODE_COMMENT, NODE_ENTITY, NODE_NOTATION, NODE_PROCESSING_INSTRUCTION, NODE_TEXT Returns an error. These node types either cannot have children or their children are read-only.

NODE_DOCUMENT

This operation depends on the value of the newChild parameter.

NODE_ATTRIBUTE, NODE_CDATA_SECTION, NODE_DOCUMENT, NODE_ENTITY, NODE_ENTITY_REFERENCE, NODE_NOTATION, NODE_TEXT Returns an error. These nodes are not valid as children of a document node.
NODE_COMMENT, NODE_PROCESSING_INSTRUCTION Replaces the specified oldChild with the supplied newChild and returns oldChild.
NODE_DOCUMENT_TYPE, NODE_ELEMENT Replaces oldChild with newChild and returns oldChild. By definition, an XML document (the document node) can have only a single child. Therefore, an error is returned if the document node already has a child.
NODE_DOCUMENT_FRAGMENT Replaces the specified oldChild with the children of the document fragment (newChild) and returns oldChild. The insert operations are subject to the rules for child nodes and can fail if the document fragment children represent node types that cannot be inserted.
NODE_DOCUMENT_TYPE Returns an error. The document type is read-only.

NODE_DOCUMENT_FRAGMENT

This operation depends on the value of the newChild parameter.

NODE_ATTRIBUTE, NODE_DOCUMENT, NODE_DOCUMENT_TYPE Returns an error. These nodes types are not valid as children of a document fragment.
NODE_CDATA_SECTION, NODE_COMMENT, NODE_ELEMENT, NODE_ENTITY_REFERENCE, NODE_PROCESSING_INSTRUCTION, NODE_TEXT Replaces the specified oldChild with the supplied newChild and returns oldChild.
NODE_DOCUMENT_FRAGMENT Replaces the specified oldChild with the children of the document fragment (newChild) and returns oldChild. The insert operations are subject to the rules for child nodes and can fail if the document fragment children represent node types that cannot be inserted.
NODE_ENTITY, NODE_NOTATION Returns an error. Entities and notations are read-only and cannot be inserted into a document.

NODE_ELEMENT

This operation depends on the value of the newChild parameter.

NODE_CDATA_SECTION, NODE_COMMENT, NODE_ELEMENT, NODE_ENTITY_REFERENCE, NODE_TEXT, NODE_PROCESSING_INSTRUCTION Replaces the specified oldChild with newChild and returns oldChild.
NODE_ATTRIBUTE, NODE_DOCUMENT, NODE_DOCUMENT_TYPE, NODE_ENTITY, NODE_NOTATION Returns an error. These node types cannot be children of an element node.
NODE_DOCUMENT_FRAGMENT Replaces the specified oldChild with the children of the document fragment (newChild) and returns oldChild. The insert operations are subject to the rules for child nodes and can fail if the document fragment children represent node types that cannot be inserted.
NODE_ENTITY_REFERENCE Returns an error. Although the child nodes of an entity reference are the expanded entity, the children cannot be modified.

To view reference information for Visual Basic, C/C++, or Script only, click the Language Filter button Language Filter in the upper-left corner of the page.

See Also

nodeType Property

Applies to: IXMLDOMAttribute | IXMLDOMCDATASection | IXMLDOMCharacterData | IXMLDOMComment | DOMDocument | IXMLDOMDocumentFragment | IXMLDOMDocumentType | IXMLDOMElement | IXMLDOMEntity | IXMLDOMEntityReference | IXMLDOMNode | IXMLDOMNotation | IXMLDOMProcessingInstruction | IXMLDOMText