The Zen Java Classes are an interface to the MicroKernel Engine.
Java Class Library and MicroKernel Engine
The Zen 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.
Note Btrieve has been using the "file/record/field" terminology. However, in this section we use table, row and column instead when we describe classes that can be used in conjunction with databases that have Zen dictionaries.
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:
•Providing Btrieve application developers a set of abstractions.
•Ensuring ease of use.
•Hiding the platform-dependent byte-orders.
•Enabling developers to use all features of the Btrieve system.
•Ensuring that the performance of the MicroKernel Engine is not jeopardized.
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 Zen 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.
Database Concepts
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 Zen Java interface can operate at a high or low level depending on which classes you use.
Tightly-Coupled Databases
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.
Loosely-Coupled Databases
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:
1 Create a database dictionary for the loosely coupled database by using the Zen Control Center. In effect, the database is turned into a tightly coupled database before using the new API.
2 Create a new persistent dictionary and define tables, columns, and so on for each Btrieve file in an application program by using the new API. In this case, the database is turned programmatically into a tightly coupled database.
How to Set Up your Environment
This section contains information about proper configuration for use of the Zen Java interface.
The Zen Java interface supports JDK 1.4 and later.
CLASSPATH Environment Variable
The Zen SDK configuration needs the CLASSPATH variable to point to the Zen classes.
The sample CLASSPATH assumes that Zen was installed to file_path\Zen. The Java Class Library SDK is installed to file_path\Zen\SDK\JCL. For default locations of Zen files, see Where are the files installed? in Getting Started with Zen.
You can update CLASSPATH within a session as follows or make the change permanent through the Windows Control Panel in the steps below.
SET CLASSPATH=.; file_path\Zen\bin\psql.jar;
file_path\Zen\SDK\JCL\Samples\PVideo\pvideoj.jar;
file_path\Zen\SDK\JCL\Samples\PVideo;
where file_path equals the installation location of Zen.
Windows CLASSPATH
If you receive an error that a certain Zen class file cannot be found, your user CLASSPATH variable in the Control Panel may be overriding the system CLASSPATH variable that contains the Zen paths.
To verify your Windows setup (and correct if necessary):
1 Click Start, point to Settings, and then Control Panel.
2 Double-click System.
3 Select the Environment tab.
4 Your Zen paths are contained in the system variable. Under User Variables, see if CLASSPATH is present. If it is not, no action is required. If it is, prepend %CLASSPATH%; to your user variable.
Running the Video Store Java Sample Application
The Video Store sample applications demonstrates some of the capabilities of the Zen Java interface.
►To run the JCL SDK sample application
1 Open your Zen SDK Java Pvideo folder. Assuming it is located in the default location, this would be file_path\SDK\jcl\samples\Pvideo.
Figure 1 Zen Sample Video Application Main Window - Java
Viewing the Source of the Java Video Store Application
The Java source files for the Zen video store sample application are contained in a .jar file. You can extract these files to get a working example of the Zen Java interface connecting to Btrieve tables.
The following procedure assumes that the JDK is installed and its \bin directory is in the path.
►To unpack the Java source files
1 At a command prompt, enter:
cd \zen\sdk\jcl\samples\pvideo
2 Next enter the JAR command:
jar -xvf source.zip
The source is extracted to the current directory and subdirectories below zen\sdk\jcl\samples\pvideo.
