Building rddads.lib:

Given a choice of SQL engine to use when building apps from any xbase language, I just can’t think why would anyone choose any other than Sybase’s ADS. I base my assertion on the premise that the apps being built are commercial-multi-user-complex-real-life systems to be used by many users concurrently and on the fact that ADS is the only SQL that is also ISAM.

As xbase programmers we are used to working with indexed dbf tables where a file pointer moves to a specific location granting access to a specific record. Dbf tables and indexes are so simple to manage, we never think on the need to have a DBA on-site or any sort of special maintenance rituals to keep our database healthy. The beauty of ADS is that you get to keep all that while adding SQL to the equation. Certain data operations are better performed with SQL while others are better suited for ISAM. With ADS you are not restricted to just SQL or just ISAM. You have both.

There is, however, one caveat; albeit ADS’s documentation is extensive and very complete, there is close to zero documentation aimed at the xbase programmer. I think the one question I find most often on the forums is how to build Harbour’s replaceable database driver (rddads.lib) for a particular version of ADS. Some times I wonder how many people have been turned off after not being able to even start testing the free ADS local server version. So, let’s start by showing how to build rddads.lib for (x)Harbour for a particular ADS version.

What is ace32, why do I need it and why does it change:

Advantage Client Engine (Ace32.dll) is Sybase’ API to ADS. We will be calling many of these external functions from our Harbour apps. In order for the Linker to resolve references to external functions, like the ones in ace32.dll, we must provide a .lib file format of the .dll file that contains the actual functions as part of our link script. ACE32 is distributed by Sybase and it can be found after installing Data Architect in “c:\program files\Advantage 10.0\ARC\ace32.dll” or after installing the Advantage SDK available for download at http://devzone.advantagedatabase.com.

Each C compiler has its own utility to create a .lib from a .dll. With Borland C++, the most widely used C compiler in the community, that utility is called "implib.exe" and it can be found on \bin directory of the BCC compiler. To create the actual .lib file implib is executed like this: Implib ace32.lib ace32.dll. The command will generate ace32.lib from ace32.dll. Once the .lib file has been created, it must be linked to the application that makes use of the dynamic linked library functions. With the commercial version of xharbour (xhb builder), you need to link ads.lib which is provided in the /lib directory. With the non-commercial version, link ace32.lib as well as rddads.lib which is located in /contrib/rdd_ads.

What you will need to build your own rddads.lib and why:

From time to time Sybase will release a new update of ADS that requires newer clients. While older clients are always compatible with newer servers the opposite is not true. It should be noted that it is not always desirable to stay with old clients. Newer servers introduce new functionality and services that are only available with the corresponding new client. Thus, it may be necessary to build different versions of the ADS libs (rddads.lib and ace32.lib) to be linked to the Harbour application depending on the ADS server and client being targeted. To build rddads.lib the developer needs to acquire ace.h for the ADS version for which the .lib is to be created i.e. (ADS version 7, 8, 9...). This file can be found on the Advantage SDK which is available for download from the advantage client engine link found in http://devzone.advantagedatabase.com or in the \rdd_ads directory inside \xharbour\contrib directory. Please note that the SDK will also contain ace32.dll which we need to create ace32.lib. Ace.h is the only version specific file to be used when building rddads.lib. It is crucial that the correct ace.h is used and it should be the one that corresponds to the advantage .dll files and ADS version being targeted.

Building rddads.lib:

More than once the Harbour project developers have changed the method necessary to build an ADS version specific rddads.lib. At this point I take for granted that the reader is using more recent versions of the compiler; e.i. 2009 or newer. I will reserve for a later post how to build rddads.lib for older versions of the compiler.

Starting with version 1.2 of the xharbour compiler, the Harbour project developers have put a new system in place to automatically get everything set up in order to build \xharbour\lib\rddads.lib as well as ads32.lib for any specific version and it works quite well. Let me just say that it represents a huge improvement over previous methods. It requires acesdk directory for the specific ADS version. Acesdk is installed from aceapi.exe which can be downloaded from the advantage devzone as noted previously.

Once acdsdk has been installed, set the environmental variable HB_DIR_ADS to the directory that contains the SDK files:

C:\xharbour\contrib\rddasd>set HB_DIR_ADS=c:\ads8\acesdk

Now execute the batch file for the C compiler being used with your applications and the newly created rddads.lib and ace32.lib necessary to be linked to your Harbour apps will be found in c:\xharbour\lib. Note that the batch files used to build the lib file are written for specific compilers (make_b32.bat for Borland c++, make_vc.bat for MS Visual c). You might have to edit the makefile (makefile.bc for Borland c++ or makefile.vc for MS Visual c) to make sure the paths are correct.

Distributing an Advantage Enabled Application

Include the files below with your distribution of a Windows Harbour Advantage client application:

ace32.dll: Advantage Client Engine DLL. This .dll contains the core Advantage Windows client functionality.

