Saves the Recordset in a file or Stream object.
Syntax
recordset.Save Destination, PersistFormat
Parameters
Destination Optional. A Variant that represents the complete path name of the file where the Recordset is to be saved, or a reference to a Stream object.
PersistFormat Optional. A PersistFormatEnum value that specifies the format in which the Recordset is to be saved (XML or ADTG). The default value is adPersistADTG.
Remarks
The Save method can only be invoked on an open Recordset. Use the Open method to later restore the Recordset from Destination.
If the Filter property is in effect for the Recordset, then only the rows accessible under the filter are saved. If the Recordset is hierarchical, then the current child Recordset and its children are saved, including the parent Recordset. If the Save method of a child Recordset is called, the child and all its children are saved, but the parent is not.
The first time you save the Recordset, it is optional to specify Destination. If you omit Destination, a new file will be created with a name set to the value of the Source property of the Recordset.
Omit Destination when you subsequently call Save after the first save, or a run-time error will occur. If you subsequently call Save with a new Destination, the Recordset is saved to the new destination. However, the new destination and the original destination will both be open.
Save does not close the Recordset or Destination, so you can continue to work with the Recordset and save your most recent changes. Destination remains open until the Recordset is closed, during which time other applications can read but not write to Destination.
For reasons of security, the Save method permits only the use of low and custom security settings from a script executed by Microsoft Internet Explorer. For a more detailed explanation of security issues, see "ADO and RDS Security Issues in Microsoft Internet Explorer" under ActiveX Data Objects (ADO) Technical Articles in Microsoft Data Access Technical Articles.
If the Save method is called while an asynchronous Recordset fetch, execute, or update operation is in progress, then Save waits until the asynchronous operation is complete.
Records are saved beginning with the first row of the Recordset. When the Save method is finished, the current row position is moved to the first row of the Recordset.
For best results, set the CursorLocation property to adUseClient with Save. If your provider does not support all of the functionality necessary to save Recordset objects, the Cursor Service will provide that functionality.
When a Recordset is persisted with the CursorLocation property set to adUseServer, the update capability for the Recordset is limited. Typically, only single-table updates, insertions, and deletions are allowed (dependant upon provider functionality). The Resync method is also unavailable in this configuration.
Note Saving a Recordset with Fields of type adVariant, adIDispatch, or adIUnknown is not supported by ADO and can cause unpredictable results.
Because the Destination parameter can accept any object that supports the OLE DB IStream interface, you can save a Recordset directly to the ASP Response object. For more details, please see the XML Recordset Persistence Scenario.
You can also save a Recordset in XML format to an instance of an MSXML DOM object, as is shown in the following Visual Basic code:
Dim xDOM As New MSXML.DOMDocument
Dim rsXML As New ADODB.Recordset
Dim sSQL As String, sConn As String
sSQL = "SELECT customerid, companyname, contactname FROM customers"
sConn="Provider=Microsoft.Jet.OLEDB.4.0;Data Source=D:\Program Files" & _
"\Common Files\System\msadc\samples\NWind.mdb"
rsXML.Open sSQL, sConn
rsXML.Save xDOM, adPersistXML 'Save Recordset directly into a DOM tree.
...
Note Two limitations apply when saving hierarchical Recordsets (data shapes) in XML format. You cannot save into XML if the hierarchical Recordset contains pending updates, and you cannot save a parameterized hierarchical Recordset.