25.4 Methods Reference

AcceptChanges

DataRow.AcceptChanges();

Commits all changes made to the DataRow since the last time it was loaded or since the last time AcceptChanges( ) was called.

Parameters

None.

Example

The following example demonstrates how to call the AcceptChanges( ) method of the DataRow:

// create a table with a single column
DataTable dt = new DataTable();
dt.Columns.Add("MyColumn", typeof(System.Int32));

DataRow row;
row = dt.NewRow();
row["MyColumn"] = 1;
dt.Rows.Add(row);       // RowState = Added

row.AcceptChanges();    // RowState = Unchanged

row["MyColumn"] = 2;    // RowState = Modified
row.AcceptChanges();    // RowState = Unchanged

row.Delete();           // RowState = Deleted
row.AcceptChanges();    // Row is removed from the DataTable

Notes

Calling AcceptChanges( ) sets the RowState property of Added and Modified rows to Unchanged; the original values in the DataRow are set as the current values. Deleted rows are removed from the DataTable.

Calling the AcceptChanges( ) method of the table the row belongs to implicitly calls the AcceptChanges( ) method of the row.

If the DataRow is in edit mode, as a result of calling the BeginEdit( ) method, EndEdit( ) is implicitly called, ending the edit.

Calling AcceptChanges( ) clears all RowError information and sets the HasErrors property for the row to false.

BeginEdit

DataRow.BeginEdit();

Puts the DataRow into edit mode, suspending the events that trigger validations rules.

Parameters

None.

Example

The following example demonstrates how to use the BeginEdit( ), EndEdit( ), and CancelEdit( ) methods:

DataRow row;

// ... retrieve data into the DataRow object

row.BeginEdit();
foreach(DataColumn col in row.Table.Columns)
{
    // ... modify the column value
}

Boolean rowValid = true;
// check the values in the row to make sure that they are valid
 
if(rowValid)
{
    row.CancelEdit();
}
else
{
    row.EndEdit();
}

Notes

Updates to a row can be buffered by calling the BeginEdit( ), EndEdit( ), and CancelEdit( ) methods. The BeginEdit( ) method turns off all constraints and suspends events used to enforce validation rules. If CancelEdit( ) is called, the changes in the buffer are discarded. When EndEdit( ) is called, the data is validated against the constraints, and events are raised if any violations occur.

Prior to calling EndEdit( ), any changes made to values for the row are stored as a proposed value. Until EndEdit( ) is called, both the original value and the proposed value can be retrieved by specifying Original or Proposed as the optional DataRowVersion argument for the Item property. While the row is being edited, the proposed value is returned by default.

The HasVersion method can be called to determine whether the row has an Original or Proposed value.

BeginEdit( ) is called implicitly when a user changes the value of a data-bound control.

CancelEdit

DataRow.CancelEdit();

Cancels the edit on the DataRow, discarding the changes.

Parameters

None.

Example

See the Example for the BeginEdit( ) method in this chapter.

Notes

Updates to a row can be buffered by calling the BeginEdit( ), EndEdit( ), and CancelEdit( ) methods. The BeginEdit( ) method turns off all constraints and suspends events that enforce validation rules. If CancelEdit( ) is called, the changes in the buffer are discarded. When EndEdit( ) is called, the data is validated against the constraints, and events are raised if any violations occur.

Prior to EndEdit( ) being called, any changes made to values for the row are stored as a proposed value. Until EndEdit( ) is called, both the original value and the proposed value can be retrieved by specifying the Original or Proposed as the optional DataRowVersion argument for the Item property. While the row is being edited, the proposed value is returned by default.

The HasVersion( ) method can be called to determine whether the row has an Original or Proposed value.

ClearErrors

DataRow.ClearErrors();

Clears all errors for the DataRow.

Parameters

None.

Example

The following example demonstrates using the Clear( ) method to clear the errors for a row:

row.ClearErrors();

Note

