/*
 * $Id: readme.txt,v 1.10 2002/12/17 18:52:56 brianhays Exp $
 */
/*
 * $DOC$
 * $FUNCNAME$
 *      ADS Overview
 * $CATEGORY$
 *      Document
 * $ONELINER$
 *      Advantage Database Server RDD
 * $DESCRIPTION$
 *      RDDADS is an RDD for the Advantage Database Server, an xBase data
 *      server by Extended Systems <www.advantagedatabase.com>.
 *      The RDD was written by Alexander Kresin <alex@belacy.belgorod.su>
 *      Additional code and documentation was added by
 *      Brian Hays <bhays@abacuslaw.com>.

 *      Your Harbour application can access a remote database server for a
 *      true client/server architecture, or it can use the "local server"
 *      ADSLOC32.DLL for stand-alone or even small network installations.
 *
 *      <b>For using this RDD you need to have:   </b></par>
 *      <b>ACE32.DLL    ( Advantage Client Engine ),   </b></par>
 *      <b>AXCWS32.DLL  ( communication layer for remote server ) or   </b></par>
 *      <b>ADSLOC32.DLL ( local server )   </b></par>
 *
 *      You need also to create ace32.lib with the help of implib.exe:
 *      implib ace32.lib ace32.dll
 *
 *      Then build rddads.lib using make_b32.bat or make_vc.bat.
 *
 *      For building executables don't forget to include the ace32.lib and
 *      rddads.lib in the make file or link script.
 *
 *      You also need to include in your PRG file following lines:
 *
 *      REQUEST _ADS   </par>
 *      rddRegister( "ADS", 1 )   </par>
 *      rddsetdefault( "ADS" )   </par>
 *
 *      By default RDDADS is tuned for remote server and cdx indexes. To
 *      change this you may use these commands defined in ads.ch:
 *
 *      SET SERVER LOCAL
 *      SET SERVER REMOTE
 *
 *      SET FILETYPE TO NTX
 *      SET FILETYPE TO ADT
 *      SET FILETYPE TO CDX
 *
 *      or functions AdsSetServerType(), AdsSetFileType().
 *      See the header file ADS.CH for details.
 *
 *      Note that the default local server (ADSLOC32.DLL) is useable for
 *      file sharing on a small network.  The default DLL is limited to
 *      5 users, but an unlimited version is available from Extended Systems.
 *
 *      MAX OPEN TABLES: The server (even local) has its own setting for
 *      Max Tables allowed open.  For the Local Server, it can be set in
 *      ADSLOCAL.CFG.  The default is only 50!
 *      For the Windows Remote Servers, use the Configuration Utility, or
 *      increase the setting for the TABLES configuration value in the Advantage
 *      Database Server configuration registry key using the Registry Editor.
 *      For NetWare, edit the configuration file ADS.CFG.

 *      See ACE.HLP under ADSLOCAL.CFG, or the Advantage Error Guide for
 *      error 7005.

 *  $COMPLIANCE$
 *      Every attempt has been made to make the rdd compliant with the
 *      standard dbfcdx rdd at the .PRG level.
 *      One important difference is the handling of structural indexes.
 *      ACE will <b>always</b> automatically open an index with the same
 *      name as the data file.  There is no way to turn this feature off.

 *      You can use the Set() function call as well as the equivalent
 *      commands for SET DEFAULT TO, DATEFORMAT, DELETE, and EPOCH.
 *      Harbour automatically makes the call to ADS to change its internal
 *      setting to match Harbour's.

 *      INDEXING and Progress Displays:
 *      ACE32.DLL does not support the EVAL/EVERY clauses. Remember, there
 *      is an external process doing the indexing that knows nothing of
 *      Harbour expressions or codeblocks. Even with Local Server it's the
 *      DLLs doing all the indexing. So to do progress meters
 *      you need to implement <b>adsRegCallback( bEval )</b>.
 *      It lets you set a codeblock that is eval'ed every 2 seconds.
 *      A numeric value of the "percent completed" is passed to the
 *      codeblock by the ADS server.
 *
 *       <table>
 *       FUNCTION Main()
 *          ...
 *          AdsRegCallBack( {|nPercent| outputstuff(nPercent)}  )
 *          /* The above codeblock will be called approximately
 *               every 2 seconds while indexing.
 *               The codeblock can return .T. to abort.   */
 *          INDEX ON First+LAST+LABEL1+LABEL2 TAG First
 *          AdsClrCallBack()
 *       RETURN nil
 *
 *       FUNCTION outputstuff(nPercent)  /* The "callback" function */
 *          ? "output stuff", nPercent
 *       RETURN inkey() == 27
 *       /*  If press ESC, returns .T. to abort.   */
 *      </table>
 *
 *      For programmers who are already familiar with the ACE engine,
 *      Harbour's compatibility with dbfcdx means there are some differences
 *      between the RDDADS in Harbour and the parallel ACE documentation:
 *
 *      1) In ACE, skipping backwards to BOF goes to the phantom record and
 *      sets the record number to 0.  In RDDADS, the  record pointer stays at
 *      the Top record and only the BOF flag is set to True.

 *      2) In RDDADS, a filter expression can be used that may not be
 *      valid on the server (because of references to public variables or
 *      User-Defined Functions).
 *      In these cases, all data will come back from the server
 *      but will be filtered by the application running on the client.
 *      These situations lose the benefits of having a data server and should
 *      be avoided, but they will function as they would in a Clipper program.

 *      One problem with this scenario is that index key counting
 *      functions that are supposed to give an accurate count respecting
 *      the filter (e.g. dbOrderInfo(DBOI_KEYCOUNT) will return the values the
 *      Server knows about, so the counts will be inaccurate.

 *      3) When setting a relation, the expression must be one that can be
 *      evaluated by the Advantage Expression Engine.  UDFs will fail.

 *
 * $END$
 */
