Getting Started with Cloudscape
Page 3 of 6

Getting Started Road Map

Here's a road map of tasks to perform for getting started.

Users on Windows platforms who simply want to start utilities from the Start menu can skip some steps, because the Cloudview Windows installer automatically installs a JRE, which is a runtime version of a JVM. Steps which are optional for Windows Start menu users are indicated with an asterisk (*). Users who want to develop applications should not skip any steps.

  1. Install a JVM of 1.1.1 or Higher.*
  2. Set the PATH Environment Variable for the JVM.*
  3. Read the Release Notes.
  4. Set the CLOUDSCAPE_INSTALL Environment Variable.
  5. Set the Class Path.
  6. Set Path to Use the Tools and Startup Utilities (Windows or UNIX).*
  7. Browse the Cloudscape Documents.
  8. Bring up Cloudview Against a Sample Database.
  9. Start Programming with the Examples.
  10. Read and do the lessons in Learning Cloudscape: The Tutorial.
  11. If you are a previous customer, read What's New in Version 3.6?.

Install a JVM of 1.1.1 or Higher

Before you use the Cloudscape software, your system must contain a JDK or a JVM. (The Windows installer installs a JRE, a runtime version of a JDK, and so you can skip this step if you like.) The following list shows the JDK version required by the various Cloudscape products:

  • Cloudscape engine and ij (an SQL scripting tool)

    JDK 1.1.1 or greater

  • Cloudscape using disk encryption, JDBC 2.0 and its extensions, or JTA:

    JDK 1.2 or greater

  • Cloudview (a graphical user interface)

    JDK 1.2 or greater

    It is possible to use Cloudview with a 1.1 JDK (1.1.6 or higher). To do so, you must download an extra library (swingall.jar) from the Cloudscape Web site and place it in the class path. You can download this library from http://www.cloudscape.com/support/Downloads/.

    For complete information about Cloudview and platforms, see the release notes.

  • RmiJdbc server framework

    JDK 1.1 or greater

  • Cloudconnector server framework

    JDK 1.1 or greater (to see a list of supported platforms, go to the Weblogic web site)

See http://www.javasoft.com/products/jdk/1.1/index.html if you need to install a JDK. Be sure to follow the full installation instructions, which require that you update the PATH and CLASSPATH environment variables.

NOTE: For a list of validated JVMs, see the Cloudscape web site.

Set the PATH Environment Variable for the JVM

NOTE: This instruction repeats one of the basic steps in installing a JVM. We are repeating it here to make sure you don't miss it!

If you haven't done so already, set your PATH environment variable so that the JVM and Java applications run correctly.

Add the bin subdirectory of the JDK directory to the beginning of the path. For example, if the directory is C:\JDK1.1.8, add C:\JDK1.1.8\bin to the beginning of the path.

The PATH variable enables your operating system to find the appropriate executables from any directory. If you have more than one JDK installed, the JDK you wish to use must appear before any of the others in the PATH variable.

Testing Your Path

Here's a test you can run to make sure you set the path correctly.

In a command window, try the following command:

java

If the path is set correctly, you will see a printout telling you how to use the java command.

Read the Release Notes

Read the Cloudscape release notes for late-breaking installation information. The release notes are inside the cloudscape base directory, the directory in which you installed the software.

Set the CLOUDSCAPE_INSTALL Environment Variable

The installation program asked you to choose a base directory; we recommend that you name it cloudscape_3.6. This document refers to that directory as the cloudscape base directory.

If your operating system supports it, create an environment variable called CLOUDSCAPE_INSTALL. On some operating systems, the installer may have already created this variable for you. Set the value of this variable to the path of the cloudscape base directory.

Set the Class Path

The class path tells the JVM and other Java applications where to find class libraries.

There are two ways to set the class path:

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

In most development environments, it works best to set the environment variable temporarily with a script. Run such a script every time you open a new command window.

For instructions on how to set the environment variable permanently (on the system level), see Setting the CLASSPATH Environment Variable at the System Level.