The ClearErrors( ) method clears all errors set on the row and on the individual columns within the row, including the RowError and errors set on the columns using the SetColumnError( ) method.

Delete

DataRow.Delete();

If the RowState of the DataRow is Added, the row is removed from the table. Otherwise, the RowState of the DataRow is set to Deleted, effectively marking it for deletion.

Parameters

None.

Examples

Three examples follow that demonstrate how to use the Delete( ) method and that highlight the effect of the RowState property and of the AcceptChanges( ) and RejectChanges( ) methods. The first example shows the relationship between the Delete( ) method and the AcceptChanges( ) method:

// delete the first row from the table
DataRow row = dt.Rows[0];
row.Delete();          // RowState changed to Deleted
dt.AcceptChanges();    // row is removed from the DataTable

The next example shows the relationship between the Delete( ) method and the RejectChanges( ) method:

// delete the first row from the table
DataRow row = dt.Rows[0];
row.Delete();            // RowState changed to Deleted
dt.RejectChanges();      // RowState reverts to Unchanged

Finally, the following example shows the relationship between newly added rows and the Delete( ) method:

// Create a new row
row = dt.NewRow();

// ... code to set the data for the row

// add the row to the table
dt.Rows.Add(row);       // RowState is Added

// delete the newly added row
row.Delete();           // row is removed from the table

Note

A deleted row can be undeleted by calling the RejectChanges( ) method.

EndEdit

DataRow.EndEdit();

Ends the edit on the DataRow, committing the changes made.

Parameters

None.

Example

See the Example for the BeginEdit( ) method in this chapter.

Notes

Updates to a row can be buffered by calling the BeginEdit( ), EndEdit( ), and CancelEdit( ) methods. The BeginEdit( ) method turns off all constraints and suspends events that enforce validation rules. If CancelEdit( ) is called, the changes in the buffer are discarded. When EndEdit( ) is called, the data is validated against the constraints, and events are raised if any violations occur.

Prior to EndEdit( ) being called, any changes made to values for the row are stored as proposed values. Until EndEdit( ) is called, both the original value and the proposed value can be retrieved by specifying the Original or Proposed as the optional DataRowVersion argument for the Item property. While the row is being edited, the proposed value is returned by default.

The HasVersion method can be called to determine whether the row has an Original or Proposed value.

EndEdit( ) is called implicitly when AcceptChanges( ) is called.

GetChildRows

DataRow[] childRows = DataRow.GetChildRows(DataRelation dr);
DataRow[] childRows = DataRow.GetChildRows(String relationName);
DataRow[] childRows = DataRow.GetChildRows(DataRelation,
    DataRowVersion drv);
DataRow[] childRows = DataRow.GetChildRows(String relationName,
    DataRowVersion drv);

Gets an array of DataRow objects that are the child rows of the DataRow, based on a specified DataRelation.

Parameters

childRows

Returns an array of DataRow objects containing the child rows.

dr

The DataRelation object to use.

relationName

The name of the DataRelation to use.

drv

One of the DataRowVersion enumeration values described in Table 25-5, which is in the HasVersion section of this chapter.

Example

The following example uses the GetChildRows( ) method to retrieve the array of Orders for a Customer:

// iterate through all of the Customers rows
foreach(DataRow rowCustomer in ds.Tables["Customers"].Rows)
{
    // iterate through the orders rows for the customer
    foreach(DataRow rowOrder in rowCustomer.GetChildRows(
        "Customers_Orders"))
    {
        // ... code to process the order for the customer
    }
}
GetColumnError

String colErr = DataRow.GetColumnError(DataColumn col);
String colErr = DataRow.GetColumnError(Integer columnIndex);
String colErr = DataRow.GetColumnError(String columnName);

Gets the error description for a specified column in the DataRow.

Parameters

colErr

Returns a string containing the error description for the specified DataColumn in the DataRow.

col

The DataColumn object for which to return the error.

columnIndex

The index of the DataColumn for which to return the error.

columnName

The name of the DataColumn for which to return the error.

