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 exampleIn 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 tableThe 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.
> use users
#---------------------------------------------------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.
# location of directories and important files
#---------------------------------------------------
DB_DATADIR="${ROI_ROOT}data/" ;export DB_DATADIR
Click image to display full sizeFig 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 sizeFig 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: southwindDISPLAY DATABASE shows the data one screen at a time, whereas LIST DATABASE is ideal for output to a file.
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
...
> 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 databaseNOTE: Program files are added to a database using the SQL CREATE PROCEDURE command.
open database myapp
// Compile all the database's programs
compile database
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 databaseNOTE: 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.
open database southwind
// Rebuild all the database's indexes
reindex database
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 databaseThe 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.
create database newdb
// Open the databaseWith 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.
open database newdb
// config.dbAs 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.
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
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 databaseThe 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.
open database southwind
// Export the database to ASCII format
backup database
// Query the DB_BACKUPDIR environment variable settingLike 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.
> ? getenv([DB_BACKUPDIR])
/usr/recital/backup
# profile.db/uas extractOnce 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.
#---------------------------------------------------
# location of directories and important files
#---------------------------------------------------
DB_BACKUPDIR="${ROI_ROOT}backup/" ;export DB_BACKUPDIR
// 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