Full details on Recital Function Keys can be found in the Key Assist section of the Help menu, or in our documentation wiki here.

In this article Barry Mavin, CEO and Chief Software Architect for Recital provides details on how the Recital Database Server can be used to provide a solution for Universal Data Integration.

Overview

The Recital Database Server handles universal cross-platform data access to a wide range of data sources. The database server natively handles full remote SQL data access to Recital, Visual FoxPro, FoxPro, FoxBASE, Clipper and older dBase data. Using Bridges, it handles full remote SQL data access to C-ISAM and OpenVMS RMS. Using gateway connections, it handles full remote SQL data access to Oracle, MySQL, PostgreSQL, SQL Server, server-side ODBC, server-side JDBC and server-side OLE DB data sources. With its ability to access data using server-side ODBC, JDBC and OLE DB drivers from clients on all supported operating systems (Windows, Linux, Unix, OpenVMS), the Recital Database Server is an ideal Data Integration Solution for applications of all sizes and complexity.

Universal Data Integration Solutions

There are several ways in which data may be accessed by the Database Server.

Table 1:

Client Universal Data Access solutions for accessing local or remote data.

Client	Solution
Recital	Use remote gateway connections
Visual FoxPro	Use the Universal ODBC Driver
Java (all platforms)	Use the Universal JDBC Driver
.NET Framework	Use the Universal .NET Data Provider
Microsoft Office	Use the Universal ODBC Driver
Windows Mobile	Use the Universal Compact Framework .NET Data Provider
PHP on Linux	Use the Universal ODBC Driver for Linux
Mono on Linux	Use the Universal .NET Data Provider
Others	If the data source you want to access is not in the list above, then you can use a remote ODBC, JDBC or OLE DB gateway. You can find examples of connection strings for most ODBC and OLE DB data sources by clicking here.

Table 2:

Windows Server Universal Data Access solutions accessible from any remote client running on Windows, Linux, Unix or OpenVMS:

Data Source	Solution
Recital	Native support (See table 1)
Visual FoxPro	Native support (See table 1)
FoxPro	Native support (See table 1)
FoxBASE	Native support (See table 1)
Clipper	Native support (See table 1)
dBase	Native support (See table 1)
C-ISAM	Use a bridge (See table 1)
Access	Use a gateway connection gateway="oledb:Provider=Microsoft.Jet.OLEDB.4.0;Data Source=\somepath\mydb.mdb;User Id=admin;Password=;"
Exchange	Use a gateway connection gateway="oledb:Provider=ExOLEDB.DataSource;Data Source=http://servername/publicstore"
Excel	Use a gateway connection gateway="oledb:Provider=Microsoft.Jet.OLEDB.4.0;Data Source=C:\MyExcel.xls;"
Oracle	Use a gateway connection gateway="oledb:Provider=msdaora;Data Source=TheOracleDB;User Id=xxxxx;Password=xxxxx;"
SQL Server	Use a gateway connection gateway="oledb:Provider=sqloledb;Data Source=Aron1;Initial Catalog=pubs;User Id=sa;Password=asdasd;"
MySQL	Use a gateway connection gateway="oledb:Provider=MySQLProv;Data Source=mydb;User Id=xxxxx;Password=xxxxx;"
IBM DB2	Use a gateway connection gateway="oledb:Provider=DB2OLEDB;Network Transport Library=TCPIP;Network Address=XXX.XXX.XXX.XXX;Initial Catalog=MyCtlg;Package Collection=MyPkgCol;Default Schema=Schema;User ID=MyUser;Password=MyPW"
Sybase ASA	Use a gateway connection gateway="oledb:Provider=ASAProv;Data source=myASA"
Sybase ASE	Use a gateway connection gateway="oledb:Provider=Sybase.ASEOLEDBProvider;Srvr=myASEserver,5000;Catalog=myDBname;User Id=username;Password=password"
IBM Informix	Use a gateway connection gateway="oledb:Provider=Ifxoledbc.2;password=myPw;User ID=myUser;Data Source=dbName@serverName;Persist Security Info=true"
Ingres	Use a gateway connection gateway="odbc:dsn=data_source_name"
Firebird	Use a gateway connection gateway="odbc:dsn=data_source_name"
IBM AS400 iSeries	Use a gateway connection gateway="oledb:PROVIDER=IBMDA400; DATA SOURCE=MY_SYSTEM_NAME;USER ID=myUserName;PASSWORD=myPwd"
Interbase	Use a gateway connection gateway="oledb:provider=sibprovider;location=localhost:;data source=c:\databases\gdbs\mygdb.gdb;user id=xxxxx;password=xxxxx"
Others	If the data source you want to access is not in the list above, then you can use server-side ODBC, JDBC or OLE DB. You can find examples of connection strings for most ODBC and OLE DB data sources by clicking here. Full details on using server-side JDBC drivers can be found here. Full details on using server-side ODBC drivers can be found here. Full details on using server-side OLE DB drivers can be found here.

