From RAD Studio API Documentation
Jump to: navigation, search


property DataSource: TDataSource read GetDataSource;


__property TDataSource* DataSource = {read=GetDataSource};


Type Visibility Source Unit Parent
property public
Data.DB TDataSet


Represents the data source of another dataset that supplies values to the dataset.

As implemented in TDataSet, the DataSource property is always nil (Delphi) or NULL (C++).

Descendant dataset classes that support specifying a data source redeclare and implement methods for getting and setting the DataSource property.

For example:

For Data.Win.ADODB.TADOQuery, which is an indirect descendand of TDataSet (deriving from Data.Win.ADODB.TCustomADODataSet),DataSource specifies the data source component from which to extract the current field values to use in same-name parameters in the ADO query's SQL statement.

Set Data.Win.ADODB.TCustomADODataSet.DataSource to automatically fill parameters in a query with field values from another dataset. Parameters that have the same name as the fields in the other dataset are filled with the field values. Parameters with names that are not the same as the fields in the other dataset do not automatically get values, and must be programmatically set. For example, if the SQL property of the Data.Win.ADODB.TADOQuery contains the SQL statement below and the dataset referenced through Data.Win.ADODB.TCustomADODataSet.DataSource has a CustNo field, the value from the current record in that other dataset is used in the CustNo parameter:

FROM Orders O
WHERE (O.CustNo = :CustNo)

Data.Win.ADODB.TCustomADODataSet.DataSource must point to a Data.DB.TDataSource component linked to another dataset component; it cannot point to this query component. The dataset specified in Data.Win.ADODB.TCustomADODataSet.DataSource must be created, populated, and opened before attempting to bind parameters. Parameters are bound by setting the ADO query's Data.Win.ADODB.TADOCommand.Prepared property to True prior to executing the query. If the SQL statement used by a query does not contain parameters, or all parameters are bound by the application using the Data.Win.ADODB.TADOCommand.Parameters property or the Data.Win.ADODB.TParameters.ParamByName method, Data.Win.ADODB.TCustomADODataSet.DataSource need not be assigned. The example below shows setting the Data.Win.ADODB.TCustomADODataSet.DataSource property of ADOQuery2 to the data source for ADOQuery1, preparing ADOQuery2, and activating ADOQuery2:

with ADOQuery2 do begin
DataSource := DataSource1;
Prepared := True;

ADOQuery2->DataSource = DataSource1;
ADOQuery2->Prepared = true;

If the SQL statement in the Data.Win.ADODB.TADOQuery is a SELECT query, the query is executed using the new field values each time the record pointer in the other dataset is changed. It is not necessary to call the Data.Win.ADODB.TADOConnection.Open method of the Data.Win.ADODB.TADOQuery each time. This makes using the Data.Win.ADODB.TCustomADODataSet.DataSource property to dynamically filter a query result set useful for establishing Master-Detail relationships. Set the Data.Win.ADODB.TCustomADODataSet.DataSource property in the Detail query to the Data.Win.ADODB.TCustomADODataSet.DataSource component for the Master dataset.

If the SQL statement uses other than a SELECT query (such as INSERT or UPDATE), the parameters with the same name as fields in the other dataset still get values, but the query must be explicitly executed each time the other dataset's record pointer moves. For example, the SQL statement below uses the INSERT statement and has the parameters CustNo and CompanyName:

(CustNo, Company)
VALUES (:CustNo, :CompanyName)

Another dataset, ADOQuery1 and DataSource1, has a CustNo field but no CompanyName field. If this dataset is used through the Data.Win.ADODB.TCustomADODataSet.DataSource property, the CompanyName parameter must be programmatically assigned a value. Because ADOQuery1 has a CustNo field and ADOQuery1 is referenced through the Data.Win.ADODB.TCustomADODataSet.DataSource property, the CustNo parameter automatically receives a value.

with ADOQuery2 do begin
DataSource := DataSource1;
ParamByName ('CompanyName').AsString := Edit1.Text;
Prepared := True;

ADOQuery2->DataSource = DataSource1;
ADOQuery2->ParamByName("CompanyName")->AsString = Edit1->Text;
ADOQuery2->Prepared = true;

If the SQL statement contains parameters with the same name as fields in the other dataset, do not manually set values for these parameters. Any values programmatically set, such as by using the Data.Win.ADODB.TADOCommand.Parameters property or the Data.Win.ADODB.TParameters.ParamByName method, will be overridden with automatic values. Parameters of other names must be programmatically given values. These parameters are unaffected by setting Data.Win.ADODB.TCustomADODataSet.DataSource.

Data.Win.ADODB.TCustomADODataSet.DataSource can be set at run time or at design time using the Object Inspector. At design time, select the desired Data.DB.TDataSource from the drop-down list or type in the name.

See Also