AdsSetAOF

Advantage Client Engine

Create an Advantage Optimized Filter (AOF) for the given table

Syntax

UNSIGNED32

AdsSetAOF ( ADSHANDLE hTable,

UNSIGNED8 *pucFilter,

UNSIGNED16 usOptions );

Parameters

hTable (I)

Handle of a table or cursor to set the filter on.

pucFilter (I)

Null terminated filter expression.

usOptions (I)

Option to indicate how the filter should be resolved in the event that the expression cannot be fully optimized. This flag is also used to indicate how filter membership is affected by data changes. Options are ADS_RESOLVE_IMMEDIATE, ADS_RESOLVE_DYNAMIC, ADS_DYNAMIC_AOF, ADS_KEYSET_AOF, and ADS_FIXED_AOF.

Remarks

AdsSetAOF creates an Advantage Optimized Filter on the given table using all currently open indexes. Filters created on tables opened with the ADS_NTX option will not be optimized; only filters created on ADS_CDX, ADS_VFP or ADS_ADT tables will be optimized. The ADS_RESOLVE_IMMEDIATE option causes the server to immediately remove all records from the result set that do not pass the filter if it cannot be fully optimized. This means it must evaluate the expression for every record that is potentially in the result set to determine membership conclusively. The ADS_RESOLVE_DYNAMIC option causes the server to determine membership as the data is read by the client (e.g., from a browse).

The benefit to using ADS_RESOLVE_IMMEDIATE is that a more "accurate" record count is returned and can be retrieved via AdsGetRecordCount. In addition, once the full resolution has been done, the server does not have to evaluate the expression on any subsequent record movements. The drawback to the immediate resolution is the extra time needed to perform the resolution. With dynamic resolution, records are removed from the filter as the client requests record movement. This means that the resolution time can be spread out through a browse of the data, and the elapsed time for the resolution will not be noticed. Also, a skip (browse) through the entire data set will remove all records from the filter that do not meet the condition. A second pass through the data, then, will not require those records to be evaluated. In general, it is better to use dynamic resolution for most applications.

The usOptions parameter is a multi-purpose option flag used to specify both the resolution type and the AOF type.

Resolution Types:

 ADS_RESOLVE_IMMEDIATE

 ADS_RESOLVE_DYNAMIC

 

AOF Types:

 ADS_DYNAMIC_AOF

 ADS_KEYSET_AOF

 ADS_FIXED_AOF

 

The resolution portion of the options flag is required. If an AOF type is not specified, ADS_DYNAMIC_AOF will be assumed.

Different AOF types provide different levels of filter membership.

Note Dynamic filters are only supported when connected to the Advantage Database Server. If using the Advantage Local Server, dynamic filters will behave like keyset filters.

For more information, see Advantage Optimized Filters.

Example #1

Click Here

Example #2

AdsSetAOF( hTable, "lastname > ‘Anderson’", ADS_RESOLVE_IMMEDIATE | ADS_FIXED_AOF );

See Also

AdsClearAOF

AdsRefreshAOF

AdsGetAOF

AdsGetAOFOptLevel

AdsEvalAOF

AdsSetFilter