Release 10.1A: OpenEdge Development:
ProDataSets

> ## ProDataSet buffer FIND-FAILED event

> 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. For example:

> Syntax
>     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 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 the 4GL 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 don’t 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 itself not do any `FINDs` on the same buffer that the event is defined on. Attempting to do this will cause an error.

> The "Setting up an event handler for the FIND-FAILED buffer event" section 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`.

Copyright © 2005 Progress Software Corporation www.progress.com Voice: (781) 280-4000 Fax: (781) 280-4095