Regardless of which method you choose, you need to know which libraries to include:

Cloudscape Terminology

The Cloudscape documentation uses some specialized terms. Here are some definitions that will help you understand Cloudscape:

environment
How your application interacts with Cloudscape. Sometimes referred to as a framework. The two environments are embedded environment and client/server environment.
embedded environment
When an application starts up an instance of Cloudscape within its JVM, the application is said to run in an embedded environment. In this environment, only a single application can access a database at one time, and no network access occurs.
client/server environment
When multiple applications connect to Cloudscape over the network, they are said to run in a client/server environment. Cloudscape runs embedded in a server framework that allows multiple network connections. (The framework itself starts up an instance of Cloudscape and, strictly speaking, it is running in an embedded environment; the client applications, however, are not.)

NOTE: Most users who are just getting started with Cloudscape work with it in an embedded environment.

Cloudscape Libraries

Add the appropriate items to class path. Paths shown are relative to the cloudscape base directory ($CLOUDSCAPE_INSTALL or %CLOUDSCAPE_INSTALL%):

  • the primary Cloudscape library (lib/cloudscape.jar or lib/cloudsync.jar).

    The primary Cloudscape library is the library that provides the database engine itself; it is either cloudscape.jar or cloudsync.jar. You always need this library for embedded environments. For client/server environments, you need this library on the server only.

    See Table 1, "The Database Engine Libraries" for details on when to use a particular library. Be sure to have only one of the libraries in your class path.

  • the Cloudscape client library (lib/client.jar)

    Only for JDBC client applications in a client/server environment. This library is not needed for non-JDBC clients such as servlet clients.

  • the server framework libraries

    The server libraries on the servers, the client libraries on the clients. See Table 2, "Libraries for Different Connectivity Options".

  • the tools library (/lib/tools.jar) if you want to use the Cloudscape tools

    For embedded environments, you need this library in the class path to use the tools. For a client/server environment, you need this library on the client only.

  • the sample database and application libraries (demo/programs/tours)

    For embedded environments; for a client/server environment, on both the client and the server.

  • the current directory (.)

NOTE: If you want to work in a client/server environment and are just getting started, include all the necessary client and server libraries in your class path to make it easier to get started.

A Note on Setting Class Path

Cloudscape provides scripts to help you get started setting class path in the /bin subdirectories in each of the frameworks directories in %CLOUDSCAPE_INSTALL%/frameworks. These scripts have names that reflect their environment; for example, setEmbeddedCloudscapeCP (in %CLOUDSCAPE_INSTALL%/frameworks/embedded/bin) helps you set class path for an embedded environment. These scripts come in two flavors: one for Windows environment (this file ends with .bat) and one for UNIX environments (this file ends with .ksh). For users working in those environments, copying the commands in this file will help you get started setting the class path.

Table 1 The Database Engine Libraries

Product

Use

Library Name

Path from the cloudscape base directory

Cloudscape

For non-synchronization systems

cloudscape.jar

lib/cloudscape.jar

Cloudsync

For target or source databases in a synchronized system.

cloudsync.jar

lib/cloudsync.jar

NOTE: cloudscape.jar supports only non-synchronization databases.

Table 2 Libraries for Different Connectivity Options

Server Framework

Server Library

Client Library

RmiJdbc Server

(customized framework provided with Cloudscape)

frameworks/RmiJdbc/classes/RmiJdbc.jar

frameworks/RmiJdbc/classes/RmiJdbc.jar

Cloudconnector

frameworks/cloudconnect/classes/

frameworks/cloudconnect/lib/weblogicaux.jar

frameworks/cloudconnect/license

frameworks/cloudconnect/classes/

frameworks/cloudconnect/lib/weblogicaux.jar

frameworks/cloudconnect/license

About the Versions of Cloudscape Libraries

The Cloudscape libraries must be "in version" with one another. For example, you cannot use cloudscape.jar version 3.5.0 and tools.jar version 3.5.1. If your versions do not match, you may get unexplained and confusing errors in your programs.

