Syntax

A similar condition to the OFF-END event that happens when you go past the end of a set of rows is when a FIND on a table fails. There is a FIND-FAILED event for a ProDataSet temp-table buffer, which is triggered when any attempt is made to find a row that is not in the table. This can be the result of a FIND statement, a FIND method on a buffer (FIND-FIRST and FIND-UNIQUE), or an action that implicitly finds a row in a ProDataSet temp-table. This is the syntax for the SET-CALLBACK-PROCEDURE method using FIND-FAILED:

buffer-handle:SET-CALLBACK-PROCEDURE( "FIND-FAILED", event-procedure
                                       [, procedure-handle ] ).

If an application procedure is looking for a row that may have been cached already in a ProDataSet, and it is not there, this event gives the procedure the opportunity to suspend the FIND in order to retrieve the row in question, and to do anything else that might be appropriate. So the event procedure could retrieve just the row for which the FIND failed, and add it to the local cache, or it could retrieve a set of related rows, or anything else. The event handler has to be able to determine from the context of the ProDataSet, which as always is passed into it as an INPUT parameter, what the missing data is. For example, if the current row in the ttOrder table as passed in does not yet have its OrderLines, then the code can make a call back to the server to return OrderLines of the current Order and append them to the ProDataSet. However, the event handler does not have direct access to the where-clause used on the FIND that failed.

As with the OFF-END event, it is completely transparent to ABL code that causes the initial failure that the FIND ever failed in the first place. If the event handler is able to add the needed row to the temp-table and RETURN NO-APPLY, the original statement simply succeeds as if the row had always been there.

As with the OFF-END event, this event is supported only for FINDs on ProDataSet temp-table buffers, not other buffers.

FIND-FAILED can be triggered by the static FIND and FIND FIRST statements and the dynamic method equivalents FIND-UNIQUE and FIND-FIRST. FIND-FAILED does not occur for any FIND NEXT or LAST statement or their equivalent GET methods for queries, or for the CAN-FIND function. By contrast, FIND NEXT and FIND LAST conditions that do not yield a row of data are handled by the query OFF-END event.

If a unique find (that is, an unqualified FIND statement or a FIND-UNIQUE method) fails due to ambiguity, the event does not fire, since the problem in that case is not that the row does not exist, but that there are too many matches.

It is important that the event handler does not do any FINDs on the same buffer the event is defined on. Attempting to do this will cause an error.

Set up an event handler for the FIND-FAILED buffer event illustrates how to use the FIND-FAILED event to fill in Item rows in the client-side user interface as they are explicitly referenced for the first time by an OrderLine that uses that Item.