
Getting Started with Cloudscape,
Page 3 of 8
|

|

[top]  [prev]
  [next]
Documentation Top
Global Index
Release Notes |
Getting Started Road Map
Heres 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.
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 Whats New in Version 3.0? and Whats 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 dont miss it!
If you havent 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
Heres 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 Cloudscapes sysinfo tool to check the versions of Cloudscape products.
java COM.cloudscape.tools.sysinfo
The following excerpt from near the end of sysinfos 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 Developers Guide.
-
LDAP or NIS+ user authentication
You need additional libraries. For specific library information, see the Cloudscape Developers 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.
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.
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 (dont 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.
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.
|