RAD Studio |  |

Adding Custom Information to Data Packets
See Also
Collapse All

Dataset providers can add application-defined information to data packets using the OnGetDataSetProperties event. This information is encoded as an OleVariant, and stored under a name you specify. Client datasets can then retrieve the information using their GetOptionalParam method. You can also specify that the information be included in delta packets that the client dataset sends when updating records. In this case, the client dataset may never be aware of the information, but the provider can send a round-trip message to itself.

When adding custom information in the OnGetDataSetProperties event, each individual attribute (sometimes called an "optional parameter") is specified using a Variant array that contains three elements: the name (a string), the value (a Variant), and a boolean flag indicating whether the information should be included in delta packets when the client applies updates. Add multiple attributes by creating a Variant array of Variant arrays. For example, the following OnGetDataSetProperties event handler sends two values, the time the data was provided and the total number of records in the source dataset. Only the time the data was provided is returned when client datasets apply updates:

Copy Code

    procedure TMyDataModule1.Provider1GetDataSetProperties(Sender: TObject; DataSet: TDataSet; out Properties: OleVariant);
    begin
      Properties := VarArrayCreate([0,1], varVariant);
      Properties[0] := VarArrayOf(['TimeProvided', Now, True]);
      Properties[1] := VarArrayOf(['TableSize', DataSet.RecordCount, False]);
    end;

Copy Code

    void __fastcall TMyDataModule1::Provider1GetDataSetProperties(TObject *Sender, TDataSet *DataSet, out OleVariant Properties)
    {
      int ArrayBounds[2];
      ArrayBounds[0] = 0;
      ArrayBounds[1] = 1;
      Properties = VarArrayCreate(ArrayBounds, 1, varVariant);
      Variant values[3];
      values[0] = Variant("TimeProvided");
      values[1] = Variant(Now());
      values[2] = Variant(true);
      Properties[0] = VarArrayOf(values,2);
      values[0] = Variant("TableSize");
      values[1] = Variant(DataSet->RecordCount);
      values[2] = Variant(false);
      Properties[1] = VarArrayOf(values,2);
    }

When the client dataset applies updates, the time the original records were provided can be read in the provider's OnUpdateData event:

Copy Code

    procedure TMyDataModule1.Provider1UpdateData(Sender: TObject; DataSet: TCustomClientDataSet);
    var
      WhenProvided: TDateTime;
    begin
      WhenProvided := DataSet.GetOptionalParam('TimeProvided');
      ...
    end;

Copy Code

    void __fastcall TMyDataModule1::Provider1UpdateData(TObject *Sender, TCustomClientDataSet *DataSet)
    {
      Variant WhenProvided = DataSet->GetOptionalParam("TimeProvided");
      ...
    }

See Also

Specifying What Fields Appear in Data Packets

Setting Options That Influence the Data Packets

Adding Application Specific Information to the Data

Copyright(C) 2009 Embarcadero Technologies, Inc. All Rights Reserved.
What do you think about this topic? Send feedback!