Getting Started with Cloudscape,
Page 3 of 8


[top]
[prev]
[next]
Documentation Top
Global Index
Release Notes

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 it automatically installs a JRE, which is a runtime version of a JVM. Those steps 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.0?” and “What’s New in the Version 3.0 Documentation?”

Install a JVM of 1.1.1 or Higher

Before you use the Cloudscape software, you need to install 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

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.

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.7, add C:\JDK1.1.7\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. 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 have 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. You can set the default class path by adding a CLASSPATH environment variable if you do not already have one and then setting its value to the path to the Cloudscape libraries.

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, “Primary Cloudscape Libraries (put only one in the class path)” for details on when to use a particular library. Be sure to have only one of the libraries in your class path.
  • the license library (lib/license.jar)
    For users of the thirty-day evaluation copy only. You do not need this library if you have purchased a Cloudscape product. If you have the thirty-day evaluation version of Cloudscape but neglect to add license.jar to your class path, you will get an error.
  • the client Cloudscape 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 get started setting 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. Note that you may need to add the license.jar file because this file does not appear in the scripts.

Table 1 Primary Cloudscape Libraries (put only one in the class path)
Product Use Library Name Path from the cloudscape base directory

Cloudscape

For non-synchronization systems, or for target databases in a synchronized system.

cloudscape.jar

lib/cloudscape.jar

Cloudsync

For source databases in a synchronized system. Also works for target databases, which is convenient when you are developing applications.

cloudsync.jar

lib/cloudsync.jar

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.0.0 and tools.jar version 3.0.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.0.0 #8648
[d:\cloudscape\tools.jar] version 3.0.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 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.

Setting CLASSPATH on Windows NT

On Windows NT, set the CLASSPATH environment variable with 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.

Setting CLASSPATH on 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 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.

Setting CLASSPATH on 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.

  • 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

  • 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
  • syncSource (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 the missing libraries if there are any.

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.

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 installhelp@cloudscape.com.

Cloudscape Documents

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

[top]
[prev]
[next]


Cloudscape Version 3.0
For technical support, go to: www.cloudscape.com and click Support.
Copyright © 1998 and 1999 Cloudscape, Inc. All rights reserved.