Harbour Reference Guide

ADS Overview |  | Improve this doc

Advantage Database Server RDD
Description

rddads is an RDD for the Advantage Database Server, an xBase data server by Extended Systems https://devzone.advantagedatabase.com/. The RDD was written by Alexander Kresin alex/at/belacy.belgorod.su Additional code and documentation was added by Brian Hays bhays/at/abacuslaw.com.

Your Harbour application can access a remote database server for a true client/server architecture, or it can use the "local server" for stand-alone or even small network installations.

For using this RDD you need to have all required dynamic libraries installed on your system.

For building executables don't forget to include rddads.hbc in your hbmk2 project.

You also need to include in your prg file following lines:

REQUEST ADS
rddRegister( "ADS", 1 )
rddSetDefault( "ADS" )

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 is usable 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.

Speed and Performance Issues

If you have sluggish browsers, one issue could be the scrollbar. If it's fast with the scrollbar disabled, the browse/scrolling logic may not be as optimized as it could be. Scrollbars should always use AdsGetRelKeyPos() and AdsSetRelKeyPos() instead of key counting functions.

If filtered data seems slower than expected, check these things: First, optimization is not on by default, so at the top of the app call

Set( _SET_OPTIMIZE, .T. )

or its command equivalent. rddads will use an AOF whenever dbSetFilter() is called if it can.

Second, make sure the filter is one ADS can understand. UDFs are out, as are references to public or private variables. It's also best to remove field aliases from the string. ADS cannot reference aliases for other related tables, so they're superfluous. You can call

? AdsIsExprValid( cFilter )

to check. If this returns False, neither the Local Server nor the Remote Server can process it, so optimization will never occur (but the Harbour RDD will process the filtering locally by evaluating the codeblock and testing each record). The only way to speed it up is to fix the filter so ADS understands it.

You can also use dbOrderInfo( DBOI_OPTLEVEL ) to see if the current filter is optimized or not. COMIX users can use:

FUNCTION rlOptLevel()
   RETURN dbOrderInfo( DBOI_OPTLEVEL )

This returns the Clipper/COMIX values (not ADS-defined values) because this is an RDD call, not just a wrapper to the ADS call, which uses different numbers).

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 always 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: Remote server 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 AdsRegCallback( bEval ). It lets you set a codeblock that is evaluated every 2 seconds. A numeric value of the "percent completed" is passed to the codeblock by the ADS server.
#include "inkey.ch"
PROCEDURE 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

STATIC FUNCTION outputstuff( nPercent )  /* The "callback" function */
   ? "output stuff", nPercent
   RETURN hb_keyStd( Inkey() ) == K_ESC  /* If <Esc> pressed, returns .T. to abort. */
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 may be inaccurate.
3) When setting a relation, the expression must be one that can be evaluated by the Advantage Expression Engine. UDFs will fail.
Platforms
Available on all platforms
Tag
Document

AdsBlob2File()Source code  |  | Improve this doc

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().
Status
Ready
Compliance
Harbour specific
Platforms
Available on Windows
Files
Library is rddads
Header is ads.ch
Tag
Advantage Database RDD
See also

AdsCacheOpenCursors()Source code  |  | Improve this doc

Provides caching of open cursors
Syntax
AdsCacheOpenCursors( <nOpen> ) → nRetVal
Arguments
nOpen Number of cursors to cache.
Returns
nRetVal ???
Description
AdsCacheOpenCursors() allows cursor closes to be cached in order for subsequent SELECTS to occur faster. A call to AdsCloseTable() with the cursor cache greater than zero results in the cursor appearing closed to an application, but still open on the Advantage server. AdsCacheOpenCursors() is a global setting that affects the behavior of the entire application. The default number of open cursors that are cached is 25.
Examples
? AdsCacheOpenCursors( 0 )
Status
Ready
Compliance
Harbour specific
Platforms
Available on Linux
Available on Windows
Files
Library is rddads
Header is ads.ch
Tag
Advantage Database RDD
See also

AdsCacheOpenTables()Source code  |  | Improve this doc

