Introduction

---

Loading and saving tables and query result sets to and from streams is accomplished through the LoadFromStream and SaveToStream methods of the TDBISAMTable and TDBISAMQuery components. The properties used by the LoadFromStream and SaveToStream methods include the DatabaseName, TableName, and Exists properties. A stream is any TStream-descendant object such as TFileStream, TMemoryStream, or even the DBISAM TDBISAMBlobStream object used for reading and writing to BLOB fields. Loading a stream copies the entire contents of a stream to an existing table or query result set. When loading a stream, the contents of the stream must have been created using the SaveToStream method or else an EDBISAMEngineError exception will be raised. The error code given when a load from a stream fails because of an invalid stream is 11312 and is defined as DBISAM_LOADSTREAMERROR in the dbisamcn unit (Delphi) or dbisamcn header file (C++). Saving to a stream copies the contents of a table or query result set to the stream, overwriting the entire contents of the stream. The records that are copied can be controlled by setting a range or filter on the source table or query result set prior to calling the SaveToStream method. Please see the Setting Ranges on Tables and Setting Filters on Tables and Query Result Sets topics for more information.

Loading Data from a Stream

---

To load data from a stream into an existing table, you must specify the DatabaseName and TableName properties of the TDBISAMTable component and then call the LoadFromStream method. When using a TDBISAMTable component, the table can be open or closed when this method is called, and the table does not need to be opened exclusively. If the table is closed when this method is called, then DBISAM will attempt to open the table before loading the data into it. It is usually good practice to examine the Exists property of the TDBISAMTable component first to make sure that you don't attempt to load data into a non-existent table. If you do attempt to load data into a non-existent table an EDBISAMEngineError exception will be raised. The error code given when a load from a stream fails due to the table not existing is 11010 and is defined as DBISAM_OSENOENT in the dbisamcn unit (Delphi) or dbisamcn header file (C++). To load data from a stream into a query result set, the TDBISAMQuery SQL property must be populated with a SELECT SQL statement and the Active property must be True.

The following example shows how to load data from a memory stream (assumed to already be created) into a table using the LoadFromStream method:

begin
   with MyTable do
      begin
      DatabaseName:='d:\temp';
      TableName:='customer';
      if Exists then
         LoadFromStream(MyMemoryStream);
      end;
end;

Tracking the Load Progress

---

To take care of tracking the progress of the load we have provided the TDBISAMTable and TDBISAMQuery OnLoadFromStreamProgress events.

Saving Data to a Stream

---

To save the data from a table to a stream, you must specify the DatabaseName and TableName properties of the TDBISAMTable component and then call the SaveToStream method. When using a TDBISAMTable component, the table can be open or closed when this method is called, and the table does not need to be opened exclusively. If the table is closed when this method is called, then DBISAM will attempt to open the table before saving the data. It is usually good practice to examine the Exists property of the TDBISAMTable component first to make sure that you don't attempt to save data from a non-existent table. If you do attempt to save data from a non-existent table an EDBISAMEngineError exception will be raised. The error code given when a save fails due to the table not existing is 11010 and is defined as DBISAM_OSENOENT in the dbisamcn unit (Delphi) or dbisamcn header file (C++). To save data to a stream from a query result set, the TDBISAMQuery SQL property must be populated with a SELECT SQL statement and the Active property must be True.

The following example shows how to save the data from a table to a memory stream (assumed to already be created) using the SaveToStream method of the TDBISAMTable component:

begin
   with MyTable do
      begin
      DatabaseName:='d:\temp';
      TableName:='customer';
      if Exists then
         SaveToStream(MyMemoryStream);
      end;
end;

Tracking the Save Progress

---

To take care of tracking the progress of the save we have provided the TDBISAMTable and TDBISAMQuery OnSaveToStreamProgress events.