You can use Cloudscape's sysinfo tool to check the versions of Cloudscape products.

java COM.cloudscape.tools.sysinfo

The following excerpt from near the end of sysinfo's output indicates a problem, because there are two different version numbers:

-----------------Cloudscape Info-------------------
[d:\cloudscape\cloudscape.jar] version 3.5.0 #8648
[d:\cloudscape\tools.jar] version 3.5.1 #8688
[License Type] Development. Valid.
---------------------------------------------

Additional Libraries

Some special Cloudscape features require that you install additional libraries and place them in your class path:

  • Disk encryption

    You must install the 1.2.1 or higher version of the standard JCE package. For more information, see the Cloudscape Developer's Guide.

  • LDAP or NIS+ user authentication

    You need additional libraries. For specific library information, see the Cloudscape Developer's Guide.

  • JTA

    You need additional libraries. For specific library information, see the Cloudscape Reference Manual.

  • JDBC 2.0 Extensions

    You need additional libraries. For specific library information, see the Cloudscape Reference Manual.

  • Cloudview

    If you want to use a pre-1.2 JDK (JDK 1.1.6 or higher), you will need swingall.jar (see Install a JVM of 1.1.1 or Higher). Put this library ahead of any Cloudconnector libraries in your class path.

  • Localized Messages

    For localized error or user interface messages, you need additional libraries. For information, see the Cloudscape Developer's Guide.

Setting the CLASSPATH Environment Variable at the System Level

Optionally, you can set a persistent CLASSPATH Environment Variable at the system level. Depending on your operating system, the procedure for setting the system CLASSPATH varies slightly.

Windows NT

On Windows NT, set the CLASSPATH environment variable from the System Control Panel.

  1. Start the System tool from the Control Panel, select the Environment tab, and select the CLASSPATH user variable. If one does not already exist, create a new user variable called CLASSPATH.
  2. Add the appropriate text to the beginning of the CLASSPATH user variable definition.

    For example:

    %CLOUDSCAPE_INSTALL%\lib\cloudscape.jar;
    %CLOUDSCAPE_INSTALL%\lib\tools.jar;
    %CLOUDSCAPE_INSTALL%\demo\programs\tours;.;

    assuming that you are not deploying a source synchronization database.

  3. Click Set, click Apply, and close the System Control Panel.

Windows 2000

On Windows 2000, set the CLASSPATH environment variable from the System Control Panel.

  1. Start the System tool from the Control Panel, and select the Advanced tab, and click the Environment Variables button. If the CLASSPATH user variable exists, highlight it and click Edit. If one does not already exist, click New to define a user variable called CLASSPATH.
  2. Add the appropriate text to the beginning of the CLASSPATH user variable definition.

    For example:

    %CLOUDSCAPE_INSTALL%\lib\cloudscape.jar;
    %CLOUDSCAPE_INSTALL%\lib\tools.jar;
    %CLOUDSCAPE_INSTALL%\demo\programs\tours;.;

    assuming that you are not deploying a source synchronization database.

  3. Save changes and close the System Control Panel.

Windows 95 or Windows 98

On Windows 95 or Windows 98, you add or alter the CLASSPATH setting by adding or altering the text in your autoexec.bat file.

If the variable is already set, add the following text to the beginning of the definition for the variable:

%CLOUDSCAPE_INSTALL%\lib\cloudscape.jar;
%CLOUDSCAPE_INSTALL%\lib\tools.jar;
%CLOUDSCAPE_INSTALL%\demo\programs\tours;.;

assuming that you are not deploying a source or target synchronization database.

If the variable is not already set, add the following text to the file:

SET CLASSPATH=%CLOUDSCAPE_INSTALL%\lib\cloudscape.jar;
%CLOUDSCAPE_INSTALL%\lib\tools.jar;
%CLOUDSCAPE_INSTALL%\demo\programs\tours;.;

When setting environment variables such as CLASSPATH in Windows 95, users sometimes get a message like "Not enough environment space."