Table 3:

Linux and Unix Server Universal Data Access solutions accessible from any remote client running on Windows, Linux, Unix or OpenVMS:

Data Source	Solution
Recital	Native support (See table 1)
Visual FoxPro	Native support (See table 1)
FoxPro	Native support (See table 1)
FoxBASE	Native support (See table 1)
Clipper	Native support (See table 1)
dBase	Native support (See table 1)
C-ISAM	Use a bridge (See table 1)
Oracle	Use a gateway connection gateway="oracle:Connection_String"
MySQL	Use a gateway connection gateway="mysql:Connection_String"
IBM DB2	Use a gateway connection gateway="db2:Connection_String"
PostgreSQL	Use a gateway connection gateway="postgres:Connection_String"
Others	If the data source you want to access is not in the list above, then you can use a server-side JDBC driver. Full details on using server-side JDBC drivers can be found here.

Table 4:

OpenVMS Server Universal Data Access solutions accessible from any remote client running on Windows, Linux, Unix or OpenVMS:

Data Source	Solution
Recital	Native support (See table 1)
Visual FoxPro	Native support (See table 1)
FoxPro	Native support (See table 1)
FoxBASE	Native support (See table 1)
Clipper	Native support (See table 1)
dBase	Native support (See table 1)
RMS	Use a bridge (See table 1)
Others	If the data source you want to access is not in the list above, then you can use a server-side JDBC driver.

Supported Data Sources

Native Data Access

The Recital Database Server has native built-in support for the following data sources:

• Recital
• Visual FoxPro
• FoxPro
• FoxBASE
• Clipper
• dBase

You can setup tables to work with using the Database Administration Tool in Recital Enterprise Studio.

Bridges

Using Bridges, you can access the following data sources as if they were standard Recital/FoxPro tables:

• CISAM
• OpenVMS RMS

You can setup bridges using the Database Administration Tool in Recital Enterprise Studio.

Gateways/Connections

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)
• OLEDB Use this to connect to SQL Server and other Windows OLE DB data sources)
• MySQL
• PostgreSQL

Remote Data Object functions

Recital 10 includes a complete and robust set of data source independent functions for accession MySQL, Oracle, DB2 and Postgres. This article explains how to use them.

Client Data Access drivers

Included with the Recital Database Server are three Client drivers. These Client drivers can access any data sources supported by the Recital Database Server. They are not restricted to accessing only Recital data. They can be used to access server-side ODBC, JDBC and OLE DB data sources also.

Recital Universal .NET Data Provider

Use this client driver when building .NET applications with Visual Studio .NET. A data provider in the .NET Framework serves as a bridge between an application and a data source. A data provider is used to retrieve data from a data source and to reconcile changes to that data back to the data source.

Key features of the Recital Universal .NET Data Provider:

• Fully Internet enabled
  The Recital Universal .NET Data Provider works across the internet providing access to a wide range of data sources located on remote servers running Windows, Linux, Unix and OpenVMS.
• SQL Server compatible
  The Recital Universal .NET Data Provider is plug compatible with the .NET Framework SQL Server Data Provider.
• Cross-platform Data Integration
  Using the Recital Universal .NET Data Provider, you can connect to remote Windows, Linux, Unix or OpenVMS servers and access any data source supported by the Recital Database Server.
