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

 AX_SetServerAOF()
 Creates a new Advantage Optimized Filter on the Advantage Database Server
------------------------------------------------------------------------------

 Syntax

     AX_SetServerAOF( <cFilterExpr>, [<lResolve>] ) -> logical

     <cFilterExpr>  Character expression containing the filter condition
     that records must meet in order to be included in the filter.

     <lResolve>     Optional logical value indicating how partially
     optimized filters and non-optimized filters should be resolved.  A
     value of .T. means that partially optimized filters and non-optimized
     filters should be immediately resolved into fully optimized filters.
     A value of .F. (the default) means partially optimized filters and
     non-optimized filters will be dynamically resolved into fully
     optimized filters as the record data is read.  If unsure which value
     to pass, .F. is recommended.

 Returns

     Returns .T. if the operation was successful, .F. if not.  If the
     operation was unsuccessful, AX_Error() will return information on why
     the operation failed.

 Description

     AX_SetServerAOF() will create an Advantage Optimized Filter (AOF) on
     the Advantage Database Server.  Any existing server AOF will be
     destroyed.  AX_SetServerAOF() will isolate the records which meet
     a condition and make all non-matching records "invisible".

     To clear an AOF set via AX_SetServerAOF(), call AX_ClearServerAOF().

     Advantage Optimized Filters provide high performance record filtering.
     AOFs speed filter processing by using index keys instead of table
     records.  If a specified field has an index built on it, then an AOF
     uses the index file rather than the table to process the filter.
     Performance is increased by reducing the amount of data that must be
     retrieved from the disk.

     An Advantage Optimized Filter is a snapshot of a table based on the
     given filter expression.  Therefore, an AOF can be thought of as a
     query on the table.  When an application calls AX_SetServerAOF(),
     the Advantage CA-Clipper RDD sends the filter expression to the
     Advantage Database Server to build the filter.  The server uses indexes
     that have been opened for the given table to quickly determine which
     records are in the AOF.  The actual AOF consists of an array of bits
     where each bit represents a single record.  The bit for each record
     that passes the filter condition is turned on.

     In general, AOFs are created by matching portions of the filter
     expression with index key expressions.  For example, if the field
     "lastname" is indexed, then Advantage can quickly optimize the filter
     expression "lastname >= 'W' .AND. lastname <= 'Wilkins'".  The
     Advantage Database Server will seek to the appropriate location in
     the index and traverse the index pages and set bits in the AOF for
     records that pass the filter condition.  When doing this, the Advantage
     Database Server does not read the actual records but will read only the
     necessary index pages needed to resolve the filter.

     There are two primary differences between server AOFs
     (AX_SetServerAOF()) and standard CA-Clipper filters (dbSetFilter()).
     The first is the speed.  When using an AOF, it is usually very fast
     because records that do not pass the filter condition do not have to
     be read from the disk.  It does take extra time, though, to build the
     AOF initially.  This time is usually not noticeable, however.  The
     other difference between AOFs and standard CA-Clipper filters is the
     freshness of the data.  Once a fully optimized AOF has been built, it
     is not updated until it is rebuilt by another call to AX_SetServerAOF()
     or AX_RefreshServerAOF().  Record updates that occur after the build
     of an AOF do not affect inclusion in the filter.  Regular filters are
     evaluated each time a record is requested.  Therefore, they always
     provide an up to date view of the data.

     Relative speeds between the two types of filters depend on the number
     of records in a table, the number of records that pass a filter
     condition, the optimization level of the filter, and server speed.
     It is common, though, for fully optimized AOFs to return data sets
     from 10 to 1000 times faster than regular filters.  The largest
     relative speed difference between the two types of filters will be
     seen when a small percentage of records pass the filter condition.
     For example, if a filter condition eliminates 99% of the records in
     a large table (i.e. only 1% of the records pass the filter condition),
     a fully optimized AOF may be 1000 times faster than a regular filter.
     With a filter condition that eliminates only 1% of the records in a
     table (i.e. 99% of the records pass the filter condition), a fully
     optimized AOF may be only slightly faster than a regular filter.

     The optimization for AOFs can be one of three levels. AOFs can be fully
     optimized (ADS_OPTIMIZED_FULL), partially optimized (ADS_OPTIMIZED_PART),
     or not optimized (ADS_OPTIMIZED_NONE). For example, the filter
     expression "lastname == 'Smith' .AND. firstname == 'John'" will be
     fully optimized (ADS_OPTIMIZED_FULL) if indexes exist on "lastname"
     and "firstname".  If an index exists on only one of those fields, then
     the filter will be partially optimized (ADS_OPTIMIZED_PART).  If no
     index exists for either field, then the filter will not be optimized
     (ADS_OPTIMIZED_NONE).

     When a filter is partially optimized or not optimized, each bit that
     is set in the AOF indicates that the corresponding record may or may
     not be in the filter.  Each bit that is cleared indicates that the
     record is definitely not in the AOF.  Thus, for each bit that is set
     for a partial or non-optimized filter, Advantage must read the actual
     record and evaluate some portion of the filter expression against the
     record to determine whether or not the record passes the AOF condition.
     When the lResolve parameter to the AX_SetServerAOF() function is .T.
     and the filter cannot be fully optimized, the Advantage Database
     Server tests each record whose corresponding bit is initially set
     against the filter expression after building the AOF.  For each record
     that the filter expression evaluates to false, the corresponding bit
     is cleared.  When the lResolve parameter is .F., the Advantage Database
     Server tests the records on an as-needed basis, which is probably the
     best case for most applications.

     The AOF engine does not use custom or unique indexes for optimization.
     In general, it also does not use conditional indexes.  When filtering
     deleted records, though, the AOF engine will use conditional indexes
     with conditions of "!DELETED()".

     Note:  Filters created on tables opened with the DBFNTXAX RDD will
     not be optimized.  Only filters created on tables opened by the
     DBFCDXAX RDD will be optimized.

 Example

     USE Accounts INDEX state VIA "DBFCDXAX"

     // Create an AOF on the server
     AX_SetServerAOF( 'state == "CA"', .F. )

     // List all records where state is California
     LIST state

     // Clear the Server AOF
     AX_ClearServerAOF()