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");