adsloc32.dll: Advantage Local Server DLL. This .dll contains the core local server functionality. This file is not necessary if using the Advantage Database Server only.

adslocal.cfg: Advantage Local Server configuration file. This file is only necessary if using the Advantage Local Server and you wish to use Local Server settings other than the default.

ansi.chr: This file is needed for ANSI language support with the Advantage Local Server. This file may only be necessary if using non-English ANSI character sets with the Advantage Local Server.

axcws32.dll: Advantage remote communication library used when accessing data via the Advantage Database Server -Remote as well as Internet connections. This file is not necessary if using the Advantage Local Server only.

extend.chr: This file is needed for international OEM language support with the Advantage Local Server. This file is only necessary if using non-USA OEM character sets with the Advantage Local Server.

Remote, Internet, Local Advantage Connections

If you are wondering what is the difference between Remote, Internet, and Local servers, read this section. I borrow some of it from the ADS help files. The help files are available from ARC or from http://devzone.advantagedatabase.com (and it is quite good).

With Advantage there are three different ways to connect to data:

1. . Advantage Local Server (ALS).
2. . Advantage Database Server in a two tier mode (Client-Server).
3. . Advantage Internet Server (AIS).

AIS: Advantage can establish a secure connection between remote locations through basic Internet connections. Using an Advantage Internet connection provides both encryption and compression. When the connection is done via the Internet then it is referred to as an Advantage Internet Server (AIS) connection (**not a remote connection as logically you might conclude**). This requires configuring an Internet port and opening that port within the firewall at the server end as well as the client's end. With the Advantage Internet Server, a developer can have a truly Internet-enabled application without any code changes. This simple, non-HTML solution is incorporated into the Advantage Database Server so that the Internet can be used as its own virtual private network. Be advised that Internet connections tend to be slower than a regular LAN connection, thus certain ways to display data might need to be avoided.

Remote: Do not confuse the term "Advantage Remote Connection" with an internet connection to the data on the server. With ADS, a Remote connection is really the LAN connection to an actual ADS server, i.e. a two tier -Client-Server system connecting via tcp or udp without the use of the Internet. When using Remote connections, there is no need to share the data directory that contains the actual dbf/adt tables for an Advantage enabled application to access this data. This is one of the security features of ADS using server-side aliasing which we will discuss on the later part of this document.

The Advantage Database Server is the key to improved database performance in network environments. The server acts as an intelligent controller that reduces competition for resources and off-loads much of the work normally performed by each client workstation. It is responsible for all database access, including all reading and writing of data, and lock management. Working with the network operating system, the Advantage Database Server processes data requests and returns the information to the network clients.

The Advantage Database Server supports the NetWare, Windows, and Linux operating systems. The Advantage Database Server for NetWare is implemented as a NetWare Loadable Module (NLM). The Advantage Database Server for Windows operates as a Windows Service. The Advantage Database Server for Linux runs as Linux daemon service. The Remote and AIS client code used by an Harbour client application compiled to run under Windows is axcws32.dll. The Remote and AIS code used by an Harbour client application compiled to run under Linux is a shared object named libads.so.

ALS: The Advantage Local Server allows Advantage applications access to data files located locally, in shared environments, or in peer-to-peer environments. The Advantage Local Server is a non-client/server solution and can be used to access data on the local computer or on a shared file server that is not running the Advantage Database Server service.

The Advantage Local Server is called directly by the Advantage Client Engine, both of which exist as either Windows DLLs or Linux shared objects. If the data files exist on a local workstation, no network connection is necessary nor is network communication used between the Advantage client and the Advantage Local Server.

There is no cost for the Advantage Local Server. The Advantage Local Server is installed with all Advantage Windows and Linux client products (which are also free). With ALS you may develop applications for single and multi-user environments and distribute them royalty-free.

The Windows version of the Advantage Local Server (ALS) is a DLL named ADSLOC32.DLL. The Linux version of the Advantage Local Server is a shared object named libadsloc.so. The Advantage Local Server allows both single-user and multiple-user access to data files. Note however that the Advantage Local Server file that is installed with Advantage client products contains a physical limitation such that only five or fewer users can concurrently access any table.

One drawback of ALS is the lack of "transaction processing". A second drawback is the fact that the ALS "client" works in the same thread with the ALS "server", waiting one for another as it would if the data was stored locally on the client machine. In this scenario the server only acts as a file sharing disk to multiple workstations pulling data across the network. But then again, this is exactly how any other Harbour RDD works.

What makes ALS very attractive is that you may distribute your application to smaller customers without the ADS server and when the customer grows in the number of users, or requires greater security and speed, or cannot tolerate the possibility of data/index corruption due to a workstation unexpected crash, then for a small price you may deploy the ADS remote server while not even having to recompile your application.

In my next posts I will show some of the advantages of ADS over any other native xbase RDD and how to start taking advantage of it.

Reinaldo.