TDatasetWrapper

Overview

The TDatasetWrapper class represents a lightweight wrapper for the TDataSet class. It implements the IDADataset and IDAEditableDataset interfaces via the standard VCL TDataSet class.

While Data Abstract can only serialize objects that support the IDADataset into the stream that will be transferred to the client, the TDatasetWrapper allows to serialize any TDataSet descendants into the stream.

Data Abstract uses this class for serializing Exported Tables.

In most cases you do not need to deal with this class directly.

Note that the TDatasetWrapper is only used for serializing data. It does not implement any additional methods besides that purpose.

  • DisableConstraints/EnableConstraints, SetDynamicWhere and SQLContainsDynamicWhere do nothing
  • Execute and SetSQL are not implemented.
  • GetOnAfterExecute/SetOnAfterExecute, GetOnBeforeExecute/SetOnBeforeExecute, GetOnExecuteError/SetOnExecuteError, GetOnOpenError/SetOnOpenError, GetPrepared/SetPrepared, ParamByName and RefreshParams raise a "NotSupported" exception.

Use case

Following is a simple example demonstrates the usage of the TDatasetWrapper class:

   
program TDatasetWrapper_Demo;

{$APPTYPE CONSOLE}

uses
  DB, ADODB, ADOInt, ActiveX, Variants, SysUtils,
  uDAInterfaces,      //IDADataset
  uDAMemDataset,      //TDAMemoryDataset
  uDADatasetWrapper;  //TDatasetWrapper

//some general purpose utility function which operates on the IDADataset
procedure dumpDS (ds : IDADataset);
const
  ANSI_TAB  = #9;
  ANSI_CRLF = #13#10;
var
  i     : integer;
begin
  WriteLn (ANSI_CRLF, 'DataSet: ', ds.Name);

  Write ('RecId', ANSI_TAB);
  for i := 0 to ds.FieldCount - 1 do
    Write (ds.Fields [i].Name, ANSI_TAB);

  WriteLn;
  for i := 0 to ds.FieldCount do
    Write ('--------');

  WriteLn;
  while NOT ds.EOF do begin
    Write (ds.CurrentRecIdValue, ANSI_TAB);
    for i := 0 to ds.FieldCount - 1 do
      Write (Trim (VarToStr (ds.FieldValues [i])), ANSI_TAB);

    WriteLn;
    ds.Next;
  end;
end;

procedure doDemoMemDS;
  function  createField (const fldName : string; fldClass : TFieldClass; ds : TDataset) : TField;
  begin
    Result := fldClass.Create (ds);
    Result.FieldName := fldName;
    Result.DataSet := ds;
  end;
var
  memDS     : TDAMemoryDataset;
begin
  memDS := TDAMemoryDataset.Create (NIL);
  memDS.Name := 'InMemoryDataSet';
  createField ('TextId', TIntegerField, memDS);
  createField ('Text', TStringField, memDS).Size := 100;
  memDS.Open;
  memDS.AppendRecord ([1001, 'First record']);
  memDS.AppendRecord ([1002, 'Second record']);
  memDS.First;

  //TDatasetWrapper instance will be coerced to IDADataset and fried automatically
  dumpDS (TDatasetWrapper.Create (memDS));

  memDS.Free;
end;

procedure doDemoADO;
var
  adoDS     : TADODataSet;
  rs        : _Recordset;
begin
  adoDS := TADODataSet.Create (NIL);
  adoDS.Name := 'ADODataSet';
  rs := CoRecordset.Create;
  rs.Fields.Append ('IdText', adInteger, 0, adFldUnspecified);
  rs.Fields.Append ('Text', adChar, 100, adFldUnspecified);
  rs.Open (EmptyParam, EmptyParam, adOpenUnspecified, adLockUnspecified, 0);
  adoDS.Recordset := rs;
  adoDS.AppendRecord ([2001, 'First record']);
  adoDS.AppendRecord ([2002, 'Second record']);
  adoDS.First;

  //TDatasetWrapper instance will be coerced to the IDADataset and fired automatically
  dumpDS (TDatasetWrapper.Create (adoDS));

  adoDS.Free;
