TCustomClientDataSet.Active Property

Specifies whether the client dataset contains data.

Pascal

property Active: Boolean;

C++

__property Boolean Active;

Description

Use Active to determine whether the client dataset makes its data available. When Active is false, the client dataset is closed; It can't manipulate the data it represents. When Active is true, data can be read or edited using the client dataset.

Setting Active to true:

1Fills the client dataset with data. Depending on the other properties of the client dataset, this data comes from:

The file specified by the FileName property.

The provider specified by the ProviderName property or SetProvider method. (For some TCustomClientDataSet descendants, this is an internal provider component)

The data that was active when the client dataset was deactivated (only if the application has run continuously since the dataset was deactivated).

2Triggers a BeforeOpen event.

3Sets the State property to dsBrowse.

4Opens a cursor into the dataset.

5Triggers an After Open event.

If the client dataset has never been active previously, setting Active to true defines the structure (metadata) of the client dataset. This structure is retrieved with the data packet from the provider or stored on disk, or, if there is no data packet, it is built using the current value of the FieldDefs property or from the persistent field components listed by the Fields property.

If an error occurs during the dataset open, the dataset state is set to dsInactive, and the cursor is closed.

Setting Active to false:

1Triggers a BeforeClose event.

2Sets the State property to dsInactive.

3Closes the cursor, saving the current data to disk if the FileName property is set, and saving the current data packet to a cache so that it can be restored when the client dataset is reopened.

4Triggers an AfterClose event.

Note: Calling the Open method sets Active to true; calling the Close method sets Active to false.

Delphi Examples:

Copy Code

{
This example shows how to use the BeforeGetRecords event
handler (a TRemoteEventType value) to send the provider
information it needs for incremental data fetching. Before
fetching the next data packet, the client dataset packages
up the key value of the last record so that the provider
knows where to begin the next data packet. It also sends
some application-specific information, which is stored in
Memo1.  This method is used to pass the sql statement and the
value of the first field for the last record to the server so
that the server can return the correct records. The complete
project using this code example is in
Demos/DelphiWin32/VCLWin32/MIDAS/Pooler.
}
procedure TForm1.ClientDataSet1BeforeGetRecords(Sender: TObject; var OwnerData: OleVariant);
var
  LastValue: OleVariant;
  CDSClone: TClientDataSet;
begin
  if ClientDataSet1.Active then
  begin
    CDSClone := TClientDataSet.Create(Form1);
    try
      CDSClone.CloneCursor(ClientDataSet1, True);
      { turn off FetchOnDemand so that the clone only fetches
        the last LOCAL record }
      CDSClone.FetchOnDemand := False;
      CDSClone.Last;
      LastValue := CDSClone.Fields[0].AsString;
      CDSClone.Close;
    finally
      CDSClone.Free;
    end;
  end else
    LastValue := NULL;
  OwnerData := VarArrayOf([Memo1.Lines.Text, LastValue]);
end;

procedure TForm1.Button2Click(Sender: TObject);
begin
  ClientDataSet1.PacketRecords := StrToInt(Edit1.Text);
  ClientDataSet1.GetNextPacket;
end;

Copy Code

{
The following code fragment illustrates how DataSets and
DataSetCount can be used to ensure that an action is taken
for every open dataset.  Assign CheckButtonActive as the
AfterClose and AfterOpen event handlers for TClientDataSet1.
}
procedure TForm1.Button1Click(Sender: TObject);
var
  I: Integer;
begin
  if not RemoteServer1.Connected then
    RemoteServer1.Connected := True;
  ClientDataSet1.Close;
  with RemoteServer1 do
  begin
    for I := 0 to DataSetCount - 1 do
      DataSets[I].EnableControls;
  end;
  ClientDataSet1.Open;
end;

procedure TForm1.Button3Click(Sender: TObject);
var
  I: Integer;
begin
  ClientDataSet1.Close;
  RemoteServer1.Connected := False;
  with RemoteServer1 do
  begin
    for I := 0 to DataSetCount - 1 do
      DataSets[I].DisableControls;
  end;
end;

procedure TForm1.CheckButtonActive(DataSet: TDataSet);
begin
  Button1.Enabled := not ClientDataSet1.Active;
  Button2.Enabled := ClientDataSet1.Active;
  Button3.Enabled := ClientDataSet1.Active;
end;