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

  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(), aofCreateFilter(), or
  aofSetFilter(), the AOF is built.  Indexes that have been opened for the
  given table are used 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 >= 'S' .AND. lastname <= 'Schmidt'".  Advantage 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 AOFs (AX_SetServerAOF(),
  aofCreateFilter(), and aofSetFilter()) 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 a bit of extra time, however, 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 Client AOF has been built,
  it is not updated until it is rebuilt.  Record updates that occur after the
  build of a Client AOF do not affect inclusion in the filter.  Once a fully
  optimized Server AOF has been built, it is not updated to reflect updates
  made by other users until it is rebuilt.  Record updates made by the owner
  of the Server AOF that occur after the build of a Server AOF do affect
  inclusion in the filter. Record updates made by other users that occur
  after the build of a Server AOF do not affect inclusion in the filter.
  Traditional record 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 processor 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, partially optimized, or not optimized.  For example, the filter
  expression "lastname == 'Smith' .AND. firstname == 'John'" will be fully
  optimized if indexes exist on "lastname" and "firstname". If an index
  exists on only one of those fields, then the filter will be partially
  optimized.  If no index exists for either field, then the filter will not
  be optimized.

  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.

  Developers can speed up the filtering of deleted records (with SET DELETED
  ON) through the use of indexes built on "DELETED()". If a table has the
  index "DELETED()" built, then the AOF engine will automatically use that
  index to optimize the filtering of deleted records. For example, consider
  the following two statements:

     SET DELETED ON
     AX_SetServerAOF( "lastname='Smith'" )  // Could also use aofSetFilter()

  If a DBF table has an index built on "DELETED()", the AOF engine will
  automatically add ".AND. !DELETED()" to the filter expression. Note that
  if you change the deleted setting to SET DELETED OFF after building the
  AOF on a DBF table, then you should call aofRebuildFilter() or
  AX_RefreshServerAOF(), otherwise the AOF will still filter the deleted
  records. Filtering deleted records (SET DELETED ON) without an index built
  on "DELETED()" will have no effect on the optimization level. In other
  words, if the rest of the expression is fully optimized then the
  optimization level returned via AX_GetAOFOptLevel() and aofGetOptLevel()
  will still be fully optimized. In this case, AX_GetAOFRecordCount() and
  aofCountRecords() returns the number of records including the deleted
  records. To remove deleted records from AX_GetAOFRecordCount() and
  aofCountRecords(), there must be an index built on "DELETED()".

  The AOF engine does not use custom or unique indexes for optimization.

  Advantage has support for creating and using Advantage Optimized Filters
  on the server as well as on the client.  Versions of the Advantage
  CA-Clipper Libraries before 5.0 only had support for building and using
  AOFs 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.  For more information, review the "AOF on the server"
  APIs (that begin with the "AX_" prefix) in addition to the "AOF on the
  client" APIs (that begin with the "aof" prefix).

  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.

  CA-Clipper's SET FILTER command and other selected CA-Clipper commands
  which include a FOR clause can be optimized via Client AOFs. A FOR clause
  defines the condition that each record must meet in order to be processed.
  Client AOFs also have several low-level optimization functions exposed so
  CA-Clipper developers have complete flexibility and control over the filter
  optimization process.

  Client Advantage Optimized Filters provides 100% equivalent filter
  optimization functionality to Loadstone's ClipMore and SuccessWare's
  MachSix query Optimizers.  Advantage Server AOFs provide up to 10 times
  better performance than ClipMore or MachSix filters.


  Optimizing Expressions

  Depending on the filter expression or the expression in the FOR
  clause, queries will be fully or partially optimized.

  If the entire filter condition or FOR clause expression is based on
  indexed fields, the operation will be fully optimized. In some cases,
  this completely eliminates the need to access the table.

  If the filter condition or FOR clause contains expressions that are
  partially based on indexed fields, AOFs will partially optimize the
  operation.  Considerable performance enhancements will still result.

  If the Client AOF header file, AOF.CH, is included in your application,
  optimized expressions are those expressions found within a SET FILTER TO
  expression or the FOR clause of a supported command which must be in
  the following formats:

     <index key> <relational operator> <constant value>

  An <index key> can be any key of the open indexes in the currently
  selected work area.

  The <relational operator> may be any one of the following valid
  operators:

    =   == != #  $  ("$" cannot be directly optimized)
    <>  <  >  <= >=

  The <constant value> can be any expression that evaluates to a constant
  value.  This includes literal values, such as "100.00", or any memory
  variable, field, or user-defined function (UDF).

  Multiple expressions for optimization may be joined with the .AND. and
  .OR. logical operators to form complex expressions. It is not necessary
  for all expressions in the filter condition or the FOR clause to be
  index keys. Non-indexed expressions can still be optimized through
  partial optimization.


  Compiling and Linking "Client" Advantage Optimized Filters

  In order to use "Client" Advantage Optimized Filter functionality in your
  application, the Advantage Optimized Filter object file (AOF.OBJ) and
  library (AOF.LIB) must be added to your link script. In order to use
  Client AOF commands or constants in your application, the client
  Advantage Optimized Filter header file (AOF.CH) must be included in your
  source code.  If you only wish to use Client AOF functions in your
  application, then the Client AOF header file (AOF.CH) does not need to be
  included in your source code.  "Server" Advantage Optimized Filters do
  not require the AOF.LIB, AOF.OBJ, nor AOF.CH.  "Server" AOF functionality
  is included in the Advantage RDD library, DBFAXS.LIB.

  Note: Advantage Optimized Filters are only compatible with Advantage's
  DBFCDXAX RDD.

  To compile and link "Client" AOFs, do the following:

  1. Include the Advantage AOF.CH header file after the DBFCDXAX.CH header
  file in your source code if you wish to use Client AOF commands or constants.
  If you only wish to use Client AOF functions in your application, this step
  is not necessary.

   #include "DBFCDXAX.CH"
   #include "AOF.CH"

  2. Re-compile the application.

  3. Add the AOF.OBJ object file to your link command or link script.

  4. Add the AOF.LIB library to your link command or link script before
  the CLIPPER.LIB file.

  5. Re-link the application.


  Overlaying the Client AOF library

  The Advantage Optimized Filter library can be overlaid in your
  application with a real mode linker such as Blinker, RTLink, and
  WarpLink. A sample Blinker link script, AOF.LNK, has been provided to
  define which Advantage AOF modules can or cannot be overlaid.