end;

begin
  try
    CoInitialize (nil);
    doDemoMemDS;
    doDemoADO;
  except on E : Exception do
    WriteLn ('Exception: ', E.Message);
  end;
end.

Location

  • Unit: uDADatasetWrapper.pas
  • Ancestry: TInterfacedObject | TDatasetWrapper


 

constructor Create

Creates a new instance.

constructor Create(ADataset: TDataset)

Parameters:

  • ADataset: dataset

Active

Specifies whether the dataset is currently active (open) or not. Setting this property to true will automatically open the dataset, while setting it to false will automatically close it.

property Active: Boolean read write

AddRecord  protected safecall

Adds a new, populated record to the end of the dataset. The record field FieldNames is populated by the field values in FieldValues. The newly appended record becomes the active record.

procedure AddRecord(const FieldNames: array of string; const FieldValues: array of Variant)

Parameters:

  • FieldNames: List of fields that will be populated
  • FieldValues: List of values for the fields

Append  protected safecall

Adds a new, empty record to the end of the dataset. The newly appended record becomes the active record. After calling Append, the application can enable users to enter data in the fields of the record and can then post those changes using Post.

procedure Append

BOF

Indicates whether reading the dataset has reached the beginning of the recordset (BOF = Beginning of File). GetBOF will only turn true if neither an empty dataset was opened nor Prior was called while the cursor was already on the first record (it will not turn to true when reaching the first record).

property BOF: Boolean read

BookmarkValid  protected safecall

Returns True if bookmarked record exists

function BookmarkValid(Bookmark: TBookmark): Boolean

Parameters:

  • Bookmark: bookmark that is checked

Cancel  protected safecall

Cancels modifications made to one or more fields belonging to the active record, returns the record to its previous state and sets the dataset state to dsBrowse.

procedure Cancel

Close  protected safecall

Closes the dataset and discards any local data that had been retrieved from the database.

procedure Close

ControlsDisabled  protected safecall

Indicates whether data-aware controls update their display to reflect changes to the dataset.

function ControlsDisabled: Boolean

CurrentRecIdValue

Provides access to Dataset.RecNo

property CurrentRecIdValue: Integer read write

Dataset

Returns owner object

property Dataset: TDataSet read

Delete  protected safecall

Deletes the active record and positions the cursor on the next record.

procedure Delete

DisableConstraints  protected safecall

Disables dataset constraints

procedure DisableConstraints

DisableControls  protected safecall

Disables data display in data-aware controls associated with the dataset.

procedure DisableControls

DisableEventHandlers  protected safecall

Detaches all internal events from the Dataset object.

procedure DisableEventHandlers

Edit  protected safecall

Permits the editing of the active record in a dataset. Edit determines the current state of the dataset. If the dataset is empty, Edit calls Insert. Otherwise Edit.

procedure Edit

EnableConstraints  protected safecall

Enables dataset constraints

procedure EnableConstraints

EnableControls  protected safecall

Enables data display in data-aware controls associated with the dataset.

procedure EnableControls

EnableEventHandlers  protected safecall

Attaches all internal events to the Dataset object.

procedure EnableEventHandlers

Eof

Indicates whether reading the dataset has reached the end of the recordset (EOF = End of File). EOF will only turn true if neither an empty dataset was opened nor Next was called while the cursor was already on the last record (it will not turn to true when reaching the last record).

property Eof: Boolean read

Execute  protected safecall

Not implemented in dataset wrapper. Returns -1.

function Execute: Integer

FieldByName  protected safecall

Finds a field based on its name. If the specified field does not exist, FieldByName raises an exception.

function FieldByName(const aName: string): TDAField

Parameters:

  • aName: name of the searched field

FieldCount

Indicates the number of fields contained in the dataset.

property FieldCount: Integer read

Fields

Provides access to all the fields contained in the dataset.

property Fields: TDAFieldCollection read

FieldValues

Provides convenient access to all the fields values of the current record without having to go though the Fields collection property.

property FieldValues[Index: Integer]: Variant read

FindField  protected safecall

Returns an item with the specified name.

function FindField(const aName: string): TDAField

