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:

By default rddads is tuned for remote server and CDX indexes. To change this you may use these commands defined in ads.ch:

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

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

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:

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

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.

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.

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.

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.

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.

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.

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.