Example

The following example shows how to get the error description for a column named MyColumn using the GetColumnError( ) method:

String colError = row.GetColumnError("MyColumn");

Note

The SetColumnError( ) method can set the error description for a column in a row.

GetColumnsInError

DataColumn[] colInError = DataRow.GetColumnsInError();

Gets an array of DataColumn objects for the columns having errors in the DataRow.

Parameter

colInError

Returns an array of DataColumn objects that have errors.

Example

The following example demonstrates using the GetColumnsInError( ) method to return the array of columns that have errors in the row:

DataColumn[] errorCols;
if(row.HasErrors)
{
    errorCols = row.GetColumnsInError();
    for(Int32 i = 0; i < errorCols.Length; i++)
    {
        // ... resolve the error for each column
    }
}
// clear all errors on the row after resolving
row.ClearErrors();

Notes

An error can be set on a specific column using the SetColumnError( ) method.

The ClearErrors( ) method clears errors for each column in the row and for the entire row.

Call HasErrors( ) on the DataRow prior to calling GetColumnsInError( ).

GetParentRow

DataRow parentRow = DataRow.GetParentRow(DataRelation dr);
DataRow parentRow = DataRow.GetParentRow(String relationName);
DataRow parentRow = DataRow.GetParentRow(DataRelation,
    DataRowVersion drv);
DataRow parentRow = DataRow.GetParentRow(String relationName,
    DataRowVersion drv);

Gets the parent DataRow of the current row, based on a DataRelation.

Parameters

parentRow

Returns the parent DataRow.

dr

The DataRelation to use when retrieving the parent row.

relationName

The name of the DataRelation to use when retrieving the parent row.

drv

One of the DataRowVersion enumeration values described in Table 25-5, which is in the HasVersion section later in this chapter.

Example

The following example uses the GetParentRow( ) method to retrieve the customer for each order:

// iterate through all of the Orders rows
foreach(DataRow rowOrder in ds.Tables["Orders"].Rows)
{
    // get the customer row for the specified order
    DataRow rowCustomer = rowOrder.GetParentRow("Customers_Orders");
    
    // ... code to process the customer row
}
GetParentRows

DataRow[] parentRows = DataRow.GetParentRows(DataRelation dr);
DataRow[] parentRows = DataRow.GetParentRows(String relationName);
DataRow[] parentRows = DataRow.GetParentRows(DataRelation,
    DataRowVersion drv);
DataRow[] parentRows = DataRow.GetParentRows(String relationName,
    DataRowVersion drv);

Gets an array of DataRow objects that are the parent rows of the current row, based on a DataRelation.

Parameters

parentRows

Returns an array of DataRow objects.

dr

The DataRelation to use when retrieving the parent row.

relationName

The name of the DataRelation to use when retrieving the parent row.

drv

One of the DataRowVersion enumeration values described in Table 25-5 in the next section.

Example

The following example uses the GetParentRow( ) method to retrieve the Cocktails in which each Ingredient is used:

// iterate through all of the Ingredient rows
foreach(DataRow rowIngredient in ds.Tables["Ingredient"].Rows)
{
    // iterate through the Cocktail rows for the specified Ingredient
    foreach(DataRow rowCocktail in rowIngredient.GetParentRows(
        "Cocktail_Ingredient"))
    {
        // ... code to process the Cocktail row
    }
}

Note

Although the GetParentRows( ) returns the parent rows for a child row using many-to-many relationships, there is little RDBMS support for many-to-many relationships.

HasVersion

Boolean hasVersion = DataRow.HasVersion(DataRowVersion drv);

Returns a value that indicates whether the specified DataRowVersion for the DataRow exists.

Parameters

hv

Returns a Boolean value indicating whether the specified version of a DataRow exists.

drv

One of the DataRowVersion enumeration values described in Table 25-5.

Table 25-5. DataRowVersion enumeration

Value

Description

Current 

The row containing current values. Always available.

Default 