Provides caching of open tables
Syntax
AdsCacheOpenTables( <nOpen> ) → nRetVal
Arguments
nOpen Number of tables to cache.
Returns
nRetVal ???
Description
AdsCacheOpenTables() allows table closes to be cached in order for subsequent opens to occur faster. A call to AdsCloseTable() with the table cache greater than zero results in the table appearing closed to an application, but still open on the Advantage server. AdsCacheOpenTables() is a global setting that affects the behavior of the entire application. The default number of open tables that are cached is 0.
Examples
? AdsCacheOpenTables( 25 )
Status
Ready
Compliance
Harbour specific
Platforms
Available on Linux
Available on Windows
Files
Library is rddads
Header is ads.ch
Tag
Advantage Database RDD
See also

AdsClearAOF()Source code  |  | Improve this doc

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.
Status
Ready
Compliance
Harbour specific
Platforms
Available on Windows
Files
Library is rddads
Header is ads.ch
Tag
Advantage Database RDD
See also

AdsCloseCachedTables()Source code  |  | Improve this doc

Close all cached tables on the given connection
Syntax
AdsCloseCachedTables( [<hConnection>] ) → nRetVal
Arguments
hConnection A connection handle retrieved via AdsConnect() or AdsConnect60(). If omitted, the RDD's current connection handle is used, but this only exists if AdsConnect() or AdsConnect60() were previously called.
Returns
nRetVal ???
Description
AdsCloseCachedTables() can be used to close all cached tables on a given connection. All cached closed tables on the client will be closed, as well as all cache closed tables on the server that might have been used when executing SQL statements.
Examples
? AdsCloseCachedTables()
Status
Ready
Compliance
Harbour specific
Platforms
Available on Linux
Available on Windows
ADS 7.x and above
Files
Library is rddads
Header is ads.ch
Tag
Advantage Database RDD
See also

AdsClrCallback()Source code  |  | Improve this doc

Clears the callback set by AdsRegCallback().
Syntax
AdsClrCallback() → NIL
Returns
NIL
Description
Status
Ready
Compliance
Harbour specific
Platforms
Available on Linux
Available on Windows
Files
Library is rddads
Header is ads.ch
Tag
Advantage Database RDD
See also

AdsConnect60()Source code  |  | Improve this doc

Connect to a local/remote/internet server
Syntax
AdsConnect60( <cFilePath>, <nServertype>, [<cUserName>], [<cUserPass>], [<nOptions>] ) → lSuccess
Arguments
cFilePath Name of data dictionary to connect to. nServertype The server type to connect (LOCAL, REMOTE, AIS or all together) cUserName Optional Name of the user connecting to the server cUserPass Optional password for the user Name nOptions The optional connection options
Returns
lSuccess True if connected, otherwise False.
Description
AdsConnect60() makes the connection to an advantage database server. See ace.hlp for full details about the Advantage Database Server.
Examples
IF AdsConnect60( "harbour.add", 7 /* All types of connection */, "ADSSYS", "", )
   // Add one user
   AdsDDCreateUser( , "Luiz", "papael", "This is Luiz user" )
ENDIF
Status
Ready
Compliance
Harbour specific
Platforms
Available on Linux
Available on Windows
Files
Library is rddads
Header is ads.ch
Tag
Advantage Database RDD
See also

AdsCustomizeAOF()Source code  |  | Improve this doc

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:
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.
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.

Status
Ready
Compliance
Harbour specific
Platforms
Available on Windows
Files
Library is rddads
Header is ads.ch
Tag
Advantage Database RDD
See also

AdsDDAddTable()Source code  |  | Improve this doc

Add a new table to a Data dictionary
Syntax
AdsDDAddTable( <cTableName>, <cFileName>, <cIndexFileName> ) → lSuccess
Arguments
cTableName Name of the table inside the data dictionary cFileName Name of the ADT or dbf file name cIndexFileName Optional name of the index file
Returns
lSuccess - .T. if file was added, otherwise .F.
Description
See ace.hlp for full details about the Advantage Database Server. AdsDDAddTable() adds a new table to an ADS data dictionary. To add the table you must be connected as ADSSYS user using the AdsConnect60() function
Examples
IF AdsConnect60( "harbour.add", 7 /* All types of connection */, "ADSSYS", "", )
   // Add one user
   AdsDDCreateUser( , "Luiz", "papael", "This is luiz User" )
   // Add the tables
   AdsDDAddTable( "Table1", "table1.adt", "table1.adi" )
   // ...
