The TDataSet component provides several methods for inserting, updating, and deleting rows in the underlying dataset, as well as properties for reading both the current and old column values from the current row.

Inserting New Rows

---

Inserting a new row in a dataset is a three-step process. First, use the TDataSet Insert method to put the dataset into the insert state. This will:

• Fire the BeforeInsert event handler, if one is defined. To prevent the insert from occurring, return False as the result in the event handler.



• If the OwnerDatabase's AutoTransactions property is True (the default), then start a new transaction and then create a new row. If the Append flag (default False) is passed to the Insert method, then the new row will be appended to the end of the dataset. Otherwise, the new row will be inserted at the current row pointer in the dataset.



• Fire the OnInitrow event handler, if one is defined. The OnInitRow event handler allows the application to assign values to the columns in the new row without causing any of the columns, or the row, to be flagged as modified. This is a good place to assign default values for columns.



• Change the TDataSet State property to dsInsert once the dataset is in the insert state.



• Fire the AfterInsert event handler, if one is defined.

Once the dataset is in the insert state, you can use the Columns property to read or assign new values to the various columns in the row using the TDataColumn As* properties. When a column is assigned a new value, its Modified property is set to True.

When all column modifications have been made, use the Save method to complete the insert. This will:

• Fire the BeforeSave event handler, if one is defined. To prevent the save from occurring, return False as the result in the event handler.



• Save the row in the dataset, logging the insert if a transaction is in progress. At this point, the Modified property for the columns in the row will be reset to False.



• Fire the AfterSave event handler, if one is defined.



• Update any active sort and change the TDataSet State property to dsBrowse to reflect that the dataset is now in the browse state.
  
  
   With no active sort, rows are always sorted by their actual insertion order, so even if the Insert method was called without the Append flag, the newly-inserted row will move to the end of the dataset after the Save method completes.



• If the OwnerDatabase's AutoTransactions property is True (the default), then commit the active transaction.

If you want to cancel the insert operation, you can use the TDataSet Cancel method. This will:

• Fire the BeforeCancel event handler, if one is defined. To prevent the cancel from occurring, return False as the result in the event handler.



• Discard the row. The row pointer will return to the row pointer that was active prior to the Insert method being called.



• Fire the AfterCancel event handler, if one is defined.



• Change the TDataSet State property to dsBrowse to reflect that the dataset is now in the browse state.



• If the OwnerDatabase's AutoTransactions property is True (the default), then roll back the active transaction.

The following example inserts a new product into the Products dataset:

begin
   with Products do
      begin
      Products.Insert; // Required to avoid conflict with Insert system function
      Columns['ProductID'].AsString:='PHONE-HEADSET';
      Columns['Description'].AsString:='Hands-free phone handset';
      Columns['ListPrice'].AsFloat:=15.00;
      Columns['Shipping'].AsFloat:=2.00;
      Save;
      end;
end;

Updating Existing Rows

---

Updating an existing row in a dataset is a three-step process. First, use the TDataSet Update method to put the dataset into the update state. This will:

• Fire the BeforeUpdate event handler, if one is defined. To prevent the update from occurring, return False as the result in the event handler.



• If the OwnerDatabase's AutoTransactions property is True (the default), then start a new transaction.



• Change the TDataSet State property to dsUpdate once the dataset is in the update state.



• Fire the AfterUpdate event handler, if one is defined.

Once the dataset is in the update state, you can use the Columns property to read or assign new values to the various columns in the row using the TDataColumn As* properties. When a column is assigned a new value, its Modified property is set to True. You can use the TDataColumn OldValue property to access the value of any column before any new assignments were made to the row.

When all column modifications have been made, use the Save method to complete the update. This will:

• Fire the BeforeSave event handler, if one is defined. To prevent the save from occurring, return False as the result in the event handler.



• Save the row in the dataset, logging the update if a transaction is in progress. At this point, the Modified property for the columns in the row will be reset to False.



• Fire the AfterSave event handler, if one is defined.



• Update any active sort and change the TDataSet State property to dsBrowse to reflect that the dataset is now in the browse state.
  
  
   If any of the columns modified during the update are part of the active sort, then the row will automatically move to the correct position in the active sort.

If you want to cancel the update operation, you can use the TDataSet Cancel method. This will:

• Fire the BeforeCancel event handler, if one is defined. To prevent the cancel from occurring, return False as the result in the event handler.



• Discard any modifications to the row. The row pointer will stay in the same location.



• Fire the AfterCancel event handler, if one is defined.



• Change the TDataSet State property to dsBrowse to reflect that the dataset is now in the browse state.



• If the OwnerDatabase's AutoTransactions property is True (the default), then roll back the active transaction.

The following example finds a product in the Products dataset and updates its shipping cost:

begin
   with Products do
      begin
      if Find(['ProductID'],['PHONE-HEADSET'],False,True) then
         begin
         Update;
         Columns['Shipping'].AsFloat:=1.80;
         Save;
         end;
      end;
end;

Deleting Existing Rows

---

Deleting an existing row in a dataset can be done by calling the TDataSet Delete method. This will:

• Fire the BeforeDelete event handler, if one is defined. To prevent the delete from occurring, return False as the result in the event handler.



• If the OwnerDatabase's AutoTransactions property is True (the default), then start a new transaction and delete the existing row.



• Fire the AfterDelete event handler, if one is defined.

The following example finds a product in the Products dataset and deletes it:

begin
   with Products do
      begin
      if Find(['ProductID'],['FLASH-USB-16GB'],False,True) then
         Delete;
      end;
end;