Parameters:

  • aName: name of the searched field

First  protected safecall

Positions the cursor on the first record in the dataset and makes it the active record. It also posts any changes.

procedure First

FreeBookmark  protected safecall

Frees the resources allocated for a specified bookmark.

procedure FreeBookmark(Bookmark: TBookmark)

Parameters:

  • Bookmark: bookmark that should be freed

GetBookMark  protected safecall

Allocates a bookmark for the active record

function GetBookMark: TBookmark

GotoBookmark  protected safecall

Positions on the record to which a specified bookmark points.

procedure GotoBookmark(Bookmark: TBookmark)

Parameters:

  • Bookmark: record identified by this Bookmark should be active

Insert  protected safecall

Inserts a new record

procedure Insert

InterfaceSupportsErrorInfo  protected stdcall

Indicates whether an interface supports the IErrorInfo interface.

function InterfaceSupportsErrorInfo(const iid: TGUID): HResult

Parameters:

  • iid: GUID or name of interface that should be checked

IsEmpty

Indicates whether the dataset contains no records.

property IsEmpty: Boolean read

Last  protected safecall

Moves to the last record in the dataset.

procedure Last

Locate  protected safecall

Locates and activates a record by key values.

function Locate(const KeyFields: string; const KeyValues: Variant; Options: TLocateOptions): Boolean

Parameters:

  • KeyFields: The semicolon-separated list of fields.
  • KeyValues: Values specified by the Variant or Variant array.
  • Options: Indicates whether the search is case insensitive and whether partial matches are supported.

LogicalName

Defines the name of the data table.

property LogicalName: string read write

Lookup  protected safecall

Retrieves the field values from the record that matches the specified search values.

function Lookup(const KeyFields: string; const KeyValues: Variant; const ResultFields: string): Variant

Parameters:

  • KeyFields: the semicolon-separated list of fields
  • KeyValues: Values specified by the Variant or Variant array
  • ResultFields: The semicolon-separated list of result fields.

Name

Returns a human-readable name for the command. For commands obtained through the TDASchema component, this will be the name that the command (or data table) was defined under in the Schema Modeler. When obtaining a command from an IDAConnection, the name can be specified in the call to NewCommand or NewDataset.

property Name: string read

Names

Returns data table's field name specified by Index

property Names[Index: Integer]: string read

Advances the cursor to the next available record in the dataset. If the current record is the last record available, calling Next will set EOF to indicate that the end of the dataset has been reached.

procedure Next

OnAfterOpen

Fires after dataset was opened

property OnAfterOpen: TDAAfterOpenDatasetEvent read write
delegate:  procedure OnAfterOpen(const Sender: IDADataset; ActualSQL: string; ElapsedMilliseconds: Cardinal)

OnBeforeOpen

Fires before dataset was opened

property OnBeforeOpen: TDABeforeOpenDatasetEvent read write
delegate:  procedure OnBeforeOpen(const Sender: IDADataset)

Open  protected safecall

Opens the dataset and prepares it for fetching records from the database. If the dataset is not empty, the cursor will be placed on the first available record; otherwise, EOF will be set to true to indicate that the end of the (empty) record set has been reached.

procedure Open

ParamByName  protected safecall

Locates a specific parameter, based on its name. If no matching parameter is defined, an exception will be raised.

function ParamByName(const aName: string): TDAParam

Parameters:

  • aName: name of the parameter

Params

Provides access to the list of parameters defined for the command.

property Params: TDAParamCollection read

Post  protected safecall

Saves changes in the dataset

procedure Post

Prior  protected safecall

Moves to the previous record of the dataset

procedure Prior

RecordCount

Returns the count of records

property RecordCount: Integer read

Refresh  protected safecall

Reopens the dataset.

procedure Refresh

RowRecIdValue

Returns -1

property RowRecIdValue: Integer read

SafeCallException  override

Handles exceptions in methods that use safecall directive.

function SafeCallException(ExceptObject: TObject; ExceptAddr: Pointer): HResult

Parameters:

  • ExceptObject: Exception object.
  • ExceptAddr: Address of the exception.

State

