System.Data.Common Namespace   DbDataAdapter Class

Adds or refreshes rows in the DataSet to match those in the data source using the DataSet and DataTable names.

[ VB ]
Overloads Public Function Fill ( _
   ByVal dataSet As DataSet, _
   ByVal srcTable As String _
) As Integer

[ C# ]
public int Fill (
   DataSet dataSet,
   string srcTable
);

[ C++ ]
public: int Fill (
   DataSet* dataSet,
   String* srcTable
);

[ JScript ]
public function Fill (
   dataSet : DataSet,
   srcTable : String
) : int;

dataSet

A DataSet to fill with records and, if necessary, schema.

srcTable

The name of the source table to use for table mapping.

The number of rows successfully added to or refreshed in the DataSet. This does not include rows affected by statements that do not return rows.

The Fill method retrieves the data from the data source using a SELECT statement. The IDbConnection object associated with the select command must be valid, but it does not need to be open. If the IDbConnection is closed before Fill is called, it is opened to retrieve data, then closed. If the connection is open before Fill is called, it remains open.

If a command does not return any rows, no tables are added to the DataSet, and no exception is raised.

If the DbDataAdapter object encounters duplicate columns while populating a DataTable, it will generate names for the subsequent columns, using the pattern "columnname1", "columnname2", "columnname3", and so on. If the incoming data contains unnamed columns, they are placed in the DataSet according to the pattern "Column1", "Column2", and so on.

When the query specified returns multiple results, the result set for each row returning query is placed in a separate table. Additional result sets are named by appending integral values to the specified table name ( for example, "Table", "Table1", "Table2", and so on. ). Since no table is created for a query that does not return rows, if you were to process an insert query followed by a select query, the table created for the select query would be named "Table" since it is the first table created. Applications should use caution when using column and table names to ensure that no naming conflict occurs.

The Fill method supports scenarios where the DataSet contains multiple DataTable objects whose names differ only by case. In such situations, Fill performs a case-sensitive comparison to find the corresponding table, and initializes a new table if no exact match exists. The following [ C# ] code illustrates this behavior.

DataSet myDataset = new DataSet ( );
myDataset.Tables.Add ( "aaa" );
myDataset.Tables.Add ( "AAA" );

adapter.Fill ( myDataset, "aaa" );   // Fills "aaa", which already exists in the DataSet.

adapter.Fill ( myDataset, "Aaa" );   // adds a new table called "Aaa".

If Fill is called and the DataSet contains only one DataTable whose name differs only by case, that DataTable is updated. In this scenario, the comparison is case insensitive. The following [ C# ] code illustrates this behavior.

DataSet myDataset = new DataSet ( );
myDataset.Tables.Add ( "aaa" );

adapter.Fill ( myDataset, "AAA" );
// Fills table "aaa" as only one similarly named table is in the DataSet.

If an error is encountered while populating the data set, rows added prior to the occurrence of the error remain in the data set. The remainder of the operation is aborted.

When the SELECT statement used to populate the DataSet returns multiple results, such as batch SQL statements, and if one of the results contains an error, all subsequent results are skipped and not added to the DataSet.

When using subsequent Fill calls to refresh the contents of the DataSet, two conditions must be met:

1. The SQL statement should match the one initally used to populate the DataSet.
2. The Key column information must be present.

If primary key information is present, any duplicate rows are reconciled and only appears once in the DataTable that corresponds to the DataSet. Primary key information may be set either through FillSchema, by specifying the PrimaryKey property of the DataTable, or by setting the MissingSchemaAction property to AddWithKey.

NOTE: When handling batch SQL statements that return multiple results, the implementation of FillSchema for the OLE DB .NET Data Provider retrieves schema information for only the first result. To retrieve schema information for multiple results, use Fill with the MissingSchemaAction set to AddWithKey.

The following example shows how to use Fill to populate a DataSet using this constructor.

void FillDemo ( ) {
   // . . . code to initialize DataAdapter and DataSet here . . .

   myDataAdapter.Fill ( myDataSet, "Products" );
}

Public Sub FillDemo ( )
   ' . . . code to initialize DataAdapter and DataSet here . . .

   myDataAdapter.Fill ( myDataSet, "Products" )
End Sub

DbDataAdapter Members   DbDataAdapter.Fill Overload List