Creating an OnUpdateRecord Event Handler

Go Up to Controlling the Update Process

The OnUpdateRecord event handles cases where a single update component cannot be used to perform the required updates, or when your application needs more control over special parameter substitution. The OnUpdateRecord event fires once for the attempt to apply the changes for each modified record in the update cache.

To create an OnUpdateRecord event handler for a dataset:

1. Select the dataset component.

2. Choose the Events page in the Object Inspector.

3. Double-click the OnUpdateRecord property value to invoke the code editor.

Here is the skeleton code for an OnUpdateRecord event handler:

procedure TForm1.DataSetUpdateRecord(DataSet: TDataSet;
UpdateKind: TUpdateKind; var UpdateAction: TUpdateAction);
begin
  { perform updates here... }
end;

The DataSet parameter specifies the cached dataset with updates.

The UpdateKind parameter indicates the type of update to perform. Values for UpdateKind are ukModify, ukInsert, and ukDelete. When using an update component, you need to pass this parameter to its execution and parameter binding methods. For example using ukModify with the Apply method executes the update object’s ModifySQL statement. You may also need to inspect this parameter if your handler performs any special processing based on the kind of update to perform.

The UpdateAction parameter indicates if you applied an update or not. Values for UpdateAction are uaFail (the default), uaAbort, uaSkip, uaRetry, uaApplied. Unless you encounter a problem during updating, your event handler should set this parameter to uaApplied before exiting. If you decide not to update a particular record, set the value to uaSkip to preserve unapplied changes in the cache.

If you do not change the value for UpdateAction, the entire update operation for the dataset is aborted. For more information about UpdateAction, see Specifying the Action to Take.

In addition to these parameters, you will typically want to make use of the OldValue and NewValue properties for the field component associated with the current record. For more information about OldValue and NewValue see “Accessing a field’s OldValue, NewValue, and CurValue properties” in the Delphi Developer’s Guide.

Important:
The OnUpdateRecord event, like the OnUpdateError and OnCalcFields event handlers, should never call any methods that change which record in a dataset is the current record.

Here is an OnUpdateRecord event handler that executes two update components using their Apply methods. The UpdateKind parameter is passed to the Apply method to determine which update SQL statement in each update object to execute.

procedure TForm1.EmpAuditUpdateRecord(DataSet: TDataSet;
  UpdateKind: TUpdateKind; var UpdateAction: TUpdateAction);
begin
  EmployeeUpdateSQL.Apply(UpdateKind);
  JobUpdateSQL.Apply(UpdateKind);
  UpdateAction := uaApplied;
end;

In this example the DataSet parameter is not used. This is because the update components are not associated with the dataset component using its UpdateObject property.

Advance To:

• Handling Cached Update Errors