Export (0) Print
Expand All

DbDataAdapter.Fill Method (DataTable[], Int32, Int32, IDbCommand, CommandBehavior)

Note: This method is new in the .NET Framework version 2.0.

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

Namespace: System.Data.Common
Assembly: System.Data (in system.data.dll)

protected:
virtual int Fill (
	array<DataTable^>^ dataTables, 
	int startRecord, 
	int maxRecords, 
	IDbCommand^ command, 
	CommandBehavior behavior
)
protected int Fill (
	DataTable[] dataTables, 
	int startRecord, 
	int maxRecords, 
	IDbCommand command, 
	CommandBehavior behavior
)
protected function Fill (
	dataTables : DataTable[], 
	startRecord : int, 
	maxRecords : int, 
	command : IDbCommand, 
	behavior : CommandBehavior
) : int

Parameters

dataTables

The DataTable objects to fill from the data source.

startRecord

The zero-based record number to start with.

maxRecords

The maximum number of records to retrieve.

command

The IDbCommand executed to fill the DataTable objects.

behavior

One of the CommandBehavior values.

Return Value

The number of rows added to or refreshed in the data tables.

Exception typeCondition

SystemException

The DataSet is invalid.

InvalidOperationException

The source table is invalid.

-or-

The connection is invalid.

InvalidCastException

The connection could not be found.

ArgumentException

The startRecord parameter is less than 0.

-or-

The maxRecords parameter is less than 0.

A maxRecords value of 0 gets all records found after the start record. If maxRecords is greater than the number of remaining rows, only the remaining rows are returned and no error is issued.

The Fill method retrieves the data from the data source using a SELECT statement. The IDbConnection object associated with the SELECT statement 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, but 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, each result set 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", because it is the first table created. Applications using column and table names should ensure that conflicts with these naming patterns does not occur.

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 creates a new table if no exact match exists. The following C# code illustrates this behavior.

 DataSet dataset = new DataSet();
 dataset.Tables.Add("aaa");
 dataset.Tables.Add("AAA");
 adapter.Fill(dataset, "aaa"); // Fills "aaa", which already exists in the DataSet.
 adapter.Fill(dataset, "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 dataset = new DataSet();
 dataset.Tables.Add("aaa");
 adapter.Fill(dataset, "AAA"); // Fills table "aaa" because only one similarly named table is in the DataSet.

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

When the SELECT statement used to populate the DataTable objects returns multiple results, such as a batch SQL statement, be aware of the following:

  • When processing multiple results from a batch SQL statement, maxRecords only applies to the first result. The same is true for rows containing chaptered results (.NET Framework Data Provider for OLE DB only). The top level result is limited by maxRecords, but all child rows are added.

  • If one of the results contains an error, all subsequent results are skipped.

NoteNote

The DataSet will not contain more than the number of records indicated by maxRecords. However, the entire resultset generated by the query is still returned from the server.

Notes to Inheritors When overriding Fill in a derived class, be sure to call the base class's Fill method.

Windows 98, Windows 2000 SP4, Windows CE, Windows Millennium Edition, Windows Mobile for Pocket PC, Windows Mobile for Smartphone, Windows Server 2003, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP SP2, Windows XP Starter Edition

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see System Requirements.

.NET Framework

Supported in: 2.0

.NET Compact Framework

Supported in: 2.0

Community Additions

ADD
Show:
© 2014 Microsoft