ENDIF
Status
Ready
Compliance
Harbour specific
Platforms
Available on Linux
Available on Windows
Files
Library is rddads
Header is ads.ch
Tag
Advantage Database RDD
See also

AdsEvalAOF()Source code  |  | Improve this doc

Evaluate a filter expression to determine its optimization level
Syntax
AdsEvalAOF( <cFilter> ) → nOptimizationLevel
Arguments
cFilter Expression to test.
Returns
nOptimizationLevel 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.
Status
Ready
Compliance
Harbour specific
Platforms
Available on Windows
Files
Library is rddads
Header is ads.ch
Tag
Advantage Database RDD
See also

AdsFile2Blob()Source code  |  | Improve this doc

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.
Status
Ready
Compliance
Harbour specific
Platforms
Available on Windows
Files
Library is rddads
Header is ads.ch
Tag
Advantage Database RDD
See also

AdsGetAOF()Source code  |  | Improve this doc

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.
Status
Ready
Compliance
Harbour specific
Platforms
Available on Windows
Files
Library is rddads
Header is ads.ch
Tag
Advantage Database RDD
See also

AdsGetAOFNoOpt()Source code  |  | Improve this doc

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.
Status
Ready
Compliance
Harbour specific
Platforms
Available on Windows
Files
Library is rddads
Header is ads.ch
Tag
Advantage Database RDD
See also

AdsGetAOFOptLevel()Source code  |  | Improve this doc

Returns optimization level of the current AOF filter
Syntax
AdsGetAOFOptLevel() → nOptimizationLevel
Arguments
None
Returns
nOptimizationLevel 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.
Status
Ready
Compliance
Harbour specific
Platforms
Available on Windows
Files
Library is rddads
Header is ads.ch
Tag
Advantage Database RDD
See also

AdsGetConnectionType()Source code  |  | Improve this doc

Returns the type of Server used by the given connection handle.
Syntax
AdsGetConnectionType( [<hConnection>] ) → nConnectionType
Arguments
hConnection A connection handle retrieved via AdsConnect() or AdsConnect60(). If omitted, the RDD's current connection handle is used, but this only exists if AdsConnect() or AdsConnect60() were previously called.
Returns
The type of Advantage Server that the connection uses, either ADS_REMOTE_SERVER, ADS_AIS_SERVER, or ADS_LOCAL_SERVER.
Description
Advantage uses Handles to control connections to various servers. It's possible that an app may open some files via the Remote server, but others via the Local server or an Internet connection. This function identifies the type of server used by a connection handle. Note that after a table is opened, the type of connection used for that workarea can be retrieved with AdsGetTableConType(). See ace.hlp for full details.
Status
Ready
Compliance
Harbour specific
Platforms
Available on Linux
Available on Windows
Files
Library is rddads
Header is ads.ch
Tag
Advantage Database RDD
See also

AdsGetLastError()Source code  |  | Improve this doc

Returns any error code generated by the most recent ADS API call
Syntax
AdsGetLastError() → nErrorCode
Arguments
None.
Returns
The error code generated by the most recent ADS API call. Zero for success.
Description
See ace.hlp for full details about the Advantage Database Server.
Status
Ready
Compliance
Harbour specific
Platforms
Available on Linux
Available on Windows
Files
Library is rddads
Header is ads.ch
Tag
Advantage Database RDD

AdsGetRelKeyPos()Source code  |  | Improve this doc

Estimated key position of current record within the current index
Syntax
AdsGetRelKeyPos() → nKeyPos
Arguments
None. Only accesses the current index, if any.
Returns
A value between 0.0 and 1.0, inclusive.
Description

This function estimates the relative key position within the current index, respecting any scope setting. It also works with no active index to yield the relative position of the current record number. The value returned is between 0.0 and 1.0, inclusive.