• Managed code
  The Recital Universal .NET Data Adaptor written in C# is 100% .NET Framework managed code.
• Runs on Windows Mobile
  The Recital Universal .NET Data Adaptor runs under the .NET Compact Framework on Windows Mobile.

Recital Universal JDBC Driver

The JDBC API is the industry standard for database-independent connectivity between the Java programming language and a wide range of databases. The JDBC API provides a call-level API for SQL-based database access. JDBC technology allows you to use the Java programming language to exploit "Write Once, Run Anywhere" capabilities for applications that require access to enterprise data.

Key features of the Recital Universal JDBC Driver:

• Fully Internet enabled
  The Recital Universal JDBC driver works across the internet providing access to a wide range of data sources located on remote servers running Windows, Linux, Unix and OpenVMS.
• JDBC 3.0 API
  The Recital Universal JDBC driver supports the JDBC 3.0 API.
• Pure Java Type 3 Driver
  The Recital Universal JDBC driver is a 100% pure Java Type 3 driver.
• Full Access to Metadata
  The JDBC API provides metadata access that enables the development of sophisticated applications that need to understand the underlying facilities and capabilities of a specific database connection.
• Cross-platform Data Integration
  Using the Recital Universal JDBC driver, you can connect to remote Windows, Linux, Unix or OpenVMS servers and access any data source supported by the Recital Database Server.
• No Installation
  A pure JDBC technology-based driver does not require special installation; it is automatically downloaded as part of the applet that makes the JDBC calls. The Recital Universal JDBC Driver is 100% java.

Recital Universal ODBC Driver

Connect to remote data from Microsoft Office or other applications that support ODBC data access. The Recital Universal ODBC Driver is also available for Linux and Unix.

Key features of the Recital Universal ODBC Driver:

• Fully Internet enabled
  The Recital Universal ODBC driver works across the internet providing access to a wide range of data sources located on remote servers running Windows, Linux, Unix and OpenVMS.
• Works with Crystal Reports
  The Recital Universal ODBC driver supports the SQL syntax generated by Crystal Reports.
• Works with Microsoft Office
  The Recital Universal ODBC driver works with Microsoft Office products.
• Works with PHP on Linux
  The Recital Universal ODBC driver is available for Linux and works with PHP.

This article examines the advantages of using databases and looks at how to create databases for new and existing applications.

Overview

file which contains information, including full path details, about all the files that belong to that particular database. Opening a database gives an application access to all that database's files - operating system and data dictionary protection and security permitting - in whichever directory on the system they reside and database commands can target the files as a single unit.

NOTE: The word 'database' has often been used in Xbase products to refer to an individual '.dbf' file. In this article these are referred to as 'tables' and a database may contain many tables.

Advantages

Recital has always offered developers the maximum in flexibility in the design and deployment of their applications. The SET DEFAULT and SET PATH commands along with the ability to access files via their full Operating System path name has allowed data and code to be created and stored in any required location. Such flexibility does however put the onus on the developer to manage all elements of the application and ensure that maintenance tasks cover all files. The introduction of the database commands retains the established developer-driven design, but provides functionality to facilitate the access and maintenance of the components of that design. The functionality offered is in three main areas:

• Facilitate data access
• Facilitate the storage and extraction of information about the files in an application
• Facilitate the maintenance of the files in an application

These three areas are looked at in more detail in the sections below.

Data Access

The immediate effect of using a database is that all the database's tables and associated files (indexes, dictionaries, memo files) are accessible with the issue of a single command, the OPEN DATABASE command.

// Open the database
> open database southwind
// List the database tables
> list tables

Tables in Database southwind:
 Name                Source
 categories		/usr/recital/data/southwind/categories.dbf
 customers		/usr/recital/data/southwind/customers.dbf
 employees		/usr/recital/data/southwind/employees.dbf
 example		/usr/recital/data/southwind/example.dbf
 order_details	/usr/recital/data/southwind/order_details.dbf
 orders			/usr/recital/data/southwind/orders.dbf
 productsbyname	/usr/recital/data/southwind/productsbyname.dbf
 products		/usr/recital/data/southwind/products.dbf
 shippers		/usr/recital/data/southwind/shippers.dbf
 suppliers		/usr/recital/data/southwind/suppliers.dbf
 cisamdemo		/usr/recital/data/southwind/cisamdemo.dbf

