Specifying the UpdateObject Property for a Dataset
Go Up to Using Update Objects to Update a Dataset
One or more update objects can be associated with a dataset to be updated. Associate update objects with the update dataset either by setting the UpdateObject property of the dataset component to the update object or by setting the DataSet property of the update object to the update dataset. Which method is used depends on whether only one base table or multiple tables in the update dataset are to be updated.
You must use one of these two means of associating update datasets with update objects. Without proper association, the dynamic filling of parameters in the update object’s SQL statements cannot occur. Use one association method or the other, but never both.
How an update object is associated with a dataset also determines how the update object is executed. An update object might be executed automatically, without explicit intervention by the application, or it might need to be explicitly executed. If the association is made using the dataset component’s UpdateObject property, the update object will automatically be executed. If the association is made with the update object’s DataSet property, you must execute the update object programmatically.
The following sections explain the process of associating update objects with update dataset components in greater detail, along with suggestions about when each method should be used and effects on update execution.
Using a Single Update Object
When only one of the base tables referenced in the update dataset needs to be updated, associate an update object with the dataset by setting the UpdateObject property of the dataset component to the name of the update object.
IBQuery1.UpdateObject := UpdateSQL1;
The update SQL statements in the update object are automatically executed when the ApplyUpdates method of the update dataset is called. The update object is invoked for each record that requires updating. Do not call the ExecSQL method of the update object in a handler for the OnUpdateRecord event as this will result in a second attempt to apply each record’s update.
If you supply a handler for the OnUpdateRecord event of the dataset, the minimum action that you need to take in that handler is setting the UpdateAction parameter of the event handler to uaApplied. You may optionally perform data validation, data modification, or other operations like setting parameter values.
Using Multiple Update Objects
When more than one base table referenced in the update dataset needs to be updated, you need to use multiple update objects: one for each base table updated. Because the UpdateObject of the dataset component only allows one update object to be associated with the dataset, you must associate each update object with the dataset by setting its DataSet property to the name of the dataset. The DataSet property for update objects is not available at design time in the Object Inspector. You can only set this property at runtime.
IBUpdateSQL1.DataSet := IBQuery1;
The update SQL statements in the update object are not automatically executed when the ApplyUpdates method of the update dataset is called. To update records, you must supply a handler for the OnUpdateRecord event of the dataset component and call the ExecSQL or Apply methods of the update object. This invokes the update object for each record that requires updating.
In the handler for the OnUpdateRecord event of the dataset, the minimal actions that you need to take in that handler are:
- Calling the
SetParamsmethod of the update object (if you later callExecSQL). - Executing the update object for the current record with
ExecSQLorApply. - Setting the
UpdateActionparameter of the event handler touaApplied.
You may optionally perform data validation, data modification, or other operations that depend on each record’s update.
It is also possible to have one update object associated with the dataset using the
UpdateObject property of the dataset component, and the second and subsequent update objects associated using their DataSet properties. The first update object is executed automatically on calling the ApplyUpdates method of the dataset component. The rest need to be manually executed.