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.
- Install a JVM of 1.1.1 or Higher.*
- Set the PATH Environment Variable for the JVM.*
- Read the Release Notes.
- Set the CLOUDSCAPE_INSTALL Environment Variable.
- Set the Class Path.
- Set Path to Use the Tools and Startup Utilities (Windows or UNIX).*
- Browse the Cloudscape Documents.
- Bring up Cloudview Against a Sample Database.
- Start Programming with the Examples.
- Read and do the lessons in Learning Cloudscape: The Tutorial.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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
- 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.
|