Advantage Client Engine
Create an Advantage Optimized Filter (AOF) for the given table
UNSIGNED32 |
AdsSetAOF ( ADSHANDLE hTable, UNSIGNED8 *pucFilter, UNSIGNED16 usOptions ); |
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. |
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.
Dynamic AOFs: Filter membership is affected by modifications all users make to record data.
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.
Keyset-Driven AOFs: Filter membership is only affected by updates from the filter owner (the table instance that set the filter). Updates made by other users will not affect a record’s membership in the filter.
Fixed AOFs: Filter membership does not change. If other users modify records they will always remain visible within this fixed filter, even if the changes have modified field values such that the record no longer passes the original filter expression.
For more information, see Advantage Optimized Filters.
AdsSetAOF( hTable, "lastname > ‘Anderson’", ADS_RESOLVE_IMMEDIATE | ADS_FIXED_AOF );