Adding New Records
Go Up to Modifying Data
A dataset must be in dsInsert mode before an application can add new records. In code, you can use the Insert or Append methods to put a dataset into dsInsert mode if the read-only CanModify property for the dataset is True.
When a dataset transitions to dsInsert mode, it first receives a BeforeInsert event. After the transition to insert mode is successfully completed, the dataset receives first an OnNewRecord event hand then an AfterInsert event. You can use these events, for example, to provide initial values to newly inserted records:
procedure TForm1.OrdersTableNewRecord(DataSet: TDataSet);
begin
DataSet.FieldByName('OrderDate').AsDateTime := Date;
end;
void __fastcall TForm1::OrdersTableNewRecord(TDataSet *DataSet)
{
DataSet->FieldByName("OrderDate")->AsDateTime = Date();
}
On forms in your application, the data-aware grid and navigator controls can put a dataset into dsInsert state if
- The control's ReadOnly property is False (the default), and
- CanModify is True for the dataset.
Note: Even if a dataset is in dsInsert state, adding records may not succeed for SQL-based databases if your application's user does not have proper SQL access privileges.
Once a dataset is in dsInsert mode, a user or application can enter values into the fields associated with the new record. Except for the grid and navigational controls, there is no visible difference to a user between Insert and Append. On a call to Insert, an empty row appears in a grid above what was the current record. On a call to Append, the grid is scrolled to the last record in the dataset, an empty row appears at the bottom of the grid, and the Next and Last buttons are dimmed on any navigator component associated with the dataset.
Data-aware controls for which inserting is enabled automatically call Post when a user executes any action that changes which record is current (such as moving to a different record in a grid). Otherwise you must call Post in your code.
Post writes the new record to the database, or, if you are caching updates, Post writes the record to an in-memory cache. To write cached inserts and appends to the database, call the dataset's ApplyUpdates method.
Inserting records
Insert opens a new, empty record before the current record, and makes the empty record the current record so that field values for the record can be entered either by a user or by your application code.
When an application calls Post (or ApplyUpdates when using cached updates), a newly inserted record is written to a database in one of three ways:
- For indexed Paradox and dBASE tables, the record is inserted into the dataset in a position based on its index.
- For unindexed Paradox and dBASE tables, the record is inserted into the dataset at its current position.
- For SQL databases, the physical location of the insertion is implementation-specific. If the table is indexed, the index is updated with the new record information.
Appending records
Append opens a new, empty record at the end of the dataset, and makes the empty record the current one so that field values for the record can be entered either by a user or by your application code.
When an application calls Post (or ApplyUpdates when using cached updates), a newly appended record is written to a database in one of three ways:
- For indexed Paradox and dBASE tables, the record is inserted into the dataset in a position based on its index.
- For unindexed Paradox and dBASE tables, the record is added to the end of the dataset.
- For SQL databases, the physical location of the append is implementation-specific. If the table is indexed, the index is updated with the new record information.
See Also
- Editing Records
- Deleting Records
- Posting Data to the Database
- Canceling Changes
- Modifying Entire Records