Invoking the Persistence Provider

The OLE DB Persistence Provider is automatically invoked when the ADO Save method is called on the IADORecordset interface, with a pointer to the recordset and with the local file name specified. The following example in Microsoft? Visual C++? shows the SaveMyRowset method for rowset persistence. The example follows these steps:

1. An empty recordset is constructed.

2. The rowset is given to ADO, where the rowset is merged into the constructed recordset.

3. Therecordset's Save method (defined in the following code) is invoked, passing in as arguments the file name (bstrFileName) and the desired persisted file format (adPersist*), where * is either "XML" or "ADTG".

For more examples, see the "Microsoft OLE DB Persistence Provider" documentation in the ADO Programmer's Reference.

HRESULT SaveMyRowset(IRowset *pRowset, BSTR bstrFileName)
{
// Get the recordset interface.
//IADORecordset *pADORs = NULL;
//IADORecordsetConstruction * pADORsCt = NULL;
   HRESULT hr;

// Get an ADO recordset, and ask for the recordset construction interface.
   if (FAILED (hr = ::CoCreateInstance(
               CLSID_ADORecordset,
               NULL,
               CLSCTX_INPROC_SERVER,
               IID_IADORecordsetConstruction,
               (LPVOID *) &pADORsCt)))
      return hr;

// Give the rowset to ADO.
   if (SUCCEEDED (hr= pADORsCt->put_Rowset(pRowset)))
   {
      hr = pADORsCt->QueryInterface(IID_IADORecordset, (void **)&pADORs);
// Identify which format to use when persisting: XML or ADTG.
      hr = pADORs->Save(bstrFileName, adPersistADTG);
   }

// Cleanup (or use the ATL CComPtr class):
   pADORs->Release();
   pADORsCt->Release();

   return hr;
}

Note

The result of saving hierarchical rowsets is different because they are persisted as separate, flattened rowsets. For more information about persisting hierarchical rowsets, see the Persisted Hierarchical Data section of this guide.

Loading a persisted rowset into a recordset so that it can be viewed or modified by the application requires the persisted file name and a pointer to the IRowset interface. The following Visual C++ example shows the LoadMyFile method for loading the persisted data into a recordset. The example follows these steps:

1. An empty recordset is constructed.

2. The persisted file is opened (as identified by bstrFileName).

3. The rowset is loaded into the recordset.

For more examples, see the "Microsoft OLE DB Persistence Provider" documentation in the ADO Programmer's Reference.

HRESULT LoadMyFile(BSTR bstrFileName, IRowset ** ppRowset)
{
   // Get the recordset interface.
   //IADORecordsetConstruction * pADORsCt = NULL;
   //IADORecordset * pADORs = NULL;
   HRESULT hr;

   // Create the ADO Recordset.
   if (SUCCEEDED (hr = ::CoCreateInstance(CLSID_ADORecordset,
                  NULL,
                  CLSCTX_INPROC_SERVER,
                  IID_IADORecordset,
                  (LPVOID *) &pADORs)))
   {
      VARIANT varEmpty;

      varEmpty.vt = VT_ERROR;
      varEmpty.scode = DISP_E_PARAMNOTFOUND;

      // Open the persisted file.

      hr = pADORs->Open(bstrFileName, varEmpty, adOpenUnspecified, 
                        adLockUnspecified, adCmdUnspecified);
      hr = pADORs->QueryInterface(IID_IADORecordsetConstruction,
      (void **)&pADORsCt);

      // Loads the persisted rowset into the Recordset.
      hr = pADORsCt->get_Rowset(ppRowset);
   }

   pADORs->Release() ;
   pADORsCt->Release() ;
   return hr;
}

Note

The procedures for saving a rowset do not apply to hierarchical rowsets because they are persisted as separate, flattened rowsets. For more information about persisting hierarchical rowsets, see the Persisted Hierarchical Data section of this guide.

Programming Considerations for the C++ Programmer

For C++ programmers who want to benefit from the full ADO functionality of the Persistence Provider, use the following code sample. Call CoCreateInstance on the ADO recordset, and then call QueryInterface for the IADORecordsetConstruction interface. Next, load the underlying rowset with the ADO recordset and call the save method. ADO automatically invokes the client cursor engine and calls the Persistence Provider when saving the recordset. The following example shows this procedure:

HRESULT SaveMyRowset(IRowset *pRowset, BSTR bstrFileName)
{
// Get the recordset interface.
   IADORecordset * pRs = NULL;
   IADORecordsetConstruction * pADORsCt = NULL;
   HRESULT hr;

// Get an ADO recordset, and ask for the recordset construction 
// interface.
   if (FAILED (hr = ::CoCreateInstance(
            CLSID_ADORecordset, 
            NULL,
            CLSCTX_INPROC,
            IID_IADORecordsetConstruction, 
            (LPVOID *) &pADORsCt)))
      return hr;

// Give the rowset to ADO and save to the file name while calling the    
//   Persistence Provider with the desired data format.
   if (SUCCEEDED (hr= pADORsCt->put_Rowset(pRowset))
   {
      hr = pADORsCt->QueryInterface(IID_IADORecordset, (void **)&pRs);
      hr = pRs->Save(bstrFileName, adPersistADTG);
      }

// Cleanup: (or use ATL CComPtr class).
   pRs->Release();
   pADORsCt->Release();

   return hr;
}

This topic is a part of:

• Using the OLE DB Persistence Provider: A Closer Look

See Also

Reference

IRowset

Concepts

Persisted Hierarchical Data