> use example

In the case of the sample southwind database that ships with Recital products on all platforms and is shown above, this effect can be achieved in other ways (SET PATH or SET DEFAULT), since its files all reside in the southwind directory. The database advantage comes when the database catalog contains files from multiple directories, e.g.

// Open the database
> open database myapp
// List the database tables
> list tables

Tables in Database myapp:
  Name                Source
  zipcodes		/usr/myapp/data/lookups/zipcodes.dbf
  customers		/usr/myapp/data/current/customers.dbf
  archive03		/usr/myapp/data/archive/archive03.dbf
  archive04		/usr/myapp/data/archive/archive04.dbf
  users			/usr/allapps/data/users.dbf
  menus		/usr/myapp/data/system/menus.dbf

// Open a table
> use users

The OPEN DATABASE command requires only the database name to be specified, not the complete path of a directory as with SET PATH or SET DEFAULT. Databases are searched for in the sub-directories of the directory defined in the DB_DATADIR environment variable or symbol. DB_DATADIR is set in the system wide configuration file.

#---------------------------------------------------
# location of directories and important files
#---------------------------------------------------
DB_DATADIR="${ROI_ROOT}data/"     ;export DB_DATADIR

NOTE: DB_DATADIR is read from these files at startup to determine the home directory for databases. Updates to DB_DATADIR once a Recital process is running do not change this setting. The OPEN DATABASE command and certain other database commands allow a '?' to be specified in place of a database name. In this case the 'Select a file' dialog is displayed, listing the available files in the DB_DATADIR directory.

Click image to display full size

Fig 1: Recital Terminal Developer OPEN DATABASE ? command.

This functionality is also supported by the PACK DATABASE, REBUILD DATABASE and REINDEX DATABASE commands.

Databases can also simplify data access for Recital Client Drivers using the Recital Database Server: instead of specifying a starting directory, only a database name is required. The database can handle files from multiple directories and associate tables with their single index files.

Recital Universal .NET Data Provider

/////////////////////////////////////////
// include the references below
using System.Data;
using Recital.Data;

