This documentation is archived and is not being maintained.

DataSet.Load Method (IDataReader, LoadOption, FillErrorEventHandler, DataTable())

Fills a DataSet with values from a data source using the supplied IDataReader, using an array of DataTable instances to supply the schema and namespace information.

Namespace:  System.Data
Assembly:  System.Data (in System.Data.dll)

'Declaration
Public Overridable Sub Load ( _
	reader As IDataReader, _
	loadOption As LoadOption, _
	errorHandler As FillErrorEventHandler, _
	ParamArray tables As DataTable() _
)
'Usage
Dim instance As DataSet 
Dim reader As IDataReader 
Dim loadOption As LoadOption 
Dim errorHandler As FillErrorEventHandler 
Dim tables As DataTable()

instance.Load(reader, loadOption, errorHandler, _
	tables)

Parameters

reader
Type: System.Data.IDataReader

An IDataReader that provides one or more result sets.

loadOption
Type: System.Data.LoadOption

A value from the LoadOption enumeration that indicates how rows already in the DataTable instances within the DataSet will be combined with incoming rows that share the same primary key.

errorHandler
Type: System.Data.FillErrorEventHandler

A FillErrorEventHandler delegate to call when an error occurs while loading data.

tables
Type: System.Data.DataTable()

An array of DataTable instances, from which the Load method retrieves name and namespace information.

The Load method provides a technique for filling a single DataTable with data, retrieved from an IDataReader instance. This method provides the same functionality, but allows you to load multiple result sets from an IDataReader into multiple tables within a DataSet.

NoteNote:

The load operation will fail with an InvalidOperationException if any of the source data columns in the incoming reader are computed columns.

The loadOption parameter allows you to specify how you want the imported data to interact with existing data, and can be any of the values from the LoadOption enumeration. See the documentation for the DataTable Load method for more information on using this parameter.

The errorHandler parameter is a FillErrorEventHandler delegate that refers to a procedure that is called when an error occurs while loading data. The FillErrorEventArgs parameter passed to the procedure provides properties that allow you to retrieve information about the error that occurred, the current row of data, and the DataTable being filled. Using this delegate mechanism, rather than a simpler try/catch block, allows you to determine the error, handle the situation, and continue processing if you like. The FillErrorEventArgs parameter supplies a Continue property: set this property to true to indicate that you have handled the error and wish to continue processing; set the property to false to indicate that you wish to halt processing. Be aware that setting the property to false causes the code that triggered the problem to throw an exception.

The tables parameter allows you to specify an array of DataTable instances, indicating the order of the tables corresponding to each result set loaded from the reader. The Load method fills each supplied DataTable instance with data from a single result set from the source data reader. After each result set, the Load method moves on to the next result set within the reader, until there are no more result sets.

The name resolution scheme for this method is the same as that followed by the Fill method of the DbDataAdapter class.

The following example adds a table to a DataSet, and then attempts to use the Load method to load data from a DataTableReader that contains an incompatible schema. Rather than trapping the error, this example uses a FillErrorEventHandler delegate to investigate and handle the error. The output is displayed in the console window.

Sub Main()
  Dim dataSet As New DataSet
  Dim table As New DataTable()

  ' Attempt to load data from a data reader in which 
  ' the schema is incompatible with the current schema. 
  ' If you use exception handling, you won't get the chance 
  ' to examine each row, and each individual table, 
  ' as the Load method progresses. 
  ' By taking advantage of the FillErrorEventHandler delegate, 
  ' you can interact with the Load process as an error occurs, 
  ' attempting to fix the problem, or simply continuing or quitting 
  ' the Load process.:
  dataSet = New DataSet()
  table = GetIntegerTable()
  dataSet.Tables.Add(table)
  Dim reader As New DataTableReader(GetStringTable())
  dataSet.Load(reader, LoadOption.OverwriteChanges, _
      AddressOf FillErrorHandler, table)

  Console.WriteLine("Press any key to continue.")
  Console.ReadKey()
End Sub 

Private Sub FillErrorHandler(ByVal sender As Object, _
  ByVal e As FillErrorEventArgs)
  ' You can use the e.Errors value to determine exactly what 
  ' went wrong. 
  If e.Errors.GetType Is GetType(System.FormatException) Then
    Console.WriteLine("Error when attempting to update the value: {0}", _
      e.Values(0))
  End If 

  ' Setting e.Continue to True tells the Load 
  ' method to continue trying. Setting it to False 
  ' indicates that an error has occurred, and the  
  ' Load method raises the exception that got  
  ' you here.
  e.Continue = True 
End Sub 

Private Function GetIntegerTable() As DataTable
  ' Create sample table with a single Int32 column. 
  Dim table As New DataTable

  Dim idColumn As DataColumn = table.Columns.Add("ID", _
      GetType(Integer))

  ' Set the ID column as the primary key column.
  table.PrimaryKey = New DataColumn() {idColumn}

  table.Rows.Add(New Object() {4})
  table.Rows.Add(New Object() {5})
  table.TableName = "IntegerTable"
  table.AcceptChanges()
  Return table
End Function 

Private Function GetStringTable() As DataTable
  ' Create sample table with a single String column. 
  Dim table As New DataTable

  Dim idColumn As DataColumn = table.Columns.Add("ID", _
      GetType(String))

  ' Set the ID column as the primary key column.
  table.PrimaryKey = New DataColumn() {idColumn}

  table.Rows.Add(New Object() {"Mary"})
  table.Rows.Add(New Object() {"Andy"})
  table.Rows.Add(New Object() {"Peter"})
  table.AcceptChanges()
  Return table
End Function 

Private Sub PrintColumns( _
   ByVal table As DataTable)

  ' Loop through all the rows in the DataTableReader. 
  For Each row As DataRow In table.Rows
    For Each col As DataColumn In table.Columns
      Console.Write(row(col).ToString() & " ")
    Next
    Console.WriteLine()
  Next 
End Sub

Windows 7, Windows Vista, Windows XP SP2, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP Starter Edition, Windows Server 2008 R2, Windows Server 2008, Windows Server 2003, Windows Server 2000 SP4, Windows Millennium Edition, Windows 98, Windows CE, Windows Mobile for Smartphone, Windows Mobile for Pocket PC, Xbox 360, Zune

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

.NET Framework

Supported in: 3.5, 3.0, 2.0

.NET Compact Framework

Supported in: 3.5, 2.0

XNA Framework

Supported in: 3.0, 2.0, 1.0
Show: