Click above to get retro games delivered to your door ever month!

 aofFiltToUser()
 Transfers ownership of a Client Advantage Optimized Filter from the system
 to the user
------------------------------------------------------------------------------

Syntax

     aofFiltToUser() -> numeric

Returns

     A numeric handle to the now user-owned filter. A value of 0 (zero)
     indicates the ownership transfer failed. If aofFiltToUser() failed,
     aofErrorCode() will return information on why the function failed.

Description

     aofFiltToUser() will transfer ownership of the system-owned filter
     to the user, but the filter will still be set and working for the
     system (as far as movement operations are concerned).  To disable
     the filter from working for the system, call dbClearFilter().

     Since the user now has ownership of the filter, the filter must be
     freed via aofFreeFilter() when the filter is no longer needed.

Example

     USE Salesmen INDEX Sales

     // Create a system-owned filter
     aofSetFilter( "SaleTot > 10000" )

     GO TOP

     // Get information about the system-owned filter
     aInfo := aofFilterInfo()

     // Display the filter owner.  Note it's owned by the system.
     ? "Filter owner = "
     ?? aInfo[ INFO_OWNER ]               //  1 - System owned

     // Change ownership from system to user
     nHandle := aofFiltToUser()

     // Get information about the user-owned filter
     aInfo := aofFilterInfo( nHandle )

     // Note that the user owns the filter now
     ? "Filter owner = "
     ?? aInfo[ INFO_OWNER ]               // 2 - User owned

     // Disable the filter from working for the system
     dbClearFilter()

     // Get info once again
     aInfo := aofFilterInfo( nHandle )

     // The user still retains ownership even after clearing the filter
     ? "Filter owner = "
     ?? aInfo[ INFO_OWNER ]               // 2 - User owned

     // The filter must be freed because the user owns it
     aofFreeFilter( nHandle )