Icon Loading and Saving Streams with Tables and Query Result Sets

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;

Information Tables or query result sets in remote sessions can load streams from a local stream. However, since the stream contents are sent as one buffer to the database server as part of the request, it is recommended that you do not load particularly large streams since you will run the risk of exceeding the available memory on the local workstation or database server.

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.
Image