Advantage Database Ruby Driver

This is a native Advantage Database driver for Ruby. This driver is intended to be a base-level library to be used by interface libraries such as ActiveRecord.

This driver can be used with Advantage Database 11 and later versions.

This driver is licensed under the Apache License, Version 2.

Build Instructions

Requirements

C Compiler
Ruby
RubyGem Package manager

All Platforms

To build the library (.so), use:

rake

To build and install the gem, use:

rake gem
rake install

The other rake tasks are

rake clean   -> Cleans up all temp files (ex *.~)
rake clobber -> Cleans up all built files (ex *.gem, *.o, *.so)

Additional Install Notes for Windows

The popular One-Click Ruby Installer for Windows (RubyInstaller) is built using Microsoft Visual C++ 6.0. Since problems can arise by combining binaries from different compilers, we advise you use this compiler.

If you want to use a more recent version of the MS C++ compiler, you will need to make a few changes:

Open the file: <RUBY DIR>libruby1.8i386-mswin32config.h, and comment out the first three lines so they look like:
```
//#if _MSC_VER != 1200
//#error MSC version unmatch
//#endif
```
This removes the check for C++ Version 6.0
Open rakefile and set:
```
APPLY_MANIFEST = true
```
This will add the manifest to the compiled binaries.

By default, rake will attempt to use Microsoft nmake when building under Windows. To use another make program, set:

USE_NMAKE_ON_WIN = FALSE

Running Unit Tests

Change to the the test directory
```
cd test
```

Create a testing database:

Use ARC to create a new database either via the "CTRL-W" in ARC shortcut or using the
CREATE DATABASE SQLstatement.  For example:
CREATE DATABASE [c:\test\ruby.add];

Create the test schema:

Open the test.sql within ARC while connected to the test database and execute the script.

Run the unit tests:
```
ruby advantage_test.rb
```

Sample

This script makes a connection, prints Successful Ruby Connection to Advantage, then disconnects.

# load the Advantage gem (not needed if included in your Gemfile)
begin
  require 'rubygems'
  gem 'advantage'
  unless defined? Advantage
    require 'advantage'
  end
end
# create an interface
api = Advantage::AdvantageInterface.new()
# initialize the interface (loads the DLL/SO)
Advantage::API.ads_initialize_interface( api )
# initialize our api object.  You need access to the libace.(so|dll) file to run this command
# See: https://devzone.advantagedatabase.com/dz/content.aspx?Key=20&Release=19&Product=14
api.ads_init()
# create a connection
conn = api.ads_new_connection()
# establish a connection
# ads_connect appears to be a call to the AdsConnect101 procedure:
# https://devzone.advantagedatabase.com/dz/webhelp/Advantage11.1/index.html?ace_adsconnect101.htm
api.ads_connect(conn, "data source=c:\\test\\ruby.add;user id=adssys;")
# execute a query without a result set
api.ads_execute_immediate(conn, "select 'Successful Ruby Connection' from system.iota;")
# disconnect from the database
api.ads_disconnect(conn)
# free the connection resources
api.ads_free_connection(conn)
# free resources the api object uses
api.ads_fini()
# close the interface
Advantage::API.ads_finalize_interface( api )