OleDbDataAdapter.Fill Method (DataSet, Object, String)
Adds or refreshes rows in the DataSet to match those in an ADO Recordset or Record object using the specified DataSet, ADO object, and source table name.
[Visual Basic] Overloads Public Function Fill( _ ByVal dataSet As DataSet, _ ByVal ADODBRecordSet As Object, _ ByVal srcTable As String _ ) As Integer [C#] public int Fill( DataSet dataSet, object ADODBRecordSet, string srcTable ); [C++] public: int Fill( DataSet* dataSet, Object* ADODBRecordSet, String* srcTable ); [JScript] public function Fill( dataSet : DataSet, ADODBRecordSet : Object, srcTable : String ) : int;
- A DataSet to fill with records and, if necessary, schema.
- An ADO Recordset or Record object.
- The source table used for the table mappings.
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.
|SystemException||The source table was invalid.|
The link between ActiveX Data Objects (ADO) and ADO.NET is a one-way operation in that you can copy data from ADO to the DataSet, but any updates to the data must be handled by ADO.NET. For more information, see Filling a DataSet with an ADO Recordset or Record.
The Fill method iterates through multiple results by calling the NextRecordset method on the Recordset, closing the input Recordset on completion of the Fill operation.
The Fill operation adds the rows to the specified destination DataTable object in the DataSet, creating the DataTable object if it does not already exist. When creating a DataTable object, 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 primary key information is present, any duplicate rows are reconciled and only appear 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.
To function properly with the .NET Framework Data Provider for OLE DB, AddWithKey requires that the native OLE DB provider obtains necessary primary key information by setting the DBPROP_UNIQUEROWS property, and then determines which columns are primary key columns by examining DBCOLUMN_KEYCOLUMN in the IColumnsRowset. As an alternative, the user may explicitly set the primary key constraints on each DataTable. This ensures that incoming records that match existing records are updated instead of appended.
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, see Defining a Primary Key for a Table.
If the Recordset is closed prior to the beginning of the Fill operation, no error results. This is required for handling of multiple results, because queries that do not return rows are indicated by a closed Recordset. The OleDbDataAdapter simply calls NextRecordset on the closed Recordset and continues processing.
If an error is encountered while populating the data set, rows added prior to the occurrence of the error remain in the DataSet. The remainder of the operation is aborted.
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 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 should use caution when using column and table names to ensure that conflicts with these naming patterns does not occur.
Values in ADO Recordset or Record objects are converted to common language runtime types for storage in the DataSet. For more information on the mappings between ADO and common language runtime types, see Accessing an ADO Recordset or Record from ADO.NET.
Note This overload of the Fill method implicitly calls Close on the ADO object when the fill operation is complete.
The following example uses an OleDbDataAdapter to fill a DataSet using an ADO Recordset that is an ADO Record object. This example assumes that you have created an ADO RecordSet and Record object.
[Visual Basic] Dim custDA As OleDbDataAdapter = New OleDbDataAdapter() Dim custDS As DataSet = New DataSet 'Use ADO objects from ADO library (msado15.dll) imported ' as .NET library ADODB.dll using TlbImp.exe Dim adoConn As ADODB.Connection = New ADODB.Connection() Dim adoRS As ADODB.Recordset = New ADODB.Recordset() adoConn.Open("Provider=SQLOLEDB;Data Source=localhost;Initial Catalog=Northwind;Integrated Security=SSPI;", "", "", -1) adoRS.Open("SELECT * FROM Customers", adoConn, ADODB.CursorTypeEnum.adOpenForwardOnly, ADODB.LockTypeEnum.adLockReadOnly, 1) custDA.Fill(custDS, adoRS, "Customers") adoConn.Close() [C#] OleDbDataAdapter custDA = new OleDbDataAdapter(); DataSet custDS = new DataSet(); //Use ADO objects from ADO library (msado15.dll) imported // as .NET library ADODB.dll using TlbImp.exe ADODB.Connection adoConn = new ADODB.Connection(); ADODB.Recordset adoRS = new ADODB.Recordset(); adoConn.Open("Provider=SQLOLEDB;Data Source=localhost;Initial Catalog=Northwind;Integrated Security=SSPI;", "", "", -1); adoRS.Open("SELECT * FROM Customers", adoConn, ADODB.CursorTypeEnum.adOpenForwardOnly, ADODB.LockTypeEnum.adLockReadOnly, 1); custDA.Fill(custDS, adoRS, "Customers"); adoConn.Close();
Platforms: Windows 98, Windows NT 4.0, Windows Millennium Edition, Windows 2000, Windows XP Home Edition, Windows XP Professional, Windows Server 2003 family