Improved Deleted Record Handling

DataFlex 18.1 adds support to allow DDOs and DEOs to better handle situations where a current record is deleted by another user. The main goal is to ensure that missing, probably deleted, records are better handled when:

Switching window views
Working with Windows and web grids
Saving and deleting records

Changes were made in the runtime and packages.

Runtime Changes

Two new DDO functions have been added:

Function ReadByRowIdEx Integer iFile RowID riId Returns Boolean
Function FindByRowIdEx Integer iFile RowID riId Returns Boolean

These functions work similarly to ReadByRowId and FindByRowId, except they do not raise a find error and return whether the operation was successful. Success means the message executed as intended, which may not indicate that a record was found. If these functions are passed a null rowId, they will clear, set Found to false, but return True because the operation was a success. If it returns False, there is a good chance your record was deleted by someone else.

The DSO Refind_Records message now does not raise an error if any of the records cannot be found. This is a behavior change that we believe is appropriate.

A new error has been defined: 4527 - DFERR_CANT_REFIND_RECORD. This will be a handled error (a user error). The purpose of this error is to notify the developer or the user that a record that was previously found can no longer be found.

In the runtime, Request_Validate, Request_Save, and Request_Delete will now return this error instead of the current unhandled error 25 - DFERR_REC_NOT_FOUND when records cannot be refound or reread. When a user sees this, they will understand that "someone must have deleted this record - this is not a bug." In the packages, grids will utilize this when records no longer exist.

Package Changes

Various cDbCJGrid packages have been updated to better handle cached records that are deleted from the back-end. This involves four new interfaces for cDbCJGrid.

When a cDbCJGrid attempts to navigate to a row where the record cannot be found, it will recognize this and consider the cache invalid. It performs the following actions:

Sets the property pbCacheError to True, which will call the method HandleCacheError in the next idle cycle.
HandleCacheError will optionally report this as a handled error and attempt to reload the cache. If it cannot reload the cache, it reports an unhandled error (most likely a programming error).

Property pbCacheError

This is a system-maintained property that is set to True when there is a cache error. This typically indicates that a record in the cache has been deleted in the back end. When this occurs, the cDbCJGrid will call HandleCacheError.

Property pbSuppressCacheError

Determines if the grid should report an error when a grid cache error occurs (i.e., when a record in the grid cache has been deleted on the back end). The default value is False, so errors are normally reported. This property is tested in HandleCacheError. Setting this to True provides a way to correct the cache problem without notifying the end user, who may not know how to handle the error.

Procedure HandleCacheError

This method is called when the grid cannot find a cached record on the back end and has set pbCacheError. It is used to handle the error, typically reporting a handled error. If pbSuppressCacheError is set to True, no error is reported. When pbSuppressCacheError is set to False (the default), it will call the method ReportCacheError, which raises the handled DFERR_CANT_REFIND_RECORD error.

Next, this method will attempt to refresh the grid's cache based on the current record. Note that the cache error usually occurs when navigating from a valid current record to another record. If the grid cannot be refreshed around the current record, it refreshes the grid from the top.

This method can be augmented or overridden, but you must ensure that any customization handles the error and refreshes the grid with valid records. If you plan to augment or override this method, it is recommended to first study the code in the package.

Procedure ReportCacheError

This procedure is called when a report cache error should be reported. By default, it displays the handled error message DFERR_CANT_REFIND_RECORD with the additional error text of C_$InvalidRowInCache (in English: "Invalid row in grid cache. Record might have been deleted"). This procedure was created so you can define your own more specific custom errors for your grid classes and objects. For example:

Procedure ReportCacheError
    Error DFERR_CANT_REFIND_RECORD "A record in your grid was probably deleted by someone else. The grid will refresh itself and all should be fine. This is a normal occurrence, so don't call us!"
End_Procedure

It is possible that a cDbGrid's current row record may be deleted. This can happen with any DEO object, and grids handle this in the same way any DEO handles it. As long as you do not attempt to save or delete the record, no error will be raised. If you attempt to save or delete the record, the DDO will raise a DFERR_CANT_REFIND_RECORD error. Note that errors will not be raised when you navigate back to a view when the DDO records are refreshed. You will only see the error if you attempt to change the record (save or delete).