Dataset change events can occur in the server or in the client and are handled where they occur.

A change event is triggered when a record in a temp-table of a dataset is created, deleted, or updated. Change events are associated with a particular temp-table or temp-table buffer.

The following table lists the events that are triggered during a create, delete, or update operation:

Event When it occurs Examples
ROW-CREATE Immediately after the record is created, a ROW-CREATE event occurs. The current buffer for the temp-table is available and contains initial values as defined in the temp-table definition.
  • Calculate initial values.
  • Make changes to other records based on the creation of the new record.
  • Reject the creation by deleting the new temp-table record.
ROW-DELETE Immediately before the temp-table record is deleted, a ROW-DELETE event occurs. Since the record has not yet been deleted, the record remains in the temp-table buffer and the code can access its values.
  • Raise an error.
  • Cancel the delete.
  • Make adjustments to other records based on the delete.
ROW-UPDATE Immediately before the temp-table record is updated, a ROW-UPDATE event occurs. Log all changes to a table.

Use a change event handler in the client

In the following example, a ROW-UPDATE event handler for the ttOrderLine temp-table buffer is used to limit the maximum discount an order line can have to 20%. This event handler, named DiscountTooHigh, is an internal procedure of the external procedure library file that is used in the client. 

/* external procedure for event handlers */
BLOCK-LEVEL ON ERROR UNDO, THROW.

{include/dsOrderOrderLine.i}

PROCEDURE DiscountTooHigh:
  DEFINE INPUT PARAMETER DATASET FOR dsOrderOrderLine.

  IF ttOrderLine.Discount > 20
  THEN
    ttOrderLine.Discount = 20.
END PROCEDURE.

The following is the client code that updates the dataset. To use the event handler, the client code first runs the external procedure as PERSISTENT and then associates the ROW-UPDATE event handler, DiscountTooHigh, with the ttOrderLine temp-table buffer. When the client updates data in the ttOrderLine record, it does so by calling the SetDiscount internal procedure. In the SetDiscount procedure, a transaction block is required around the code that updates the temp-table. As with database transactions, scope ABL transactions to be as small as possible for good performance. When SetDiscount updates the record, the DiscountTooHigh event handler runs.

/* client code to use the event handler */
/* Define the procedure handle variable */
DEFINE VARIABLE hDSEventHandlers AS HANDLE NO-UNDO.
. . .
/* Run the persistent procedure and set the handle variable */
RUN dsOrderOrderLine_EventHandlers.p PERSISTENT SET hDSEventHandlers.
. . .
/* Associate the event handler with the temp-table buffer */
BUFFER ttOrderLine:SET-CALLBACK-PROCEDURE("ROW-UPDATE","DiscountTooHigh",hDSEventHandlers).
. . .
/* Procedure to update the temp-table that calls SetDiscount */
. . .
DELETE PROCEDURE hDSEventHandlers.
RETURN.


PROCEDURE SetDiscount:
  DEFINE INPUT PARAMETER pDiscount AS INTEGER NO-UNDO.
. . .
  TEMP-TABLE ttOrderLine:TRACKING-CHANGES = TRUE.

  ttOrderLine.Discount = pDiscount.

  TEMP-TABLE ttOrderLine:TRACKING-CHANGES = FALSE.
. . .
END PROCEDURE.

See also

ProDataSet change events

Row-level events