/////////////////////////////////////////
// sample code to call a Stored Procedure
public int CallStoredProcedure()
{
    string source = "Data Source=localhost;" +
	                "Database=southwind;" +
			"uid=?;"+
			"pwd=?";
						
	RecitalConnection conn = new RecitalConnection(source);
	...

Recital Universal JDBC Driver

import java.sql.*;
import java.io.*;
import java.net.URL;
import java.math.BigDecimal;
import Recital.sql.*;

public class jdbc_test {

  public static void main(String argv[]) {
    int i;
    ResultSet rs;
    ResultSetMetaData rsmd;

    System.out.println("Recital JDBC driver verification.");
	
    for (int ii=0; ii<1; ++ii) {
      try {
        //----------------------------------------------------------
        //-- Load the Client Driver for the
        //-- Recital Universal Application Server
        //----------------------------------------------------------
        System.out.println("Loading Recital JDBC driver.");
        new RecitalDriver();
        //-----------------------------------------------------------
        //-- The standard format of the connection URL is as follows:
        //-----------------------------------------------------------
        String url = "jdbc:Recital:" +
                     "SERVERNAME=?;" +
                     "DATABASE=jdbc_test;" +
                     "USERNAME=?;" +
                     "PASSWORD=?;" +
                     "ENCRYPTION=false";
...

Windows Recital Universal ODBC Driver

Click image to display full size

Fig 2: Recital Universal ODBC Driver DSN setup using a database.

Database Procedure Libraries

A database can have an associated procedure library, which is automatically opened when the database is opened. This way, any procedures required by the database's data files are always available. The procedure library should reside in the database's directory and be named dbc_xxx_library.prg, where 'xxx' is the name of the database. When the OPEN DATABASE command is issued, a check is made for the database procedure library and a SET PROCEDURE TO dbc_xxx_library.prg ADDITIVE issued automatically. The procedure library is in turn closed when the CLOSE DATABASES command is issued. This is particularly convenient for client/server database access.

Database Events

Issuing the OPEN DATABASE or CLOSE DATABASES command also fires a database event. Database events, like triggers for tables and forms, can have programs associated with them. The OPEN DATABASE command fires the DBC_OPENDATA event and will run a program called db_opendata.prg if one exists in the database's directory. Similarly, the CLOSE DATABASES command fires the DBC_CLOSEDATA event and runs the db_closedata.prg program. Both of these events also allow the current open or close operation to be abandoned if the associated program returns a logical false (.F.).

Information

Databases, specifically database catalogs, are an excellent place to store information about the files required by a particular application. Instead of having to search through application code to determine which tables are being used and what index keys they have, this information can be viewed in the database catalog. Database catalogs are themselves Recital tables and can be viewed and/or updated in the same way as any other Recital table. There is also a series of commands to provide information about the currently open database. DISPLAY/LIST DATABASE The DISPLAY DATABASE and LIST DATABASE commands display the database name and path, followed by the equivalent of LIST STRUCTURE INDEX and LIST DICTIONARY for each table in the database, e.g.

> open database southwind
> display database

Database Name:  southwind
Database Path:  /usr/recital-9.0/data/southwind/

Structure for database : categories.dbf
Number of data records : 8
Date of creation : 05/12/2004
Date of last update : 05/12/2004
Database encrypted : False


Field	Field Name		Type			Width	Dec	Description
    1	CATEGORYID	Numeric       	10			Category ID
    2	CATEGORYNAME	Character     	15			Category Name
    3	DESCRIPTION	Memo           	8			Description
    4	PICTURE		Memo           	8			Picture
** Total **                       42
Production DBX file: categories.dbx
  Master Index TAG: CATEGORYID
  Key: categoryid
  Type: Binary
  Len: 8
...

DISPLAY DATABASE shows the data one screen at a time, whereas LIST DATABASE is ideal for output to a file.

> open database southwind
> list database to file info.txt

DISPLAY/LIST TABLES

LIST TABLES, as we have seen above, lists all the tables from the database, giving each table's name and path. DISPLAY TABLES shows the information one screen at a time.

Maintenance

Using a database can simplify the maintenance of an application's programs, tables and indexes. Multiple files, possibly in different directories, can be targeted by a single database command.

COMPILE DATABASE

The COMPILE DATABASE command can be used to issue a COMPILE command for all program files listed in the database catalog.

// Open the database
open database myapp

// Compile all the database's programs
compile database

NOTE: Program files are added to a database using the SQL CREATE PROCEDURE command.

PACK DATABASE

The PACK DATABASE command issues a PACK command for every table in the database catalog. The PACK command is used to permanently remove any records that have been marked for deletion using the DELETE command.

// Open the database
open database southwind
// Pack all the database's tables
pack database

REINDEX DATABASE

The REINDEX DATABASE command rebuilds all the tag and single indexes in the catalog. This is the equivalent of an INDEX ON <key> TO | TAG <index> for each catalogued index key.

// Open the database
open database southwind
// Rebuild all the database's indexes
reindex database

NOTE: Using a database helps protect against a table being opened without its associated single index files also being opened. Any single index files that are included in the database catalog will automatically be opened when their table is opened via the database. If a single index appears in the database catalog, but the physical file no longer exists, it will be removed from the catalog when its associated table is next opened. All indexes, tagged indexes or single indexes, created while the database is open, are added automatically to the database catalog.

REBUILD DATABASE

The REBUILD DATABASE command is used to PACK, rebuild the index tags and refresh the contents of the database catalog file.

// Rebuild the database
rebuild database southwind

Creating and populating a database

Databases are created using the CREATE DATABASE command.

// Create new database
create database newdb

The CREATE DATABASE creates a sub-directory in the DB_DATADIR and initializes the new database's catalog file. The catalog file is given the same basename as the database and is a Recital table with a '.cat' file extension. It has a production index file with a '.cax' file extension and a memo file with a '.cam' file extension.

// Open the database
open database newdb

With the database open, the catalog file table is opened in the highest available workarea and is given an alias name of its basename preceded by an underscore, e.g. '_newdb'. Any new tables or indexes that are created will be automatically added into the catalog and form part of the database. 'Free' tables can also be manually added into a database using the SQL ADD TABLE command.

// config.db
set sql on
set sql to vfp
// end of config.db

// Create a 'free' table, with no database open
create table free1 (field1 char(10), field2 date)
// Open the database
open database newdb
add table free1

As the application runs, 'myapp' in the example above, each table that is opened is added to the database catalog. Indexes that are opened are added in the same way. Using SET AUTOCATALOG OFF, inclusion in the catalog can be restricted. Once all required areas of the application have been catalogued, the application can be updated to make use of the database commands.

Converting an existing application

The AUTOCATALOG commands can be used to automatically create a database catalog based on an existing application. The SET AUTOCATALOG TO >database< command will create the database if it does not already exist.

// Database must be closed during autocatalog process
close databases
// Specify the database
set autocatalog to myappdb
// Start the autocatalog process
set autocatalog on
do myapp
// The autocatalog process can be toggled off to exclude 
// certain parts of the application if required
// set autocatalog off

Exporting a database

The BACKUP DATABASE and RESTORE DATABASE commands have been added to simplify the process of moving applications between binary incompatible platforms. Binary files such as tables, memo files and data dictionaries must be exported to ASCII format to allow them to be transferred from one platform to another where the platforms have different binary ordering. For example, this is the case when moving files between a SUN Sparc Solaris machine and an Intel Linux machine. The BACKUP DATABASE and RESTORE DATABASE commands are extensions of the BUILD and INSTALL commands: where BUILD and INSTALL operate on a specified list of tables, BACKUP DATABASE and RESTORE DATABASE automatically handle an entire database.

// Open the database
open database southwind
// Export the database to ASCII format
backup database

The BACKUP DATABASE command goes through the database catalog, exporting each file into an ASCII format that can be handled by the RESTORE DATABASE command. The files are created in a directory with the same name as the database. This directory is a sub-directory of the directory specified in the environment variable DB_BACKUPDIR and is created automatically. By default, DB_BACKUPDIR is the 'backup' sub-directory of the Recital home directory.

// Query the DB_BACKUPDIR environment variable setting
> ? getenv([DB_BACKUPDIR])
/usr/recital/backup

Like DB_DATADIR, DB_BACKUPDIR is set in the system-wide configuration file and is read at startup to determine the home directory for database backups. Updates to DB_BACKUPDIR once a Recital process is running do not change this setting.

# profile.db/uas extract
#---------------------------------------------------
# location of directories and important files
#---------------------------------------------------
DB_BACKUPDIR="${ROI_ROOT}backup/"     ;export DB_BACKUPDIR

Once the BACKUP DATABASE command has completed, the files can be transferred to another platform, for example from Intel SCO OpenServer to IBM AIX and the RESTORE DATABASE command used to recreate the database.

// Export the database to ASCII format
// Note: the BACKUP DATABASE command operates
// on the active or specified database
$ db
> backup database southwind
> quit

// 'tar' up the files for transfer
$ cd /usr/recital/backup
$ tar cvf southwind.tar ./southwind

// Transfer the tar archive to DB_BAKUPDIR on the 
// target machine, then extract the files
$ pwd
/usr/recital/backup
$ tar xvf southwind.tar

// Rebuild the database on the target platform
// The database is automatically created 
// as a sub-directory of DB_DATADIR
$ db
> restore database southwind

Usually, you do not need to setup an email server under Linux. Most GUI email clients support Gmail POP3 and IMAP configurations. But, how do you send mail via the standard /usr/bin/mail user agents in a shell script? Programs such as sendmail / postfix / exim can be configured as a gmail smarthost but they are largely overkill for this use. The ssmtp program is a neat utility that does just that for you via gmail.