Database Configuration Guide

CHAPTER 1

Configuring Cloudscape Databases

This chapter describes how to configure your IBM Cloudscape database for use as a SilverMaster or deployment database with the Novell exteNd Application Server. It includes these sections:

For more information For the latest information on supported database versions, see the Novell exteNd Application Server Release Notes.

Setting up SilverMaster databases

To use a Cloudscape database as the SilverMaster database, you need to:

Install the Cloudscape software.
Create a Cloudscape SilverMaster database.

The sections that follow explain these steps.

Step 1: Install the Cloudscape software

To use Cloudscape databases with the Novell exteNd Application Server, you must:

Install the Cloudscape software yourself (it's available from the IBM Cloudscape Web site at www-3.ibm.com/software/data/cloudscape/).
Specify the location of these three Cloudscape JAR files in the AGCLASSPATH environment variable (in the .agprofile file on Linux):
```
  cloudscape.jar
  cloudutil.jar
  RmiJdbc.jar
```
On Linux, the application server install will ask for the location of these JARs so it can update the .agprofile file for you.

For information on editing AGCLASSPATH, see the chapter on data source configuration in the Administrator's Guide.

As with any SilverMaster or deployment database, you must be able to connect to the destination Cloudscape database from the machine that hosts the Novell exteNd Application Server.

Step 2: Create a Cloudscape SilverMaster database

You can create the Cloudscape database for SilverMaster in either of these ways:

Using the Cloudscape tools (see the Cloudscape documentation at www-3.ibm.com/software/data/cloudscape/)

Once your Cloudscape database is created, you can install the application server and point to that database as the SilverMaster (as described in Installing Novell exteNd).

If the Cloudscape database that you use already contains users (not the APP user), then the database must also contain a schema of the same name (see Cloudscape users, schema, and the application server).
When you install the application server

The application server install will ask for the JDBC URL of the Cloudscape database to use as SilverMaster. You can create the database at this time, by appending the string ;create=true to the URL. (This is an easy way to create an unsecured Cloudscape database.)

For more information on Cloudscape JDBC URLs, see Locating Cloudscape databases.

Setting up deployment databases

To set up a Cloudscape database as a deployment database, you need to:

Create the Cloudscape database.
Add the Cloudscape database or connection pool to the application server.

The following sections describe these steps.

Step 1: Create a Cloudscape deployment database

You can create the Cloudscape database in either of these ways:

Using the Cloudscape tools (see the Cloudscape documentation at www-3.ibm.com/software/data/cloudscape/)
When you add the database to the application server

In this case, you must specify the JDBC URL for the database. You can create the database at the same time that you add it, by appending the string ;create=true to the URL.

For more information on Cloudscape JDBC URLs, see Locating Cloudscape databases.

Step 2: Add the Cloudscape database or connection pool to the application server

You can add a Cloudscape database using either of the following:

The Add Database dialog from the SMC
The AddDatabase command of the SilverCmd command-line tool

The examples below show how to create a new database (with ;create=true on the JDBC URL) while adding it to the application server. You do not need ;create=true when you're adding an existing database. If the database already exists, this string is ignored.

Using the Add Database dialog Provide these values:

Database name
User name: APP
Password: password

By default, Cloudscape databases are created with no security. Use the APP/password combination whenever connecting to an unsecured database.
Database platform: IBM Cloudscape
JDBC URL: jdbc:cloudscape:databasepath/databasename;create=true

For example:
```
  jdbc:cloudscape:c:/mydb/Testdb;create=true
```

Using SilverCmd AddDatabase You can invoke SilverCmd AddDatabase like this:

  SilverCmd AddDatabase server[:port] -f file [options]

The following XML shows the contents of a file that you might specify using the -f parameter. This example creates and adds a database named EstoreDB and connects as the user APP.

  <DatabaseOptions isObject="true"> 
    <MainDatabase isObject="true"> 
    <ConnectionOptions isObject="true"> 
     <DatabaseName type="String">EStoreDB</DatabaseName> 
     <Username type="String">APP</Username> 
     <Password type="String">password</Password>
     <LDSKey type="String">CloudscapeEmbeddedDriver</LDSKey>
     <OtherDriver isObject="true"> 
      <JDBC_URLtype="String">jdbc:cloudscape:c:/mydb/Testdb;create=true
       </JDBC_URL> 
     </OtherDriver> 
    </ConnectionOptions> 
    </MainDatabase>
  </DatabaseOptions>

Adding connection pools Another way to access a Cloudscape database is to add a connection pool for it to the application server. For details on adding databases and connection pools, see the chapter on data source configuration in the Administrator's Guide.

Locating Cloudscape databases

Cloudscape JDBC URLs take this form:

  jdbc:cloudscape:dbname

The dbname parameter can be a fully qualified pathname, a relative pathname, or a database name. The application server uses the cloudscape.system.home system property to locate databases (unless they are fully qualified). By default, the application server sets cloudscape.system.home to the following directory:

  AppServerInstallDir\db

If the application server is unable to locate the database using the system property, it tries the current directory.

Cloudscape users, schema, and the application server

If the application server connects to the Cloudscape database as a specific user (not APP), it requires the database to contain a schema of the same name. For example, if you want to connect to a database as the user DBADMIN, then the database must contain a schema also called DBADMIN.

For more information on creating users and schemas, see the Cloudscape documentation (at www-3.ibm.com/software/data/cloudscape/).

Managing access to Cloudscape databases

Some versions of the Cloudscape DBMS are designed to support a single database connection. If the Cloudscape JARs are found on your AGCLASSPATH, the Cloudscape database will automatically start in-process with the application server using the single allowed connection.

Keeping the Cloudscape database from starting automatically If you do not want it to start, you can remove the Cloudscape JARs from AGCLASSPATH.

Running Cloudscape in a cluster server environment Cloudscape databases are not sharable between more than one process at a time and are not appropriate for a cluster server environment.

Connecting to Cloudscape from other tools When the application server has a database open, you must use a different JDBC driver and URL to connect to that database from a different source, such as a JDBC program or a Cloudscape tool. To use Cloudscape's ij, you would normally do the following:

  java COM.cloudscape.tools.ij 
  ij> connect 'jdbc:cloudscape:d:/MyDbs/MyDatabase';

But to connect while the application server is running, you would have to run it like this:

  java -Dij.driver=COM.cloudscape.core.RmiJdbcDriver COM.cloudscape.tools.ij 
  ij> connect 'jdbc:cloudscape:rmi:d:/MyDbs/MyDatabase';

In CloudView, before connecting to the database click on the Connection tab, and change the prefix field to jdbc:cloudscape:rmi://localhost:1099/. This automatically changes the driver to COM.cloudscape.core.RmiJdbcDriver.

Allowing access to Cloudscape from external applications When the Novell exteNd Application Server has a connection to a Cloudscape database, other applications are only able to access the database through Cloudscape's remote RMI/JDBC bridge via the application server's RMI/JDBC listener. The application server provides the following property (in the httpd.props file) to control the startup of the RMI/JDBC listener:

  http-server.com.sssw.db.cloudscape.cloudscapeDatabaseRMIJDBCListener=
  [true|false]

The following table describes the property settings:

Property Value	Description
true	Setting this value to true causes the application server to start the Cloudscape RMI/JDBC listener at server startup. Starting this listener makes it possible for other applications (such as the Novell exteNd Director EJB Wizard) to connect to the Cloudscape databases that the application server is also connecting to (or holding connections to) using Cloudscape's remote RMI/JDBC bridge driver.
false (default)	Setting this value to false prevents the application server from starting the Cloudscape RMI/JDBC listener at server startup. External applications (such as exteNd Director^TM) will not be able to connect to any Cloudscape database to which the application server is connected. If you do not need external access to Cloudscape, leave this flag set to false. When the Cloudscape RMI/JDBC listener is enabled, the application server is slower to shut down because it must do additional processing. When set to false, this flag prevents the slower than normal server shutdown.

Property Value

Description

true

Setting this value to true causes the application server to start the Cloudscape RMI/JDBC listener at server startup.

Starting this listener makes it possible for other applications (such as the Novell exteNd Director EJB Wizard) to connect to the Cloudscape databases that the application server is also connecting to (or holding connections to) using Cloudscape's remote RMI/JDBC bridge driver.

false (default)

Setting this value to false prevents the application server from starting the Cloudscape RMI/JDBC listener at server startup. External applications (such as exteNd Director^TM) will not be able to connect to any Cloudscape database to which the application server is connected.

If you do not need external access to Cloudscape, leave this flag set to false. When the Cloudscape RMI/JDBC listener is enabled, the application server is slower to shut down because it must do additional processing. When set to false, this flag prevents the slower than normal server shutdown.

Running multiple application servers on a single host If you want to run multiple instances of the Novell exteNd Application Server on one computer and run Cloudscape, you need to specify a different Cloudscape RMI/JDBC port number for each server in its httpd.props file (the default is port 1099):

  http-server.com.sssw.srv.cloudscape.RmiJdbcPort=number

Setting this line to a different port for each server avoids a port number conflict. For more information on setting other ports and properties for running multiple servers on a single host, see the chapter on running the server in the Administrator's Guide.