Cloudscape Basics and the Sample Database
Page 2 of 6

Getting Acquainted with Class Path

When you request that a JVM (Java Virtual Machine) execute a Java program, it searches through the class path, a list of directories and jar or zip files that tell the JVM where to look for the program. If your program (or any classes used by the program) is not in the class path, the program does not work. You will get a message like the following:

Can't find class YourProgram

This section covers the following topics:

And the following task:

Setting the Variable vs. Using the Runtime Option

You will need to set your class path in order to run JBMSTours.CreateToursDB, the first application in the JBMSTours package.

There are two ways to set the class path:

  • Set the operating system's CLASSPATH environment variable, either permanently or temporarily.
  • Set the class path with the runtime option (specifying the class path at the time you start your Java application and the JVM).

In this tutorial, you will set the environment variable temporarily with a script. You will need to run this script every time you open a new command window.

How to Specify the Location of Files in the Class Path

The JVM (compiler or interpreter) needs to know the path (operating system-specific instructions about location) of every class file needed by your application. Class files can live in:

  • Directories

    Class files can live in directories that indicate the package name. For example, the class files in the package JBMSTours live in a directory called -JBMSTours. Class files in the package COM.cloudscape.types would live in the directory types, which would live in the directory cloudscape, which would live in the directory COM.

    When indicating the path to class files that live in a directory, do not include the name of any of the directories that constitute the package name. Instead, include the directory one level above the package name directory. For example, if the directory JBMSTours lived on your C drive in a directory called tours, you would add "c:\Tours" to the class path.

  • jar or zip files

    Class files can also live in jar or zip files. Class files in jar or zip files live inside directories that have the same name as the package name within the jar or zip files. The jar or zip files can live in any directory.

    When indicating the path to a class file that lives in a jar or zip file, include the path to the file, including the file name itself. For example, for a jar file called cloudscape.jar that lives in the cloudscape\lib directory of your C drive, you would add "c:\cloudscape\lib\cloudscape.jar" to the class path.

  • For JDK 1.1, JDK class files

    All Java programs need access to JDK class files. For JDKs prior to 1.2, you sometimes need to include the JDK class files in your class path.

    Pre-JDK 1.2 class files are located in classes.zip in the /lib subdirectory of the directory where you installed the JDK. For example:

    c:\jdk1.1.5\lib\classes.zip

    The pre-JDK1.2 JVM always includes this zip file in the class path unless you use the runtime override option. We won't use that method, so adding this zip file is optional.

    The JDK1.2 JVM uses a different library (rt.jar), and it automatically includes this library in the class path. Do not add it to the class path.

NOTE: If you operating system supports it, it is a good idea to use JDK 1.2.x for this tutorial.

The CLOUDSCAPE_INSTALL Environment Variable

Some versions of the installer automatically create an environment variable called CLOUDSCAPE_INSTALL and set its value to the cloudscape base directory, the directory in which you installed the product. If your version of the installer did not set this environment variable, do it now.

For example, if you installed the product in c:\cloudscape, set CLOUDSCAPE_INSTALL to c:\cloudscape.

What to Include in the Class Path for this Tutorial

This section describes what you need to include in the class path in order to do this tutorial correctly.

For some quick help, jump to Determine Your Class Path.

  • Current directory

    Indicated with a period (.).

  • The Cloudscape jar files

    In this tutorial you will be working with Cloudscape applications, which use the Cloudscape classes. These class files are located in jar files installed in the /lib subdirectory of CLOUDSCAPE_INSTALL.

    Include cloudscape.jar and tools.jar.

    For example:

    %CLOUDSCAPE_INSTALL%\lib\cloudscape.jar

    %CLOUDSCAPE_INSTALL%\lib\tools.jar

NOTE: If you are using a pre-1.2 JDK, you also need to download Cloudscape's swingall.jar library and add it to your class path. This library is available for download from http://www.cloudscape.com/support/Downloads/. You need to use JDK 1.1.6 or higher.

  • Your application (JBMSTours)

    In this tutorial, your application is the JBMSTours application, and you must include the path to the application in your class path. The JBMSTours application resides in the demo/programs/tours subdirectory of CLOUDSCAPE_INSTALL. For example:

    %CLOUDSCAPE_INSTALL%\demo\programs\tours

  • license.jar, if you are using a pre-3.5 evaluation copy of Cloudscape

    For example:

    %CLOUDSCAPE_INSTALL%\lib\license.jar

Figure 2-1 Setting your class path. (JDK library not shown.) In order for Cloudscape applications to work, your class path must include the Cloudscape libraries. The sample application requires the JBMSTours library, which is in /demo/programs/tours.

Path Separators

You specify the list of paths as a single string. You must use a separator between paths; the character used as the separator depends on your operating system.

  • DOS and Windows platforms:

    ; (semicolon)

  • UNIX platforms:

    : (colon)

Determine Your Class Path

Take the time now to determine the exact text of your class path. To review, it should include:

  • path to JDK (optional)
  • path to primary Cloudscape library and /lib/tools.jar
  • path to demo/programs/tours
  • current directory
  • license.jar, if you are using the evaluation version of Cloudscape

The following is an example class path on a Windows system, where the cloudscape base directory is c:\cloudscape:

.;c:\JDK\lib\classes.zip;
%CLOUDSCAPE_INSTALL%\lib\cloudscape.jar;
%CLOUDSCAPE_INSTALL%\lib\tools.jar;
%CLOUDSCAPE_INSTALL%\demo\programs\tours;%classpath%

The following is an example class path on a Windows system, where the cloudscape base directory is C:\cloudscape and the user is working with a pre-3.5 evaluation version of Cloudscape:

.;c:\JDK\lib\classes.zip;
%CLOUDSCAPE_INSTALL%\lib\cloudscape.jar;
%CLOUDSCAPE_INSTALL%\lib\tools.jar;
%CLOUDSCAPE_INSTALL%\demo\programs\tours;
%CLOUDSCAPE_INSTALL%\lib\license.jar;%classpath%

The following is an example class path on a UNIX system:

.:/JDK/classes.zip:
$CLOUDSCAPE_INSTALL/lib/cloudscape.jar:
$CLOUDSCAPE_INSTALL/lib/tools.jar:
$CLOUDSCAPE_INSTALL/demo/programs/tours:$CLASSPATH

The rest of this tutorial will refer to your class path as yourClassPath. You will be setting that in a script (see Customize Your setclasspath Script).