To enlarge the environment space, set the following command in the CONFIG.SYS file:

    SHELL=C:\Windows\COMMAND.COM /P /E:4096

COMMAND.COM is found in the Windows installation direction (usually C:\windows).

  • /P means to leave COMMAND.COM running between commands (don't exit when the user issues the dir command).
  • /E: signifies how much environment space to reserve for each process. 4K is usually enough.

Restart the machine.

UNIX Systems

On UNIX systems, alter the value of the CLASSPATH setting or create it if it does not exist in your .login or .profile file.

  1. On Solaris or Linux for ksh/sh:

    CLASSPATH=${CLOUDSCAPE_INSTALL}/lib/cloudscape.jar:
    ${CLOUDSCAPE_INSTALL}/lib/tools.jar:
    ${CLOUDSCAPE_INSTALL}/demo/programs/tours:
    .:${CLASSPATH}

    export CLASSPATH

  2. On Solaris or Linux for csh, and on HP and AIX:

    setenv CLASSPATH ${CLOUDSCAPE_INSTALL}/lib/cloudscape.jar:
    ${CLOUDSCAPE_INSTALL}/lib/tools.jar:
    ${CLOUDSCAPE_INSTALL}/demo/programs/tours:
    .:${CLASSPATH}

NOTE: You can find information for other platforms at www.cloudscape.com/support/TechInfo.

Testing Your Class Path

Cloudscape provides a tool to help you test your class path for your environment. You run the utility like this:

java COM.cloudscape.tools.sysinfo -cp arguments

Provide arguments as follows:

  • the environment (required, choose one of the following):
    • embedded
    • RmiClient
    • RmiServer
    • CloudconnectorClient
    • CloudconnectorServer
  • tools (optional)

    looks for the libraries for using the Cloudscape tools

  • sampleApp (optional)

    looks for the libraries for using the sample application

  • sync (optional)

    looks for the libraries for using Cloudscape synchronization (needed only on the server if it is a client/server environment)

  • anyClass.class (optional)

    looks for any class that you specify

The utility provides a message indicating success or failure and lists any missing libraries.

For example, to test an embedded environment, using the tools and the sample application:

java COM.cloudscape.tools.sysinfo -cp embedded tools sampleApp

To test an RmiJdbc client environment using the tools and to test for the class CloudscapeSimpleApp:

java COM.cloudscape.tools.sysinfo -cp RmiClient tools CloudscapeSimpleApp.class

Set Path to Use the Tools and Startup Utilities (Windows or UNIX)

The /bin subdirectories in environment-specific directories in the frameworks directory contain scripts for running some of the Cloudscape tools and utilities.

NOTE: These scripts serve as examples to help users on all platforms get started with these tools and utilities. However, they may require modification in order to run properly even on Windows or UNIX platforms.

  • /%CLOUDSCAPE_INSTALL%/frameworks/embedded/bin contains scripts for working in an embedded environment.
  • /%CLOUDSCAPE_INSTALL%/frameworks/RmiJdbc/bin contains scripts for working in a client/server environment using the simple framework RmiJdbc.
  • /%CLOUDSCAPE_INSTALL%/frameworks/cloudconnect/bin contains scripts for working in a client/server environment using Cloudconnector. (Directory is present if you have installed Cloudconnector.)

On a Windows or UNIX platform, add the appropriate /bin directory to your path to use shortened commands to start the Cloudscape tools.

Users on UNIX platforms need to turn on the execute bit for these files. For example:

chmod +x fileName

If You Had Problems Installing, Send Information to Cloudscape

If you encountered any problem using the installation program, make a careful note of any error messages. Then run the utility COM.cloudscape.tools.sysinfo to display system and product configuration.

java COM.cloudscape.tools.sysinfo

Send mail including the error message and output of sysinfo to support@cloudscape.com.

Cloudscape Documents

The Cloudscape installation provides you with a complete documentation set. Read about the documentation in Using the Cloudscape Documentation.