| [ Team LiB ] |
|
25.4 Methods Reference
Commits all changes made to the DataRow since the last time it was loaded or since the last time AcceptChanges( ) was called. ParametersNone. ExampleThe 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
NotesCalling 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.
Puts the DataRow into edit mode, suspending the events that trigger validations rules. ParametersNone. ExampleThe 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();
}
NotesUpdates 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.
Cancels the edit on the DataRow, discarding the changes. ParametersNone. ExampleSee the Example for the BeginEdit( ) method in this chapter. NotesUpdates 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.
Clears all errors for the DataRow. ParametersNone. ExampleThe following example demonstrates using the Clear( ) method to clear the errors for a row: row.ClearErrors(); NoteThe 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.
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. ParametersNone. ExamplesThree 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 NoteA deleted row can be undeleted by calling the RejectChanges( ) method.
Ends the edit on the DataRow, committing the changes made. ParametersNone. ExampleSee the Example for the BeginEdit( ) method in this chapter. NotesUpdates 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.
Gets an array of DataRow objects that are the child rows of the DataRow, based on a specified DataRelation. Parameters
ExampleThe 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
}
}
Gets the error description for a specified column in the DataRow. Parameters
ExampleThe following example shows how to get the error description for a column named MyColumn using the GetColumnError( ) method: String colError = row.GetColumnError("MyColumn");
NoteThe SetColumnError( ) method can set the error description for a column in a row.
Gets an array of DataColumn objects for the columns having errors in the DataRow. Parameter
ExampleThe 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();
NotesAn 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( ).
Gets the parent DataRow of the current row, based on a DataRelation. Parameters
ExampleThe 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
}
Gets an array of DataRow objects that are the parent rows of the current row, based on a DataRelation. Parameters
ExampleThe 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
}
}
NoteAlthough 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.
Returns a value that indicates whether the specified DataRowVersion for the DataRow exists. Parameters
ExampleThe following example shows how to check if a row has a proposed version that uses the HasVersion( ) method: Boolean hasVersion = row.HasVersion(DataRowVersion.Proposed);
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
ExampleThe 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
}
NoteThe 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.
Rejects all changes made to the DataRow since the last time it was loaded or since the last time AcceptChanges( ) was called. ParametersNone. ExampleThis 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.
NotesCalling 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.
Sets the error description for a specified column in the DataRow. Parameters
ExampleThe 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");
NoteThe GetColumnError( ) method can retrieve the error description for a column in a row.
Sets the parent DataRow, optionally based on a DataRelation. Parameters
ExampleThe following example shows how to use the SetParentRow( ): row.SetParentRow(parentRow, "MyDataRelation");  |
| [ Team LiB ] |
|