This is the recommended function for positioning a scrollbar or other "coarse" position interface. See ace.hlp for full details about the Advantage Database Server.

Status
Ready
Compliance
Harbour specific
Platforms
Available on Windows
Files
Library is rddads
Header is ads.ch
Tag
Advantage Database RDD
See also

AdsGetTableConType()Source code  |  | Improve this doc

Returns the type of Server used by current workarea.
Syntax
AdsGetTableConType() → nConnectionType
Arguments
None.
Returns
The type of Advantage Server that the current workarea uses, either ADS_REMOTE_SERVER, ADS_AIS_SERVER, or ADS_LOCAL_SERVER. Returns zero if the current workarea does not have an Advantage table opened.
Description
Advantage uses Handles to control connections to various servers. It's possible that an app may open some files via the Remote server, but others via the Local server or an internet connection. This function identifies the type of server used in the current workarea.
Status
Ready
Compliance
Harbour specific
Platforms
Available on Linux
Available on Windows
Files
Library is rddads
Header is ads.ch
Tag
Advantage Database RDD
See also

AdsIsExprValid()Source code  |  | Improve this doc

Determine if the ADS server can parse an expression
Syntax
AdsIsExprValid( <cExp> ) → lSuccess
Arguments
cExp Any hopefully valid expression; often a filter string
Returns
.T. if the expression is understood by ADS.
Description

ADS has its own limitations for the logical or string expressions used in indexes, filters, scopes, etc. Unlike internal RDDs like DBFNTX, the server is independent of the applications code, so it cannot understand references to PUBLIC variables or User-Defined Functions (UDFs). (See ace.hlp under Advantage Expression Engine for a list of functions allowed by ADS.) Call AdsIsExprValid() to determine if the server can process the expression.

For illustration, consider filter expressions. Since Harbour attempts to be as compatible with Clipper as possible, you can set a filter that ADS does not understand, but the filtering will be done by the RDD layer itself and ADS will be unaware of the filter setting. This means more data will be sent "across the wire" from the server to the client, and the client (in rddads) will be doing the processing. Since the value of a database server is to have more processing done by the server itself to reduce network traffic, it is better to only use filter expressions ADS can understand.

Status
Ready
Compliance
Harbour specific
Platforms
Available on Linux
Available on Windows
Files
Library is rddads
Header is ads.ch
Tag
Advantage Database RDD

AdsIsIndexed()Source code  |  | Improve this doc

Fast determination for if current workarea has a selected index
Syntax
AdsIsIndexed() → lActiveIndex
Returns
lActiveIndex
Description
Equivalent to Empty( ordSetFocus() ), but faster.
Status
Ready
Compliance
Harbour specific
Platforms
Available on Linux
Available on Windows
File
Library is rddads
Tag
Advantage Database RDD

AdsIsRecordInAOF()Source code  |  | Improve this doc

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.
Status
Ready
Compliance
Harbour specific
Platforms
Available on Windows
Files
Library is rddads
Header is ads.ch
Tag
Advantage Database RDD
See also

AdsKeyCount()Source code  |  | Improve this doc

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:
   ADS_RESPECTFILTERS   Respect filters and scopes
   ADS_IGNOREFILTERS    Ignore filters and scopes
   ADS_RESPECTSCOPES    Respect scopes only
Returns
nKeyCount The number of keys within the current index.
Description
See ace.hlp for full details about the Advantage Database Server.
Status
Ready
Compliance
Harbour specific
Platforms
Available on Windows
Files
Library is rddads
Header is ads.ch
Tag
Advantage Database RDD
See also

AdsKeyNo()Source code  |  | Improve this doc

Get the logical key number of the current record in the given index
Syntax
AdsKeyNo( [<xTag>], <cIgnoredIndexFile>, [<nFilterOption>] ) → nKeyNo
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 "ordKeyNo" 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:
   ADS_RESPECTFILTERS   Respect filters and scopes
   ADS_IGNOREFILTERS    Ignore filters and scopes
   ADS_RESPECTSCOPES    Respect scopes only
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. Wrapper for AdsGetKeyNum(). 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().
Status
Ready
Compliance
Harbour specific
Platforms
Available on Windows
Files
Library is rddads
Header is ads.ch
Tag
Advantage Database RDD
See also