Determines the current operating mode of the dataset. State determines what can be done with the data in the dataset, such as editing existing records or inserting new ones. The dataset state constantly changes as the application processes data.

property State: TDatasetState read

 

Active

Specifies whether the dataset is currently active (open) or not. Setting this property to true will automatically open the dataset, while setting it to false will automatically close it.

property Active: Boolean read write

BOF

Indicates whether reading the dataset has reached the beginning of the recordset (BOF = Beginning of File). GetBOF will only turn true if neither an empty dataset was opened nor Prior was called while the cursor was already on the first record (it will not turn to true when reaching the first record).

property BOF: Boolean read

CurrentRecIdValue

Provides access to Dataset.RecNo

property CurrentRecIdValue: Integer read write

Dataset

Returns owner object

property Dataset: TDataSet read

Eof

Indicates whether reading the dataset has reached the end of the recordset (EOF = End of File). EOF will only turn true if neither an empty dataset was opened nor Next was called while the cursor was already on the last record (it will not turn to true when reaching the last record).

property Eof: Boolean read

FieldCount

Indicates the number of fields contained in the dataset.

property FieldCount: Integer read

Fields

Provides access to all the fields contained in the dataset.

property Fields: TDAFieldCollection read

FieldValues

Provides convenient access to all the fields values of the current record without having to go though the Fields collection property.

property FieldValues[Index: Integer]: Variant read

IsEmpty

Indicates whether the dataset contains no records.

property IsEmpty: Boolean read

LogicalName

Defines the name of the data table.

property LogicalName: string read write

Name

Returns a human-readable name for the command. For commands obtained through the TDASchema component, this will be the name that the command (or data table) was defined under in the Schema Modeler. When obtaining a command from an IDAConnection, the name can be specified in the call to NewCommand or NewDataset.

property Name: string read

Names

Returns data table's field name specified by Index

property Names[Index: Integer]: string read

Params

Provides access to the list of parameters defined for the command.

property Params: TDAParamCollection read

RecordCount

Returns the count of records

property RecordCount: Integer read

RowRecIdValue

Returns -1

property RowRecIdValue: Integer read

State

Determines the current operating mode of the dataset. State determines what can be done with the data in the dataset, such as editing existing records or inserting new ones. The dataset state constantly changes as the application processes data.

property State: TDatasetState read

 

constructor Create

Creates a new instance.

constructor Create(ADataset: TDataset)

Parameters:

  • ADataset: dataset

AddRecord  protected safecall

Adds a new, populated record to the end of the dataset. The record field FieldNames is populated by the field values in FieldValues. The newly appended record becomes the active record.

procedure AddRecord(const FieldNames: array of string; const FieldValues: array of Variant)

Parameters:

  • FieldNames: List of fields that will be populated
  • FieldValues: List of values for the fields

Append  protected safecall

Adds a new, empty record to the end of the dataset. The newly appended record becomes the active record. After calling Append, the application can enable users to enter data in the fields of the record and can then post those changes using Post.

procedure Append

BookmarkValid  protected safecall

Returns True if bookmarked record exists

function BookmarkValid(Bookmark: TBookmark): Boolean

Parameters:

  • Bookmark: bookmark that is checked

Cancel  protected safecall

Cancels modifications made to one or more fields belonging to the active record, returns the record to its previous state and sets the dataset state to dsBrowse.

procedure Cancel

Close  protected safecall

Closes the dataset and discards any local data that had been retrieved from the database.

procedure Close

ControlsDisabled  protected safecall

Indicates whether data-aware controls update their display to reflect changes to the dataset.

function ControlsDisabled: Boolean

Delete  protected safecall

Deletes the active record and positions the cursor on the next record.

procedure Delete

DisableConstraints  protected safecall

Disables dataset constraints

procedure DisableConstraints

DisableControls  protected safecall

Disables data display in data-aware controls associated with the dataset.

procedure DisableControls

DisableEventHandlers  protected safecall

Detaches all internal events from the Dataset object.

procedure DisableEventHandlers

Edit  protected safecall

Permits the editing of the active record in a dataset. Edit determines the current state of the dataset. If the dataset is empty, Edit calls Insert. Otherwise Edit.

