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

 aofCreateFilter()
 Creates a new Client Advantage Optimized Filter for ownership by a user
------------------------------------------------------------------------------

Syntax

     aofCreateFilter( [<cExpr> | <nLength>] ) -> numeric

     <cExpr>  Optional expression which records must meet to be
     placed in the filter.

     <nLength>  An empty filter is created which can only contain
     records with a record number less than or equal to the length specified
     if this optional parameter is specified.

     If no parameters are specified, an empty, user-owned filter will be
     created that can potentially hold all records in the table.

Returns

     Returns a numeric handle value used to identify the filter in future
     filter operations. If an error occurs, 0 (zero) is returned. If
     aofCreateFilter() failed, aofErrorCode() will return information on
     why the function failed.

Description

     aofCreateFilter() creates a user-owned Client Advantage Optimized
     Filter.  If a filter expression is passed for the parameter, then all
     records that meet that expression will be placed in the filter.  If
     a numeric parameter is passed, then an empty filter is created that
     can only contain records with a record number less than or equal to
     the specified numeric parameter.  If no parameter is passed, an empty
     filter will be created that can potentially hold all records in the
     table.

     If the filter expression cannot be fully optimized because no index
     exists that is based upon the field in the filter condition, then a
     partially optimized filter will be created.  The non-indexed or
     "unknown" portion of the filter may be resolved later using the
     aofResolvePartial() function.

     Notes:  If a <cExpr> filter expression is specified, this function
     may take a few moments to complete as it builds the filter.

     Always destroy user owned filters that are no longer being used with
     aofFreeFilter().

     Note:  Advantage has support for creating and using Advantage
     Optimized Filters on the server as well as on the client.  AOF usage
     on the client is more flexible than AOF usage on the server, but AOF
     usage on the server is much faster than AOF usage on the client.  If
     you don't need the flexibility of a Client AOF, then you should look
     into using Server AOFs via AX_SetServerAOF() for superior performance.

Example

     // Create a user-owned filter containing all people in California
     nHandle1 := aofCreateFilter( "state == 'CA'" )

     // Create an empty, user-owned filter that can potentially
     // contain all records in the table.
     nHandle2 := aofCreateFilter()

     // Create an empty, user-owned filter that can contain only records
     // number less than or equal to 100.
     nHandle3 := aofCreateFilter( 100 )

     // Print the maximum record number that can be in the filters
     // created on a 1000 record table.
     ? aofGetMaxRecords( nHandle1 )    // Should return 1000
     ? aofGetMaxRecords( nHandle2 )    // Should return 1000
     ? aofGetMaxRecords( nHandle3 )    // Should return 100

     // Free the user-owned filters
     aofFreeFilter( nHandle1 )
     aofFreeFilter( nHandle2 )
     aofFreeFilter( nHandle3 )