AdsLocking()Source code  |  | Improve this doc

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.

Status
Ready
Compliance
Harbour specific
Platforms
Available on Windows
Files
Library is rddads
Header is ads.ch
Tag
Advantage Database RDD
See also

AdsRefreshAOF()Source code  |  | Improve this doc

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.
Status
Ready
Compliance
Harbour specific
Platforms
Available on Windows
Files
Library is rddads
Header is ads.ch
Tag
Advantage Database RDD
See also

AdsRegCallback()Source code  |  | Improve this doc

For Progress displays: Sets a codeblock to be called during indexing
Syntax
AdsRegCallback( <bEval> )  → NIL
Arguments
bEval The codeblock that is eval'ed every 2 seconds during indexing. A numeric value of the "percent completed" is passed to the codeblock by the ADS server. The codeblock should return a logical value: .T. to abort or .F. to not stop indexing.
Returns
NIL
Description
See ace.hlp for full details on AdsRegisterProgressCallback(). 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 this.
Examples
#include "inkey.ch"

PROCEDURE 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

STATIC FUNCTION outputstuff( nPercent )  /* The "callback" function */
   ? "output stuff", nPercent
   RETURN hb_keyStd( Inkey() ) == K_ESC  /* If <Esc> pressed, returns .T. to abort. */
Status
Ready
Compliance
Harbour specific
Platforms
Available on Linux
Available on Windows
Files
Library is rddads
Header is ads.ch
Tag
Advantage Database RDD
See also

AdsRightsCheck()Source code  |  | Improve this doc

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.

Status
Ready
Compliance
Harbour specific
Platforms
Available on Windows
Files
Library is rddads
Header is ads.ch
Tag
Advantage Database RDD
See also

AdsSetAOF()Source code  |  | Improve this doc

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.
Status
Ready
Compliance
Harbour specific
Platforms
Available on Windows
Files
Library is rddads
Header is ads.ch
Tag
Advantage Database RDD
See also

AdsSetCharType()Source code  |  | Improve this doc

Sets the type of character data expected when opening tables.
Syntax
AdsSetCharType( <nCharType>, [lOEM] ) → nPriorSetting
Arguments
nCharType Type of character data in the table. From ADS docs: Options are ADS_ANSI and ADS_OEM. This indicates the type of character data to be stored in the table. For compatibility with DOS-based CA-Cl*pper applications, ADS_OEM should be specified. When usTableType is ADS_ADT, this parameter is ignored and ANSI is always used. lOEM This parameter used for console mode applications, when character data stored in OEM charset. If lOEM is passed as .T., rddads doesn't convert character data into ANSI charset.
Returns
nPriorSetting
Description
See ace.hlp for full details about the Advantage Database Server. This sets the usCharType parameter used when ADS opens a table.
Status
Ready
Compliance
Harbour specific
Platforms
Available on Linux
Available on Windows
Files
Library is rddads
Header is ads.ch
Tag
Advantage Database RDD
See also
AdsLocking(), AdsRightsCheck(), AdsSetFileType()

AdsSetDefault() * |  | Improve this doc

Get/Set function for ADS's DEFAULT setting.
Syntax
AdsSetDefault( [<cPath>] ) → cPriorSetting
Arguments
cPath Sets new value if passed.
Returns
cPriorSetting
Description
This function is NOT recommended! It allows direct access to the ADS internal equivalent to SET DEFAULT TO. But this setting is automatically maintained by Harbour's Set() function and the SET DEFAULT TO command, so normal programming will not use this. It exists primarily for testing purposes.
Status
Ready
Compliance
Harbour specific
Platforms
Available on Linux
Available on Windows
Files
Library is rddads
Header is ads.ch
Tag
Advantage Database RDD

AdsSetDeleted() * |  | Improve this doc

