/*
 * $Id$
 */

/*
 * The following are Copyright of the individual authors.
 * www - http://www.harbour-project.org
 *
 * Copyright 2000 Extended Systems, Inc.
 *    Documentation for Advantage Database Server and Local Server
 *
 * Copyright 2000 Brian Hays <bhays@abacuslaw.com>
 *    Documentation for Harbour-specific features
 *
 * See doc/license.txt for licensing terms.
 *
 */

/*  $DOC$
 *  $FUNCNAME$
 *      ADSBlob2File()
 *  $CATEGORY$
 *      Advantage Database RDD
 *  $ONELINER$
 *      Write a Binary (memo) field's contents to a file
 *  $SYNTAX$
 *      ADSBlob2File(cFileName, cFieldName) --> lSuccess
 *  $ARGUMENTS$
 *      <cFileName>    File to create. If it already exists, it will be
 *      overwritten on success and destroyed on error.
 *
 *      <cFieldName>   Field in the current workarea that contains binary data.
 *
 *  $RETURNS$
 *      <lSuccess>  True if the file is successfully written.
 *  $DESCRIPTION$
 *      See ACE.HLP for full details about the Advantage Database Server.
 *      ADSBlob2File() is a wrapper for AdsBinaryToFile.
 *  $EXAMPLES$
 *  $TESTS$
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      Harbour extension
 *  $PLATFORMS$
 *      Windows 32-bit only
 *  $FILES$
 *      Library is RddAds
 *      Header is ads.ch
 *  $SEEALSO$
 *      ADSFile2Blob()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      ADSFile2Blob()
 *  $CATEGORY$
 *      Advantage Database RDD
 *  $ONELINER$
 *      Save a Binary file to a field
 *  $SYNTAX$
 *      ADSFile2Blob(cFileName, cFieldName, <nBinaryType>) --> lSuccess
 *  $ARGUMENTS$
 *      <cFileName>    File to read. Can be in UNC format. A common example is an image file.
 *
 *      <cFieldName>   Field in the current workarea to contain the binary data.
 *
 *      <nBinaryType>  Either ADS_BINARY (the default) or ADS_IMAGE.
 *      This parameter is for fields in DBF files.
 *      ADT tables cannot store binary and image data in standard character
 *      memo fields (they have specific field types for that).
 *  $RETURNS$
 *      <lSuccess>   True if the file is successfully written.
 *  $DESCRIPTION$
 *      See ACE.HLP for full details about the Advantage Database Server.
 *      ADSFile2Blob() is a wrapper for AdsFileToBinary.
 *      Use of this function is illegal in an ADS transaction.
 *  $EXAMPLES$
 *  $TESTS$
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      Harbour extension
 *  $PLATFORMS$
 *      Windows 32-bit only
 *  $FILES$
 *      Library is RddAds
 *      Header is ads.ch
 *  $SEEALSO$
 *      ADSBlob2File()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      ADSClearAOF()
 *  $CATEGORY$
 *      Advantage Database RDD
 *  $ONELINER$
 *      Clears an Advantage Optimized Filter in the current workarea.
 *  $SYNTAX$
 *      ADSClearAOF()
 *  $ARGUMENTS$
 *      None
 *  $RETURNS$
 *      NIL
 *  $DESCRIPTION$
 *      See ACE.HLP for full details about the Advantage Database Server.
 *  $EXAMPLES$
 *  $TESTS$
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      Harbour extension
 *  $PLATFORMS$
 *      Windows 32-bit
 *  $FILES$
 *      Library is RddAds
 *      Header is ads.ch
 *  $SEEALSO$
 *      ADSCustomizeAOF(),ADSEvalAOF(),ADSGetAOF(),ADSGetAOFoptLevel(),ADSIsRecordInAOF(),ADSRefreshAOF()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      ADSCustomizeAOF()
 *  $CATEGORY$
 *      Advantage Database RDD
 *  $ONELINER$
 *      Add or remove records from an existing AOF
 *  $SYNTAX$
 *      ADSCustomizeAOF( [<nRecno | aRecNos>] [, <nType>] ) --> nSuccess
 *  $ARGUMENTS$
 *      <nRecno | aRecNos> Can be either a single record number or an array of
 *      record numbers to add or delete from the AOF. If omitted, defaults to
 *      the current record.
 *
 *      <nType>   The type of operation:

 *      <table>
 *      ADS_AOF_ADD_RECORD      Add the record to the AOF (set the bit). This is the default operation.
 *      ADS_AOF_REMOVE_RECORD   Remove the record from the AOF (clear the bit).
 *      ADS_AOF_TOGGLE_RECORD   Switch the record into or out of the AOF.
 *  </table>
 *  $RETURNS$
 *      <nError>  ADS error code, or 0 for success.
 *  $DESCRIPTION$
 *      An Advantage Optimized Filter (AOF) consists of a bitmap of the records in
 *      the database. If bit 5 is on, record 5 is considered a visible record.
 *      If bit 5 is off, record 5 is not visible. It does not "pass the test".
 *      Initially, the bits are set by the Server according to a filter expression
 *      from SET FILTER TO or adsSetAOF(). But by using ADSCustomizeAOF() you can
 *      add or remove records at will from the visible set.  This is useful for
 *      tagging records or for refining a result set after the data has been retrieved
 *      from the server.

 *      The maximum number of records that can be customized in a single call is
 *      16,383, so <aRecNos> must not be longer than this.

 *      Calls to AdsCustomizeAOF must be made after an application has created a
 *      filter with a call to AdsSetAOF. To create a completely empty record set
 *      (to which records can be added with calls to AdsCustomizeAOF), use ".F." as
 *      the filter expression given to AdsSetAOF. To create a completely full
 *      record set (from which records can be removed), use ".T." as the filter
 *      expression.

 *      WARNING: Always start with a FULLY optimized AOF!
 *      If an application must use a filter expression that is not fully optimized
 *      as the starting point for customization, the ADS_RESOLVE_IMMEDIATE option
 *      should be used with the call to AdsSetAOF. Otherwise, the dynamic filter
 *      resolution that occurs on the server will automatically remove records that
 *      have been added through the AdsCustomizeAOF calls. The
 *      filter expressions ".T." and ".F." both result in fully optimized AOFs
 *      regardless of available indexes.

 *      See ACE.HLP for full details about the Advantage Database Server.
 *  $EXAMPLES$
 *  $TESTS$
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      Harbour extension
 *  $PLATFORMS$
 *      Windows 32-bit
 *  $FILES$
 *      Library is RddAds
 *      Header is ads.ch
 *  $SEEALSO$
 *      ADSClearAOF(),ADSEvalAOF(),ADSGetAOF(),ADSGetAOFoptLevel(),ADSIsRecordInAOF(),ADSRefreshAOF()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      ADSEvalAOF()
 *  $CATEGORY$
 *      Advantage Database RDD
 *  $ONELINER$
 *      Evaluate a filter expression to determine its optimization level
 *  $SYNTAX$
 *      ADSEvalAOF(<cFilter>) --> nOptimizationLevel
 *  $ARGUMENTS$
 *      <cFilter>       Expression to test.
 *  $RETURNS$
 *      <nOptimizationLevel>      </par>
 *      Values are defined in ads.ch:
 *      ADS_OPTIMIZED_FULL, ADS_OPTIMIZED_PART, ADS_OPTIMIZED_NONE.
 *      IMPORTANT NOTE: These values are NOT the same as those returned
 *      by dbOrderInfo().
 *  $DESCRIPTION$
 *      See ACE.HLP for full details about the Advantage Database Server.
 *  $EXAMPLES$
 *  $TESTS$
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      Harbour extension
 *  $PLATFORMS$
 *      Windows 32-bit
 *  $FILES$
 *      Library is RddAds
 *      Header is ads.ch
 *  $SEEALSO$
 *      ADSClearAOF(),ADSGetAOF(),ADSGetAOFoptLevel(),ADSIsRecordInAOF(),ADSRefreshAOF()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      ADSGetAOFoptLevel()
 *  $CATEGORY$
 *      Advantage Database RDD
 *  $ONELINER$
 *      Returns optimization level of the current AOF filter
 *  $SYNTAX$
 *      ADSGetAOFoptLevel() --> nOptimizationLevel
 *  $ARGUMENTS$
 *       None
 *  $RETURNS$
 *      <nOptimizationLevel>      </par>
 *      Values are defined in ads.ch:
 *      ADS_OPTIMIZED_FULL, ADS_OPTIMIZED_PART, ADS_OPTIMIZED_NONE.
 *  $DESCRIPTION$
 *      See ACE.HLP for full details about the Advantage Database Server.
 *  $EXAMPLES$
 *  $TESTS$
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      Harbour extension
 *  $PLATFORMS$
 *      Windows 32-bit
 *  $FILES$
 *      Library is RddAds
 *      Header is ads.ch
 *  $SEEALSO$
 *      ADSClearAOF(),ADSGetAOF(),ADSIsRecordInAOF(),ADSRefreshAOF()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      ADSGetAOF()
 *  $CATEGORY$
 *      Advantage Database RDD
 *  $ONELINER$
 *      Retrieve the filter expression used in the call to AdsSetAOF
 *  $SYNTAX$
 *      ADSGetAOF() --> cFilter
 *  $ARGUMENTS$
 *      None
 *  $RETURNS$
 *      <cFilter>  The filter expression used in the call to AdsSetAOF.
 *  $DESCRIPTION$
 *      See ACE.HLP for full details about the Advantage Database Server.
 *  $EXAMPLES$
 *  $TESTS$
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      Harbour extension
 *  $PLATFORMS$
 *      Windows 32-bit
 *  $FILES$
 *      Library is RddAds
 *      Header is ads.ch
 *  $SEEALSO$
 *      ADSClearAOF(),ADSGetAOFoptLevel(),ADSIsRecordInAOF(),ADSRefreshAOF()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      ADSGetAOFnoOpt()
 *  $CATEGORY$
 *      Advantage Database RDD
 *  $ONELINER$
 *      Return the non-optimized portion of the current filter expression
 *  $SYNTAX$
 *      ADSGetAOFnoOpt() --> cFilterFragment
 *  $ARGUMENTS$
 *    None
 *  $RETURNS$
 *      <cFilterFragment>  If an AOF filter expression is not fully optimizable,
 *      the non-optimizable part of the expression can be retrieved with this function.
 *  $DESCRIPTION$
 *      See ACE.HLP for full details about the Advantage Database Server.
 *  $EXAMPLES$
 *  $TESTS$
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      Harbour extension
 *  $PLATFORMS$
 *      Windows 32-bit
 *  $FILES$
 *      Library is RddAds
 *      Header is ads.ch
 *  $SEEALSO$
 *      ADSClearAOF(),ADSIsRecordInAOF(),ADSRefreshAOF()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      ADSRefreshAOF()
 *  $CATEGORY$
 *      Advantage Database RDD
 *  $ONELINER$
 *      Update the filter snapshot
 *  $SYNTAX$
 *      ADSRefreshAOF()
 *  $ARGUMENTS$
 *      None
 *  $RETURNS$
 *      NIL
 *  $DESCRIPTION$
 *      See ACE.HLP for full details about the Advantage Database Server.
 *      If record updates occur after an AOF is set, the updated records may
 *      or may not be valid records for the filter. ADSRefreshAOF()
 *      re-evaluates the data to include or exclude changed records.
 *  $EXAMPLES$
 *  $TESTS$
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      Harbour extension
 *  $PLATFORMS$
 *      Windows 32-bit
 *  $FILES$
 *      Library is RddAds
 *      Header is ads.ch
 *  $SEEALSO$
 *      ADSClearAOF(),ADSIsRecordInAOF(),ADSSetAOF()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      ADSSetAOF()
 *  $CATEGORY$
 *      Advantage Database RDD
 *  $ONELINER$
 *      Create an Advantage Optimized Filter
 *  $SYNTAX$
 *      ADSSetAOF( <cFilter> [, <nResolveOption>] ) --> lSuccess
 *  $ARGUMENTS$
 *       <cFilter>         Filter expression to set.

 *       <nResolveOption>  Option to indicate how the filter should be resolved
 *       in the event that the expression cannot be fully optimized.
 *       Options are defined in ads.ch:
 *       ADS_RESOLVE_IMMEDIATE, ADS_RESOLVE_DYNAMIC.
 *  $RETURNS$
 *      <lSuccess>   True if AOF is created.
 *  $DESCRIPTION$
 *      See ACE.HLP for full details about the Advantage Database Server.
 *  $EXAMPLES$
 *  $TESTS$
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      Harbour extension
 *  $PLATFORMS$
 *      Windows 32-bit
 *  $FILES$
 *      Library is RddAds
 *      Header is ads.ch
 *  $SEEALSO$
 *      ADSClearAOF(),ADSIsRecordInAOF(),ADSRefreshAOF()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      ADSIsRecordInAOF()
 *  $CATEGORY$
 *      Advantage Database RDD
 *  $ONELINER$
 *      Determine if a record is in the current AOF
 *  $SYNTAX$
 *      ADSIsRecordInAOF( [<nRecNo>] ) --> lSatisfiesFilter
 *  $ARGUMENTS$
 *       <nRecNo>         Record number to test. Default is current record.
 *  $RETURNS$
 *      True if the record satisfies the filter criteria.
 *  $DESCRIPTION$
 *      See ACE.HLP for full details about the Advantage Database Server.
 *  $EXAMPLES$
 *  $TESTS$
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      Harbour extension
 *  $PLATFORMS$
 *      Windows 32-bit
 *  $FILES$
 *      Library is RddAds
 *      Header is ads.ch
 *  $SEEALSO$
 *      ADSClearAOF(),ADSRefreshAOF()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      ADSGetRelKeyPos()
 *  $CATEGORY$
 *      Advantage Database RDD
 *  $ONELINER$
 *      Estimated key position of current record within the specified index
 *  $SYNTAX$
 *      ADSGetRelKeyPos([<xTag>]) --> nKeyPos
 *  $ARGUMENTS$
 *      <xTag>  Index to use. Default is current index.
 *  $RETURNS$
 *      The relative key position within the current index.
 *      This function estimates the position of the current key in the indicated
 *      index order. The value returned is between 0.0 and 1.0, inclusive.
 *      If there are scopes set on the index order, the position returned
 *      is relative to the visible records.
 *  $DESCRIPTION$
 *      See ACE.HLP for full details about the Advantage Database Server.
 *  $EXAMPLES$
 *  $TESTS$
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      Harbour extension
 *  $PLATFORMS$
 *      Windows 32-bit
 *  $FILES$
 *      Library is RddAds
 *      Header is ads.ch
 *  $SEEALSO$
 *      ADSKeyNo(),ADSKeyCount()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      ADSKeyCount()
 *  $CATEGORY$
 *      Advantage Database RDD
 *  $ONELINER$
 *      Retrieve the number of keys in a specified index
 *  $SYNTAX$
 *      ADSKeyCount([<xTag>], <cIgnoredIndexFile>, [<nFilterOption>]) --> nKeyCount
 *  $ARGUMENTS$
 *      <xTag>     Numeric order number OR index tag name. Default is current index.
 *
 *      <cIgnoredIndexFile>   This parameter is not processed. In other Harbour RDDs,
 *      the second parameter to "ordKeyCount" takes a second argument to identify
 *      a particular Index File in cases where two files are open that contain
 *      orders with the same name. The ADS driver does not support this and
 *      will select the first order with the requested name. To stay consistent
 *      with other RDDs, therefore(),the second parameter is reserved and the
 *      <nFilterOption> is passed as a third parameter.
 *
 *      <nFilterOption> Indicates if filters and/or scopes are to be respected if set.

 *      Options are defined in ads.ch:
 *
        <table>
 *         ADS_RESPECTFILTERS   Respect filters and scopes
 *         ADS_IGNOREFILTERS    Ignore filters and scopes
 *         ADS_RESPECTSCOPES    Respect scopes only
        </table>
 *  $RETURNS$
 *      <nKeyCount>  The number of keys within the current index.
 *  $DESCRIPTION$
 *      See ACE.HLP for full details about the Advantage Database Server.
 *  $EXAMPLES$
 *  $TESTS$
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      Harbour extension
 *  $PLATFORMS$
 *      Windows 32-bit
 *  $FILES$
 *      Library is RddAds
 *      Header is ads.ch
 *  $SEEALSO$
 *      ADSKeyNo(),ADSGetRelKeyPos()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      ADSKeyNo()
 *  $CATEGORY$
 *      Advantage Database RDD
 *  $ONELINER$
 *      Get the logical key number of the current record in the given index
 *  $SYNTAX$
 *      ADSKeyNo([<xTag>], [<nFilterOption>]) --> nKeyNo
 *  $ARGUMENTS$
 *      <xTag>          Numeric order number OR index tag name. Default is current index.
 *
 *      <nFilterOption> Indicates if filters and/or scopes are to be respected if set.
 *
 *      <table>
 *      Options are defined in ads.ch:
 *         ADS_RESPECTFILTERS   Respect filters and scopes
 *         ADS_IGNOREFILTERS    Ignore filters and scopes
 *         ADS_RESPECTSCOPES    Respect scopes only
        </table>
 *  $RETURNS$
 *      <nKeyNo>   The logical key number of the current record in the given index.
 *  $DESCRIPTION$
 *      See ACE.HLP for full details about the Advantage Database Server.</par>
 *      Wrapper for AdsGetKeyNum. </par>
        This function may be slow on a large database with
        ADS_RESPECTFILTERS set because it walks through the keys to get the
        current position.  Compare to ADSGetRelKeyPos().
 *  $EXAMPLES$
 *  $TESTS$
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      Harbour extension
 *  $PLATFORMS$
 *      Windows 32-bit
 *  $FILES$
 *      Library is RddAds
 *      Header is ads.ch
 *  $SEEALSO$
 *      ADSKeyCount(),ADSGetRelKeyPos()
 *  $END$
 */