procedure Edit

EnableConstraints  protected safecall

Enables dataset constraints

procedure EnableConstraints

EnableControls  protected safecall

Enables data display in data-aware controls associated with the dataset.

procedure EnableControls

EnableEventHandlers  protected safecall

Attaches all internal events to the Dataset object.

procedure EnableEventHandlers

Execute  protected safecall

Not implemented in dataset wrapper. Returns -1.

function Execute: Integer

FieldByName  protected safecall

Finds a field based on its name. If the specified field does not exist, FieldByName raises an exception.

function FieldByName(const aName: string): TDAField

Parameters:

  • aName: name of the searched field

FindField  protected safecall

Returns an item with the specified name.

function FindField(const aName: string): TDAField

Parameters:

  • aName: name of the searched field

First  protected safecall

Positions the cursor on the first record in the dataset and makes it the active record. It also posts any changes.

procedure First

FreeBookmark  protected safecall

Frees the resources allocated for a specified bookmark.

procedure FreeBookmark(Bookmark: TBookmark)

Parameters:

  • Bookmark: bookmark that should be freed

GetBookMark  protected safecall

Allocates a bookmark for the active record

function GetBookMark: TBookmark

GotoBookmark  protected safecall

Positions on the record to which a specified bookmark points.

procedure GotoBookmark(Bookmark: TBookmark)

Parameters:

  • Bookmark: record identified by this Bookmark should be active

Insert  protected safecall

Inserts a new record

procedure Insert

InterfaceSupportsErrorInfo  protected stdcall

Indicates whether an interface supports the IErrorInfo interface.

function InterfaceSupportsErrorInfo(const iid: TGUID): HResult

Parameters:

  • iid: GUID or name of interface that should be checked

Last  protected safecall

Moves to the last record in the dataset.

procedure Last

Locate  protected safecall

Locates and activates a record by key values.

function Locate(const KeyFields: string; const KeyValues: Variant; Options: TLocateOptions): Boolean

Parameters:

  • KeyFields: The semicolon-separated list of fields.
  • KeyValues: Values specified by the Variant or Variant array.
  • Options: Indicates whether the search is case insensitive and whether partial matches are supported.

Lookup  protected safecall

Retrieves the field values from the record that matches the specified search values.

function Lookup(const KeyFields: string; const KeyValues: Variant; const ResultFields: string): Variant

Parameters:

  • KeyFields: the semicolon-separated list of fields
  • KeyValues: Values specified by the Variant or Variant array
  • ResultFields: The semicolon-separated list of result fields.

Advances the cursor to the next available record in the dataset. If the current record is the last record available, calling Next will set EOF to indicate that the end of the dataset has been reached.

procedure Next

Open  protected safecall

Opens the dataset and prepares it for fetching records from the database. If the dataset is not empty, the cursor will be placed on the first available record; otherwise, EOF will be set to true to indicate that the end of the (empty) record set has been reached.

procedure Open

ParamByName  protected safecall

Locates a specific parameter, based on its name. If no matching parameter is defined, an exception will be raised.

function ParamByName(const aName: string): TDAParam

Parameters:

  • aName: name of the parameter

Post  protected safecall

Saves changes in the dataset

procedure Post

Prior  protected safecall

Moves to the previous record of the dataset

procedure Prior

Refresh  protected safecall

Reopens the dataset.

procedure Refresh

SafeCallException  override

Handles exceptions in methods that use safecall directive.

function SafeCallException(ExceptObject: TObject; ExceptAddr: Pointer): HResult

Parameters:

  • ExceptObject: Exception object.
  • ExceptAddr: Address of the exception.

 

OnAfterOpen

Fires after dataset was opened

property OnAfterOpen: TDAAfterOpenDatasetEvent read write
delegate:  procedure OnAfterOpen(const Sender: IDADataset; ActualSQL: string; ElapsedMilliseconds: Cardinal)

OnBeforeOpen

Fires before dataset was opened

property OnBeforeOpen: TDABeforeOpenDatasetEvent read write
delegate:  procedure OnBeforeOpen(const Sender: IDADataset)