Microsoft XML 2.5 SDK


 

IXMLDOMDocument::save Method

[This is preliminary documentation and subject to change.]

Saves an XML document to the specified location.

Visual Basic Syntax

oXMLDOMDocument.save(destination)

C/C++ Syntax

HRESULT save(

    VARIANT varObject);

Parameters

varObject

[in]
Type of object to save. This object can represent a file name, an ASP Response object, an XML document object, or a custom object that supports persistence. For more information, see the Remarks section below.

C/C++ Return Values

S_OK

Success

XML_BAD_ENCODING

The document contains a character that does not belong in the specified encoding. The character must use a numeric entity reference. For example, the Japanese Unicode character 20013 does not fit into the encoding windows-1250 (which is the Central European alphabet) and therefore must be represented in markup as the numeric entity reference 中 or 中. This version of save does not automatically convert characters to the numeric entity references.

E_INVALIDARG

A string was provided but it is not a valid file name.

E_ACCESSDENIED

Save operation is not permitted.

E_OUTOFMEMORY

Save does need to allocate buffers.

(Other values)

Any other file system error can be returned in the save(string) case.

Remarks

The behavior differs based on the object specified by the varObject parameter.

Object Description
String Specifies the file name. Note that this must be a file name, rather than a URL. The file is created if necessary and the contents are entirely replaced with the contents of the saved document. This mode is not intended for use from a secure client such as Internet Explorer because the method always returns E_ACCESSDENIED and cannot be enabled through user security settings. For example:

dim xmldoc

set xmldoc = Server.CreateObject("Microsoft.XMLDOM")

xmldoc.load(Request)

xmldoc.save(Server.MapPath("sample.xml"))
ASP Response Object Sends the document back to the client that invoked the ASP script. For example:

dim xmldoc

set xmldoc = Server.CreateObject("Microsoft.XMLDOM")

xmldoc.load(Server.MapPath("sample.xml"))

xmldoc.save(Response)
XML Document Object Duplicates the original document. It is the equivalent of saving the document and reparsing it. The document goes through full persistence through XML markup, thereby testing the persistability of your XML document. For example:

<script language="jscript">

    var xmldoc1 = CreateObject("Microsoft.XMLDOM");

    var xmldoc2 = CreateObject("Microsoft.XMLDOM");

    xmldoc1.load("sample.xml");

    xmldoc1.save(xmldoc2.XMLDocument);

</script>
Custom object supporting persistence Any other custom COM object that supports QueryInterface for IStream, IPersistStream, or IPersistStreamInit can also be provided here and the document will be saved accordingly. In the IStream case, the IStream::Write method will be called as it saves the document; in the IPersistStream case, IPersistStream::Load will be called with an IStream that supports the Read, Seek, and Stat methods.

External entity references in DOCTYPE, ENTITY, NOTATION, and xml namespace declarations are not changed; they point to the original document. A saved XML document might not load if the URLs are not accessible from the location in which you saved the document.

Character encoding is based on the encoding attribute in the xml declaration, such as <?xml version="1.0" encoding="windows-1252"?>. When no encoding attribute is specified, the default setting is UTF-8.

Validation is not performed during save, which can result in an invalid document that does not load again because of a specified DTD.

When manipulating a document, it is possible to create a document that lacks the appropriate namespace declarations to be reparsed, or to have declarations that would cause some prefixed names to be interpreted incorrectly. When saving an XML representation of DOM nodes, MSXML attempts to insert appropriate namespace declarations to preserve the original namespaceURI for each element and its attributes.

C/C++ Example

BOOL DOMDocSaveLocation()
{
   BOOL bResult = FALSE;
   IXMLDOMDocument *pIXMLDOMDocument = NULL;
   HRESULT hr;

   try
   {
      _variant_t varString = _T("D:\\sample.xml");
      // create Instance of DOMDocument and initialise pIXMLDOMDocument
      // load/create an XML document
      hr = pIXMLDOMDocument->save(varString);
      if(SUCCEEDED(hr))
         bResult = TRUE;
   }
   catch(...)
   {
DisplayErrorToUser();
   // release the IXMLDOMDocument interface
   }
   // release the IXMLDOMDocument interface after done with
   return bResult;
}