| ADO 2.5 API Reference |  |
| ADO 2.5 API Reference | |
Saves the Recordset in a file or Stream object.
recordset.Save Destination, PersistFormat
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.
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.
Only Filters in the form of Criteria Strings (e.g. OrderDate > '12/31/1999') affect the contents of a persisted Recordset. Filters created with an Array of Bookmarks or using a value from the FilterGroupEnum will not affect the contents of the persisted Recordset. These rules apply to Recordsets created with either client-side or server-side cursors.
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.
A Recordset saved in XML format is saved using UTF-8 format. When such a file is loaded into an ADO Stream, the Stream object will not attempt to open a Recordset from the stream unless the Charset property of the stream is set to the appropriate value for UTF-8 format.
Visual Basic Example | Visual C++ Example | Visual J++ Example
Open Method (ADO Recordset) | Open Method (ADO Stream) | SaveToFile Method
Applies To: Recordset Object | Stream Object