In this article Barry Mavin, CEO and Chief Software Architect for Recital, details how to use the Client Drivers provided with the Recital Database Server to work with local or remote server-side OLE DB data sources.

Overview

The Recital Universal .NET Data Provider provides connectivity to the Recital Database Server running on any supported platform (Windows, Linux, Unix, OpenVMS) using the RecitalConnection object.

The Recital Universal JDBC Driver provides the same functionality for java applications.

The Recital Universal ODBC Driver provides the same functionality for applications that use ODBC.

Each of the above Client Drivers use a connection string to describe connections parameters.

The basic format of a connection string consists of a series of keyword/value pairs separated by semicolons. The equal sign (=) connects each keyword and its value.

The following table lists the valid names for keyword/values.

Name	Default	Description
Data Source -or- Server -or- Nodename		The name or network address of the instance of the Recital Database Server which to connect to.
Directory		The target directory on the remote server where data to be accessed resides. This is ignored when a Database is specified.
Encrypt -or- Encryption	false	When true, DES3 encryption is used for all data sent between the client and server.
Initial Catalog -or- Database		The name of the database on the remote server.
Password -or- Pwd		The password used to authenticate access to the remote server.
User ID		The user name used to authenticate access to the remote server.
Connection Pooling -or- Pool	false	Enable connection pooling to the server. This provides for one connection to be shared.
Logging	false	Provides for the ability to log all server requests for debugging purposes
Rowid	true	When Rowid is true (the default) a column will be post-fixed to each SELECT query that is a unique row identifier. This is used to provide optimised UPDATE and DELETE operations. If you use the RecitalSqlGrid, RecitalSqlForm, or RecitalSqlGridForm components then this column is not visible but is used to handle updates to the underlying data source.
Logfile		The name of the logfile for logging
Gateway		Opens an SQL gateway(Connection) to a foreign SQL data source on the remote server. Using Gateways, you can transparently access the following local or remote data sources: Recital Oracle ODBC (Server-side ODBC data sources) JDBC (Server-side JDBC data sources) ADO (Use this to connect to SQL Server and other Native Windows OLEDB data sources) MySQL PostgreSQL The gateway can be specified in several formats: servertype@nodename:username/password-database e.g. oracle@nodename:username/password-database mysql@nodename:username/password-database postgresql@nodename:username/password-database -or- odbc:odbc_data_source_name_on_server oledb:oledb_connection_string_on_server jdbc:jdbc_driver_path_on_server;jdbc:Recital:args

To connect to a server-side OLE DB data source, you use the gateway=value key/value pair in the following way.

gateway=oledb:oledb_connection_string_on_server

Important
When specifying the connection string be sure to quote the gateway= with "...".

You can find examples of connection strings for most ODBC and OLE DB data sources by clicking here.

Example in C# using the Recital Universal .NET Data Provider:

////////////////////////////////////////////////////////////////////////
// include the references below
using System.Data;
using Recital.Data;
 
////////////////////////////////////////////////////////////////////////
// The following code example creates an instance of a DataAdapter that 
// uses a Connection to the Recital Database Server, and a gateway to
// the SQL server Northwind database. It then populates a DataTable 
// in a DataSet with the list of customers. The SQL statement and 
// Connection arguments passed to the DataAdapter constructor are used 
// to create the SelectCommand property of the DataAdapter.
public DataSet SelectCustomers()
{
	string gateway = "oledb:Provider=sqloledb;Initial Catalog=Northwind;
		Data Source=localhost;Integrated Security=SSPI";
	RecitalConnection swindConn = new 
		RecitalConnection("Data Source=localhost;gateway=\""+gateway+"\");
	RecitalCommand selectCMD = new 
		RecitalCommand("SELECT CustomerID, CompanyName FROM Customers", swindConn);
	selectCMD.CommandTimeout = 30;
	RecitalDataAdapter custDA = new RecitalDataAdapter();
	custDA.SelectCommand = selectCMD;
	swindConn.Open();
	DataSet custDS = new DataSet();
	custDA.Fill(custDS, "Customers");
	swindConn.Close();
	return custDS;
}

Example in Java using the Recital Universal JDBC Driver:

////////////////////////////////////////////////////////////////////////
// standard imports required by the JDBC driver
import java.sql.*;
import java.io.*;
import java.net.URL;
import java.math.BigDecimal;
import Recital.sql.*;
 
////////////////////////////////////////////////////////////////////////
// The following code example creates a Connection to the Recital 
// Database Server, and a gateway to the SQL server Northwind database. 
// It then retrieves all the customers.
public void SelectCustomers()
{
    // setup the Connection URL for JDBC
	String gateway = "oledb:Provider=sqloledb;Initial Catalog=Northwind;
		Data Source=localhost;Integrated Security=SSPI";
	String url = "jdbc:Recital:Data Source=localhost;gateway=\""+gateway+"\";
	// load the Recital Universal JDBC Driver
	new RecitalDriver();
 
	// create the connection
	Connection con = DriverManager.getConnection(url);
	// create the statement
	Statement stmt = con.createStatement();
	// perform the SQL query
	ResultSet rs = stmt.executeQuery("SELECT CustomerID, CompanyName FROM Customers");
	// fetch the data
	while (rs.next()) 
	{
		String CompanyID = rs.getString("CustomerID");
		String CompanyName = rs.getString("CompanyName");
		// do something with the data...
	}
    
	// Release the statement
	stmt.close();
	
	// Disconnect from the server
	con.close();
}

Each Recital table can have one or more data dictionaries to provide a central repository for constraints and other metadata. 

Here's how to set up field validation for a field with a small static number of acceptable values.

Using the example.dbf table from the southwind sample database, validation can be added to the title field to ensure it matches one of a list values.

open database southwind
alter table example add constraint;
 (title set check inlist(alltrim(title),"Miss","Mr","Mrs","Ms"))

The inlist() function checks whether the specified expression exists in the comma-separated list which follows.  An attempt to update title with a value not in the list will give an error: Validation on field 'TITLE' failed.

If you have access to the Recital Workbench, you can use the modify structure worksurface to add and alter your dictionary entries, including a customized error message if required.