/*  $DOC$
 *  $FUNCNAME$
 *      ADSLocking()
 *  $CATEGORY$
 *      Advantage Database RDD
 *  $ONELINER$
 *      Turns on/off the Advantage proprietary locking mode
 *  $SYNTAX$
 *      ADSLocking( <lMode> ) --> lPriorSetting
 *  $ARGUMENTS$
 *      <lMode>    .T. to use the Advantage proprietary locking mode
 *      (this is the default setting if a remote server is used)
 *      or pass .F. to use "compatibility" locking.
 *
 *  $RETURNS$
 *      <lPriorSetting>   .T. if prior setting was for the proprietary mode.
 *  $DESCRIPTION$
 *      See ACE.HLP for full details about the Advantage Database Server.
 *      The Advantage Database Server has a fast Proprietary locking mode that
 *      is more efficient than traditional network locking. It is only available
 *      when using the remote server (not the local server).

 *      If a file is opened in the proprietary mode, other applications cannot
 *      open it in a "write" mode. So if non-Advantage applications need
 *      concurrent access to the data files, use the Compatibility locking mode
 *      by calling  ADSLocking( .F. ).

 *      ADSLocking() is a Get/Set function for the locking mode. It affects
 *      files at the time they are opened. So when a data
 *      file is opened, the current setting is used for that file until it is
 *      closed. Different files can have different locking modes by changing
 *      the setting before opening a second file.
 *  $EXAMPLES$
 *  $TESTS$
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      Harbour extension
 *  $PLATFORMS$
 *      Windows 32-bit
 *  $FILES$
 *      Library is RddAds
 *      Header is ads.ch
 *  $SEEALSO$
 *      ADSRightsCheck()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      ADSRightsCheck()
 *  $CATEGORY$
 *      Advantage Database RDD
 *  $ONELINER$
 *      Sets the "rights checking" setting for opening files
 *  $SYNTAX$
 *      ADSRightsCheck( <lMode> ) --> lPriorSetting
 *  $ARGUMENTS$
 *      <lMode>    .T. to check rights upon opening data files (the default),
 *      or .F. to ignore rights
 *
 *  $RETURNS$
 *      <lPriorSetting>
 *  $DESCRIPTION$
 *      See ACE.HLP for full details about the Advantage Database Server.
 *      ADSRightsCheck() is a Get/Set function for the "rights checking" mode.
 *      If the setting is .T. when a file is opened, then the Advantage
 *      Database Server will use the rights of the connected user when
 *      opening the file. If the user does not have rights to the
 *      directory or server, then the open call will fail.

 *      If the setting is .F., then the ADS will
 *      ignore the connected user's rights and open the file
 *      regardless. This lets you allow only
 *      Advantage-based applications to access specific data.
 *  $EXAMPLES$
 *  $TESTS$
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      Harbour extension
 *  $PLATFORMS$
 *      Windows 32-bit
 *  $FILES$
 *      Library is RddAds
 *      Header is ads.ch
 *  $SEEALSO$
 *      ADSLocking()
 *  $END$
 */


/* TO-DO:

ADSSetCharType
ADSSetDefault
ADSSetDeleted
ADSSetFileType
ADSSetServerType

ADSDecryptRecord
ADSDecryptTable
ADSDisableEncryption
ADSEnableEncryption
ADSEncryptRecord
ADSEncryptTable
ADSIsEncryptionEnabled
ADSIsRecordEncrypted
ADSIsTableEncrypted
*/