The default row version. When the row is edited, the Proposed row is returned; otherwise the Current row is returned.

Original 

The row containing the original values. Available only when the row has been retrieved and doesn't exist for newly added rows.

Proposed

The row containing the proposed values. Available only when the row is being edited using the BeginEdit( ) method.

Example

The following example shows how to check if a row has a proposed version that uses the HasVersion( ) method:

Boolean hasVersion = row.HasVersion(DataRowVersion.Proposed);
IsNull

Boolean isNull = DataRow.IsNull(DataColumn col)
Boolean isNull = DataRow.IsNull(Integer columnIndex)
Boolean isNull = DataRow.IsNull(String columnName)
Boolean isNull = DataRow.IsNull(DataColumn col, DataRowVersion drv)

Returns a value indicating whether the specified column contains a null value. An optional argument allows the DataRowVersion of the column to be specified.

Parameters

isNull

Returns a Boolean indicating the specified DataColumn contains a null value.

col

The DataColumn object tested for a null value.

columnIndex

The zero-based index of the DataColumn tested for a null value.

columnName

The name of the DataColumn tested for a null value.

drv

One of the DataRowVersion enumeration values described in Table 25-5.

Example

The following example demonstrates how to check if the first column in the row contains a null value using an overload of the IsNull( ) method:

DataRow row;

// ... load data into the row
if(row.IsNull(0))
{
    // ... code to process the null value
}

Note

The IsNull( ) method can test data in situations in which null values are sometimes allowed in a column, thereby preventing the AllowDBNull property of the column from being set to false.

RejectChanges

DataRow.RejectChanges();

Rejects all changes made to the DataRow since the last time it was loaded or since the last time AcceptChanges( ) was called.

Parameters

None.

Example

This example demonstrates how to call the RejectChanges( ) method of the DataRow:

// create a table with a single column
DataTable dt = new DataTable();
dt.Columns.Add("MyColumn", typeof(System.Int32));

DataRow row;
row = dt.NewRow();
row["MyColumn"] = 1;
dt.Rows.Add(row);       // RowState = Added

row.AcceptChanges();    // RowState = Unchanged
row["MyColumn"] = 2;    // RowState = Modified
row.RejectChanges();    // RowState = Unchanged, row["MyColumn"] = 1

row.Delete();           // RowState = Deleted
row.RejectChanges();    // RowState = Unchanged
                        // The row isn't removed from the DataTable.

Notes

Calling RejectChanges( ) sets the RowState property of Deleted and Modified rows to Unchanged; the current values in the DataRow are set to the original values. Added rows are removed.

If the row is in edit mode as a result of calling BeginEdit( ), the edit is cancelled when RejectChanges( ) is called.

Calling RejectChanges( ) clears all RowError information and sets the HasErrors property to false.

SetColumnError

DataRow.SetColumnError(DataColumn col, String errorDesc);
DataRow.SetColumnError(Integer columnIndex, String errorDesc);
DataRow.SetColumnError(String columnName, String errorDesc);

Sets the error description for a specified column in the DataRow.

Parameters

col

The DataColumn object for which to set an error.

columnIndex

The index of the DataColumn for which to set an error.

columnName

The name of the DataColumn for which to set an error.

errorDesc

The description of the error.

Example

The following example shows how to set the error description for a column using the SetColumnError( ) method:

row.SetColumnError("MyColumn", "Custom error message for the column");

Note

The GetColumnError( ) method can retrieve the error description for a column in a row.

SetParentRow

DataRow.SetParentRow(DataRow row);
DataRow.SetParentRow(DataRow row, DataRelation dr);

Sets the parent DataRow, optionally based on a DataRelation.

Parameters

row

The new parent DataRow.

dr

The DataRelation for the parent relationship.

Example

The following example shows how to use the SetParentRow( ):

row.SetParentRow(parentRow, "MyDataRelation");


    Part I: ADO.NET Tutorial
    Part II: ADO.NET Core Classes
    Part III: API Quick Reference