Modifying Entire Records
Go Up to Modifying Data
On forms, all data-aware controls except for grids and the navigator provide access to a single field in a record.
In code, however, you can use the following methods that work with entire record structures provided that the structure of the database tables underlying the dataset is stable and does not change. The following table summarizes the methods available for working with entire records rather than individual fields in those records:
Methods that work with entire records :
| Method | Description |
|---|---|
|
AppendRecord([array of values]) |
Appends a record with the specified column values at the end of a table; analogous to Append. Performs an implicit Post. |
|
InsertRecord([array of values]) |
Inserts the specified values as a record before the current cursor position of a table; analogous to Insert. Performs an implicit Post. |
|
SetFields([array of values]) |
Sets the values of the corresponding fields; analogous to assigning values to TFields. The application must perform an explicit Post. |
These method take an array of values as an argument, where each value corresponds to a column in the underlying dataset. The values can be literals, variables, or NULL. If the number of values in an argument is less than the number of columns in a dataset, then the remaining values are assumed to be NULL.
For unindexed datasets, AppendRecord adds a record to the end of the dataset and InsertRecord inserts a record after the current cursor position. For indexed datasets, both methods place the record in the correct position in the table, based on the index. In both cases, the methods move the cursor to the record's position.
SetFields assigns the values specified in the array of parameters to fields in the dataset. To use SetFields, an application must first call Edit to put the dataset in dsEdit mode. To apply the changes to the current record, it must perform a Post.
If you use SetFields to modify some, but not all fields in an existing record, you can pass NULL values for fields you do not want to change. If you do not supply enough values for all fields in a record, SetFields assigns NULL values to them. NULL values overwrite any existing values already in those fields.
For example, suppose a database has a COUNTRY table with columns for Name, Capital, Continent, Area, and Population. If a Bde.DBTables.TTable component called CountryTable were linked to the COUNTRY table, the following statement would insert a record into the COUNTRY table:
CountryTable.InsertRecord(['Japan', 'Tokyo', 'Asia']);
CountryTable->InsertRecord(ARRAYOFCONST(("Japan", "Tokyo", "Asia")));
This statement does not specify values for Area and Population, so NULL values are inserted for them. The table is indexed on Name, so the statement would insert the record based on the alphabetic collation of "Japan".
To update the record, an application could use the following code:
with CountryTable do
begin
if Locate('Name', 'Japan', loCaseInsensitive) then;
begin
Edit;
SetFields(nil, nil, nil, 344567, 164700000);
Post;
end;
end;
TLocateOptions SearchOptions;
SearchOptions->Clear();
SearchOptions << loCaseInsensitive;
if (CountryTable->Locate("Name", "Japan", SearchOptions))
{
CountryTable->Edit();
CountryTable->SetFields(ARRAYOFCONST(((void *)NULL, (void *)NULL, (void *)NULL,
344567, 164700000)));
CountryTable->Post();
}
This code assigns values to the Area and Population fields and then posts them to the database. The three NULL pointers act as place holders for the first three columns to preserve their current contents.