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

 AX_CacheRecords()
 Get/Set the number of records to read-ahead and cached on the client
------------------------------------------------------------------------------

 Syntax

     AX_CacheRecords( [<nNumRecords>] ) -> numeric

     <nNumRecords>  The number of records to be read-ahead and cached on
     the client after a skip operation

 Returns

     If no parameter is passed, then returns the current number of records
     being read-ahead and cached on the client for the current work area.
     If a parameter is passed, then returns the previous number of records
     being read-ahead and cached on the client for the current work area.

 Description

     Advantage uses a read-ahead record caching scheme.  AX_CacheRecords()
     allows you to set the number of records to read-ahead and cache on the
     client.  Whenever you perform a skip operation after performing any
     other movement operation in your application, the next nNumRecords
     number of records will be read and transferred to the client rather
     than just a single record.  This allows the next nNumRecords - 1
     subsequent skip operations to be performed locally.  Thus, the record
     to which was skipped will be retrieved from client memory, rather than
     having to be read over the network from the server.  This should
     provide dramatic skip performance increases, especially when performing
     such operations as populating a browse window.  The default number of
     records that is read and cached on the client is the lesser of 10 or
     the number of records that can fit in a burst of packets from the
     Advantage Database Server to the Advantage client.  The default burst
     of packets can contain 8K bytes of data.

     Note:  Any records which are cached on the client will not
     reflect changes made by other users to those actual records in the
     table on the server.  To "dump" the cache of records currently in
     memory on the client and to refresh the current record, you can use
     the "SKIP 0" operation which forces the client record cache to be
     purged.

     Calling AX_CacheRecords() with a value of 0 or 1 turns off record
     caching.

     The maximum number of records that can be cached on the client is the
     number of records that fit into 64K bytes of data.  Each record has 4
     bytes overhead, so this equation yields the maximum read-ahead record
     value nNumRecords:

         nNumRecords = 65535 / ( record size + 4 )

     In theory, the ideal value for the number of records to read-ahead
     would be the number of records that normally appear in your
     application's browse window.  For example, if your application's
     browse window contains twenty records, you should consider changing
     the read-ahead record value to 20 so that the entire set of records
     can be read with exactly one server request.  However, if your
     application is repeatedly doing just a single skip, then reading ahead
     twenty records and not using them may degrade your application's
     performance.  You may want to experiment with the number of records to
     read-ahead in your application (or per function in your application)
     to find a value that provides best performance.

 Example

     USE Accounts INDEX state VIA "DBFCDXAX"

     // Set number of records to read-ahead to 5
     AX_CacheRecords( 5 )

     // A GO TOP will just read over the top record in the state index
     GO TOP

     // This SKIP will read over the next 5 records (in indexed order)
     //   from the server.
     SKIP

     // These next 4 skips will not have to go to the server to skip and
     //   read the data.  Because of read-ahead record caching, these records
     //   have already been read and are cached on the client.  Thus, these
     //   4 skips will basically be "instant" and will generate no network
     //   traffic.
     SKIP
     SKIP
     SKIP
     SKIP

     // This SKIP will (again) read over the next 5 records (in indexed
     //   order) from the server.
     SKIP