There are events that you can define for the process of making local changes to the records in a ProDataSet.
The mechanism for defining change events is exactly the same as for defining FILL events. You use the SET-CALLBACK-PROCEDURE method to associate an internal procedure name and the handle of an active procedure instance containing that internal procedure with a fixed event name. Since these are events that occur when the temp-tables themselves are modified while TRACKING-CHANGES is true, it is reasonable that the event procedure could be located either on the client side or on the server side of a distributed application. This depends on whether the temp-tables are being changed by user actions on the client or by other business logic actions on the server. Note that there are no distributed calls to event procedures. The AVM will not automatically run an event in a server-side procedure from the client. The expectation is that if the temp-table is changed on the client, then the supporting event logic is running on the client. The application can, of course, make its own calls from the client event procedures to procedures on the server, but you must consider the expense of doing this and avoid it wherever possible.
In every case the event procedure receives the ProDataSet object as an INPUT parameter, just as FILL events do. The event procedure can define the parameter as DATASET or as DATASET-HANDLE, depending on whether it has a static definition of the ProDataSet. All of these events are defined on a temp-table buffer, not the ProDataSet itself. That is, the SET-CALLBACK-PROCEDURE method is executed on a temp-table buffer handle.
Event procedures are defined for create and delete events. There is no support for a modify event. This section uses the general term "change statement" to refer to any language statement that causes one of these events. The event procedures all have access to the before images of changed or deleted records using the attributes described earlier.
If you RETURN ERROR in a callback procedure, this raises the AVM error condition as it does elsewhere. You can also set the ERROR-STRING attribute of a row to signal an error internally. In all cases, if a callback procedure attempts to raise error, the ProDataSet handle ERROR attribute is set to true. Each event reacts to the error condition in a slightly different manner. The AVM supports the following events for ProDataSet row-level changes:
ROW-CREATE — This is fired on a CREATE temp-table statement, after the record is created in the temp-table. The current buffer for the temp-table is available and contains initial values as defined in the temp-table definition (or inherited from the schema). This event could be used to calculate other initial values for other fields or to make changes to other records (such as to update a child record count in some parent record).
You could also reject the create by deleting the new temp-table record. This will cause it to be expunged from the before-table as well as the after-table. Any CREATE trigger procedure is executed after this event is handled.
When an error is raised in a ROW-CREATE callback procedure, usually through RETURN ERROR or a structured UNDO, THROW, error is raised to the caller.
ROW-DELETE— This is fired on a DELETEtemp-table statement, before the record is deleted. The event procedure could use this event to RETURN NO-APPLY to cancel the delete or to make adjustments to other records based on the delete (such as updating totals in other records). Since the record has not yet been deleted, the record is in the temp-table buffer and the code can look at its values. This event fires only after the AVM has verified that the delete operation is valid, for example, that there is a record in the buffer to delete. Therefore the event code can assume that the delete will go through unless canceled by the event procedure itself, and can take actions based on the record deletion while the record is still there to be looked at. Any DELETE trigger procedure is executed after this event is handled.
When an error is raised in a ROW-DELETE callback procedure, usually through RETURN ERROR or a structured UNDO, THROW, error is raised to the caller.
ROW-UPDATE— This is fired immediately before the record is updated in the temp-table. It typically occurs when the buffer scope ends, the transaction scope ends, the RELEASE statement or BUFFER-RELEASE( ) method is run on the buffer, or the buffer is needed for another record. The AVM sets the SELF system handle to the handle of the buffer on which the event procedure is running before calling the event handler. If the event handler returns NO-APPLY or ERROR, the return is ignored. The handler has run, and it is too late to undo any changes to the record. You can use this event to determine if and how a record has changed by reading the buffer in the before-image table (using the SELF:BEFORE-ROWID attribute) and comparing it to the updated buffer. You can also use this event in the event handler to update fields in the record (for example, to supply a calculated field). You cannot read another record into the buffer on which the event procedure is running in the event handler. If you need to read another record, use a different buffer to avoid disturbing the record you are currently updating.
When error is raised in a ROW-UPDATE callback procedure, usually through RETURN ERROR or a structured UNDO, THROW, error is not raised to the caller.
ROW-CREATE — This is fired on a CREATE temp-table statement, after the record is created in the temp-table. The current buffer for the temp-table is available and contains initial values as defined in the temp-table definition (or inherited from the schema). This event could be used to calculate other initial values for other fields or to make changes to other records (such as to update a child record count in some parent record).
