Export (0) Print
Expand All

DbDataAdapter.Fill Method (DataSet, Int32, Int32, String, IDbCommand, CommandBehavior)

Adds or refreshes rows in a specified range in the DataSet to match those in the data source using the DataSet and source table names, command string, and command behavior.

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

protected:
virtual int Fill (
	DataSet^ dataSet, 
	int startRecord, 
	int maxRecords, 
	String^ srcTable, 
	IDbCommand^ command, 
	CommandBehavior behavior
)
protected int Fill (
	DataSet dataSet, 
	int startRecord, 
	int maxRecords, 
	String srcTable, 
	IDbCommand command, 
	CommandBehavior behavior
)
protected function Fill (
	dataSet : DataSet, 
	startRecord : int, 
	maxRecords : int, 
	srcTable : String, 
	command : IDbCommand, 
	behavior : CommandBehavior
) : int
Not applicable.

Parameters

dataSet

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

startRecord

The zero-based record number to start with.

maxRecords

The maximum number of records to retrieve.

srcTable

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

command

The SQL SELECT statement used to retrieve rows from the data source.

behavior

One of the CommandBehavior values.

Return Value

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.

Exception typeCondition

InvalidOperationException

The source table is invalid.

ArgumentException

The startRecord parameter is less than 0.

-or-

The maxRecords parameter is less than 0.

The Fill method retrieves rows from the data source using the SELECT statement specified by an associated SelectCommand property. The connection object associated with the SELECT statement must be valid, but it does not need to be open. If the connection 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.

The Fill operation then adds the rows to destination DataTable objects in the DataSet, creating the DataTable objects if they do not already exist. When creating DataTable objects, the Fill operation normally creates only column name metadata. However, if the MissingSchemaAction property is set to AddWithKey, appropriate primary keys and constraints are also created.

If the DbDataAdapter encounters duplicate columns while populating a DataTable, it generates 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 multiple result sets are added to the DataSet 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). 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.

You can use the Fill method multiple times on the same DataTable. If a primary key exists, incoming rows are merged with matching rows that already exist. If no primary key exists, incoming rows are appended to the DataTable.

If the SelectCommand returns the results of an OUTER JOIN, the DataAdapter does not set a PrimaryKey value for the resulting DataTable. You must explicitly define the primary key to ensure that duplicate rows are resolved correctly. For more information, seeDefining a Primary Key for a Table.

NoteNote:

When handling batch SQL statements that return multiple results, the implementation of Fill and FillSchema for a .NET Framework data provider retrieves schema information for only the first result.

Notes to Implementers: This overload of the Fill method is protected and is designed for use by a .NET Framework data provider.

Windows 98, Windows Server 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 Microsoft .NET Framework 3.0 is supported on Windows Vista, Microsoft Windows XP SP2, and Windows Server 2003 SP1.

.NET Framework

Supported in: 3.0, 2.0, 1.1, 1.0

.NET Compact Framework

Supported in: 2.0, 1.0

XNA Framework

Supported in: 1.0

Community Additions

ADD
Show:
© 2014 Microsoft