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.
None.
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
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.
None.
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(); }
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.
None.
See the Example for the BeginEdit( ) method in this chapter.
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.
None.
The following example demonstrates using the Clear( ) method to clear the errors for a row:
row.ClearErrors();
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.
None.
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
A deleted row can be undeleted by calling the RejectChanges( ) method.
EndEdit |
DataRow.EndEdit(); |
Ends the edit on the DataRow, committing the changes made.
None.
See the Example for the BeginEdit( ) method in this chapter.
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.
Returns an array of DataRow objects containing the child rows.
The DataRelation object to use.
The name of the DataRelation to use.
One of the DataRowVersion enumeration values described in Table 25-5, which is in the HasVersion section of this chapter.
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.
Returns a string containing the error description for the specified DataColumn in the DataRow.
The DataColumn object for which to return the error.
The index of the DataColumn for which to return the error.
The name of the DataColumn for which to return the error.
The following example shows how to get the error description for a column named MyColumn using the GetColumnError( ) method:
String colError = row.GetColumnError("MyColumn");
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.
Returns an array of DataColumn objects that have errors.
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();
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.
Returns the parent DataRow.
The DataRelation to use when retrieving the parent row.
The name of the DataRelation to use when retrieving the parent row.
One of the DataRowVersion enumeration values described in Table 25-5, which is in the HasVersion section later in this chapter.
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.
Returns an array of DataRow objects.
The DataRelation to use when retrieving the parent row.
The name of the DataRelation to use when retrieving the parent row.
One of the DataRowVersion enumeration values described in Table 25-5 in the next section.
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 } }
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.
Returns a Boolean value indicating whether the specified version of a DataRow exists.
One of the DataRowVersion enumeration values described in Table 25-5.
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. |
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.
Returns a Boolean indicating the specified DataColumn contains a null value.
The DataColumn object tested for a null value.
The zero-based index of the DataColumn tested for a null value.
The name of the DataColumn tested for a null value.
One of the DataRowVersion enumeration values described in Table 25-5.
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 }
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.
None.
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.
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.
The DataColumn object for which to set an error.
The index of the DataColumn for which to set an error.
The name of the DataColumn for which to set an error.
The description of the error.
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");
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.
The new parent DataRow.
The DataRelation for the parent relationship.
The following example shows how to use the SetParentRow( ):
row.SetParentRow(parentRow, "MyDataRelation");