Get/Set function for ADS's AdsShowDeleted() setting.
Syntax
AdsSetDeleted( [<lOnOff>] ) → lPriorSetting
Arguments
lOnOff Sets new value if passed. The value is parallel to Harbour usage, so pass .F. to see deleted records or .T. to hide them. (This is inverted from ADS's AdsShowDeleted() syntax.)
Returns
lPriorSetting
Description
This function is NOT recommended! It allows direct access to the ADS internal equivalent to SET DELETED. But this setting is automatically maintained by Harbour's Set() function and the SET DELETED ON/OFF command, so normal programming will not use this. It exists primarily for testing purposes.
Status
Ready
Compliance
Harbour specific
Platforms
Available on Linux
Available on Windows
Files
Library is rddads
Header is ads.ch
Tag
Advantage Database RDD

AdsSetExact() * |  | Improve this doc

Get/Set function for ADS's AdsSetExact() setting.
Syntax
AdsSetExact( [<lOnOff>] ) → lPriorSetting
Arguments
lOnOff Sets new value if passed.
Returns
lPriorSetting
Description
This function is NOT recommended! It allows direct access to the ADS internal equivalent to SET EXACT. But this setting is automatically maintained by Harbour's Set() function and the SET EXACT ON/OFF command, so normal programming will not use this. It exists primarily for testing purposes.
Status
Ready
Compliance
Harbour specific
Platforms
Available on Linux
Available on Windows
Files
Library is rddads
Header is ads.ch
Tag
Advantage Database RDD

AdsSetRelKeyPos()Source code  |  | Improve this doc

Go to the given estimated key position within the current index
Syntax
ADSSetSelKeyPos( <nPercent> ) → nError
Arguments
nPercent Relative key position between 0.0 and 1.0, inclusive.
Returns
The return/error value of the ADS API call.
Description

This function moves the record pointer to the estimated relative position within the current index order, respecting any scope setting. It also works with no active index to go to the relative position of the current record number.

This is the recommended function for re-positioning in reaction to a dragged scrollbar thumb or other "coarse" navigation interface. See ace.hlp for full details about the Advantage Database Server.

Status
Ready
Compliance
Harbour specific
Platforms
Available on Windows
Files
Library is rddads
Header is ads.ch
Tag
Advantage Database RDD
See also

AdsSetSearchPath() * |  | Improve this doc

Get/Set function for ADS's AdsSetSearchPath() setting.
Syntax
AdsSetSearchPath( [<cPath>] ) → cPriorSetting
Arguments
cPath Sets new value if passed.
Returns
cPriorSetting
Description
This function is NOT recommended! It allows direct access to the ADS AdsSetSearchPath() setting. But this setting is automatically maintained by Harbour's Set() function and the SET PATH command, so normal programming will not use this. It exists primarily for testing purposes.
Status
Ready
Compliance
Harbour specific
Platforms
Available on Linux
Available on Windows
Files
Library is rddads
Header is ads.ch
Tag
Advantage Database RDD

AdsTestRecLocks()Source code  |  | Improve this doc

Turn On or Off a "debug mode" for trapping missed record locks.
Syntax
AdsTestRecLocks( <lOnOff> ) → lPriorSetting
Arguments
lOnOff New setting. Default is FALSE.
Returns
Prior Setting.
Description

AdsTestRecLocks() is a Get/Set function for a "record lock checking" mode. ADS has Implicit Record locking that can mask programming errors. Implicit locking can occur the first time a value is written to a field with no lock in effect. The lock can potentially remain in effect indefinitely if the record pointer is not moved, causing bugs later in program execution that are hard to find. In Harbour internal RDDs, a runtime error occurs if an attempt is made to write to a shared file without a proper lock.

AdsTestRecLocks( .T. ) will turn on a debugging mode to mimic this behavior and throw an error instead of allowing an implicit lock. Each time a field is set, we see if the file is open exclusively or locked, and whether the record has been explicitly locked already. If not, we throw an error so the developer can catch the missing lock condition. For performance reasons, Release code should leave this off. Although the call to AdsIsRecordLocked() is documented as a client call, not a server request, and should be fast, it will be called for each field as it is assigned a value.

See ace.hlp for full details about the Advantage Database Server.

Status
Ready
Compliance
Harbour specific
Platforms
Available on Linux
Available on Windows
Files
Library is rddads
Header is ads.ch
Tag
Advantage Database RDD