The PSQL Java interface is an object-oriented addition to the classic Btrieve API.

The following topics introduce the interface and its basic use:

For detailed information on developing for the Java interface in PSQL, see Programming with the Java Class Library.

The PSQL Java Classes are an interface to the MicroKernel Engine.

The PSQL Relational Engineallows the users to reference databases with column level granularity. On the other hand, the MicroKernel Engine is concerned only with files, records, and indexes, and the application programs themselves are responsible for field-level access within the data buffer returned by a Btrieve API call.

In a SQL database, column-level information is available in the data dictionary stored in the data dictionary files.

The purpose of this API is not only to provide language binding to object-oriented languages, like Java and C++, but also to furnish a logical structure that fits into object-oriented applications.

The design of the object-oriented API addresses the following goals:

Shortly after the introduction of Java, a database interface, Java Database Connectivity (JDBC) was introduced. JDBC is gaining more and more popularity among database developers. The design of the new PSQL Java API uses the JDBC API as a model and applies many of the ideas and the methodology used in JDBC. However, some new concepts had to be introduced because JDBC was designed to support SQL and generally the relational model, whereas this API set supports the transactional Btrieve.

As was mentioned previously, if a Btrieve application accesses a data file that belongs to a SQL database, the new API calls can use the column descriptions stored in the dictionary of the database. In the case of Btrieve data files that are not part of any SQL database, the new API provides other means to access these files.

A set of Btrieve data files that do not belong to any SQL database still form a database if some application programs tie them together in a logical sense. Such databases are referred to as loosely-coupled databases. A loosely-coupled database has no database dictionary. On the other hand, SQL databases will be referred to as tightly-coupled databases. A tightly-coupled database does have a persistent database dictionary.

The PSQL Java interface can operate at a high or low level depending on which classes you use.

The high-level portion of the Java interface hides many of the implementation details that Btrieve programmers have dealt with formerly, such as position blocks, data buffers, and so on.

A user who currently has a loosely coupled database and wants to take full advantage of the column-level support of the new API must choose one of the following options:

This section contains information about proper configuration for use of the PSQL Java interface.

The PSQL Java interface supports JDKs 1.4 and higher.

The PSQL SDK configuration needs the CLASSPATH variable to point to the PSQL classes.

The sample CLASSPATH assumes that PSQL was installed to file_path\PSQL. The Java Class Library SDK is installed to file_path\PSQL\SDK\JCL. For default locations of PSQL files, see Where are the PSQL files installed? in Getting Started With PSQL.

You should update your CLASSPATH environment variable as follows:

SET CLASSPATH=.; file_path\PSQL\bin\psql.jar;

file_path\PSQL\SDK\JCL\Samples\PVideo\pvideoj.jar;

file_path\PSQL\SDK\JCL\Samples\PVideo;

where file_path equals the installation location of PSQL.

If you receive an error that a certain PSQL class file cannot be found, your user CLASSPATH variable in the Control Panel may be overriding the system CLASSPATH variable that contains the PSQL paths.

To verify your Windows setup (and correct if necessary):

The Video Store sample applications demonstrates some of the capabilities of the PSQL Java interface.

The following application windows displays:

The Java source files for the PSQL video store sample application are contained in a Java Archive file. You can extract these files to get a working example of the PSQL Java interface connecting to Btrieve tables.

The following procedure assumes that the JDK is installed and its BIN directory is in the path:

The source is extracted to the current directory and subdirectories below psql\sdk\jcl\samples\pvideo.

For default locations of PSQL files, see Where are the PSQL files installed? in Getting Started With PSQL.

For more information on Java Archive files, see http://java.sun.com/docs/books/tutorial/index.html.

The following resources are available to assist you in developing applications using the Java interface.

The javadocs that accompany the Java Class Library provide a reference for the classes and methods used in JCL-based applications.

You should now have a good conceptual knowledge of what is included in the PSQL Java interface and have a properly configured environment. The next chapter shows you how to use the Java interface to create database applications.