The Locomotive Installation Guide

Hello, and thank you for considering the Locomotive Application Server. In this guide, we're going to lead you through the steps necessary to get your Locomotive up and running as quickly as possible. We'll give a quick overview of the whole web site system, from the web server to the Locomotive to the database, so that you know what you're doing when you follow each step.
 

Table of Contents

Steps for Installing The Locomotive

Creating the Locomotive Directory

Setting up the Appropriate Environment Variables

Configuring and Installing the Locolink Tunnel

Customizing the Locomotive Configuration File, loco.conf

Installing Tables and Stored Procedures in the Database

Starting and Stopping the Locomotive

Setting up Your CyberSource Environment

Using Cloudscape With the Locomotive

Appendix: Compatible Drivers

The Locomotive is a single program that is written entirely in Java. It sits between a web server and a database server and communicates with both. Once you start running a Locomotive, it runs forever until you shut it down.

When a programmer writes new modules for the Locomotive, he or she does not need to modify its source code, or even read it. He or she only needs to follow the API to develop working modules for the Locomotive. That programmer ought to know HTML, the Java programming language, the SQL query language for databases, and the JDBC database API for Java. We have included a short list of books we recommend for teaching these subjects, in Appendix A of the 'Locomotive Developer's Guide'. In addition, the programmer may want to learn a language called "Steam", which can be embedded within HTML documents to allow dynamic manipulation of content within those documents. (We call HTML documents that contain embedded Steam commands "HTML templates"). We have included a manual called "The Steam Language: Demystified" in the Locomotive distribution.

Here are the components that are necessary before programmers can start developing and testing their modules on the Locomotive:

1. You must have a Java development environment. The Locomotive works well with both JDK 1.1 and 1.2, available for downloading from Sun's Java site, or from Blackdown.org's Linux Java site. As far as we know, nobody has yet tested the Locomotive on JDK 1.3, but it should work.
2. If you want to run Java Servlets that use a database, then you must either be running a relational database, such as Oracle, Informix, MySQL, or Solid; or you must have a copy of the Cloudscape embeddable Database. Please see Our Cloudscape documentation for more information. If you're only testing/running servlets that don't use a database, then you do not need to set up a database. The Locomotive also uses the database to store session information, so if your servlets need to store session data, then you need to set up a database.
3. If you're using a separate database, you must have a JDBC database "driver", which is a Java class which communicates with the database. We've had good experience with the Informix ODBC driver (see Appendix A). Note that the Java Runtime Environment (JRE) has an internal JDBC-ODBC bridge which allows you to use any ODBC driver, but this requires you to do some extra setting up. Also, this may affect your performance. Cloudscape comes with its own JDBC drivers.
4. You may want to run a third-party web server. The Locomotive now has a built-in all-Java web server that is easy to set up and use, or you can connect a third-party web server to the Locomotive via either a CGI binary tunnel program or a tunnel web server module. We have found that Apache 1.3 or Netscape FastTrack 3.01 are reliable, stable web servers that work well with the Locomotive. (Note: we've had problems with FastTrack 2.0.) If you have would like to use the CGI tunnel, you must make sure your CGI directory is activated in your web server. If you would like to use the Apache or NSAPI tunnel, you need to install the shared objects and edit the necessary config files.
5. If you are installing the Locomotive on Windows, you need to first download and install the Cygnus Cygwin tools. This will give you the environment you need for running Locomotive on Windows. It's open-source software as well, so you don't need to buy it, just download it and install it. If you only wish to run the Locomotive, you only need the Cygwin user package (only about 3 megs). If you want to be able to modify the Locomotive's source code and re-compile it, then you'll need the Cygwin full developer package, which is a large download (about 14 megs!), but comes with quite a bit of developer software, including the GNU C compiler (GCC) for Windows. It's big, but it's great.

6. You may want to have a C compiler, for setting up your own locolink CGI tunnel, or for compiling one of the tunnel modules. The GCC compiler, from the Free Software Foundation, is available to download via HTTP or FTP. This compiler is free, and has been ported to most platforms. If you've downloaded and installed the Cygnus full developer package, then you already have GCC. If you're using the Locomotive's Embedded Web Server, then you do not need to compile nor use a tunnel binary.
7. If you wish to use the Watcher facility for monitoring the Locomotives on your web site, or if you want to use the script "parser_events.pl" to gather statistics on the usage of your web site, you need to have PERL installed on your system. For more information on PERL you can visit www.perl.com.

If you have finished all of these steps, then you're ready to install the Locomotive.

For those who are using the Cloudscape embedded database, you may want to skip down to the Cloudscape installation section, which will show you how to install Cloudscape for use with the Locomotive. Again, if you are installing the Locomotive on Windows, you'll need to install the Cygnus Cygwin tools before you begin this installation (see the System Requirements section above for more info). In general, here is what you need to do to install the Locomotive:

1. The Locomotive home directory must be created with the necessary directories and files.
2. The environment variables must be configured appropriately.
3. If you are using a third-party web server, then either the locolink CGI program or the locolink tunnel module must be installed and configured to reflect the IP address and port for each Locomotive server that will be running.
4. The Locomotive configuration file, loco.conf, must be changed to fit your system.
5. The tables and stored procedures required for Locomotive operation must be installed in the database.
6. The various scripts necessary for Locomotive maintenance and automation must be set up.
7. You may want to copy or logically link the images directory to someplace in your web server's document root, too.

The first thing you need to do is decide where you want to store the Locomotive distribution on your disk. We recommend /usr/local/loco/. The command to expand your Locomotive distribution file is:

% cd /usr/local; gzip -dc locomotive_4.2.0rc1.tar.gz | tar -xvf -

This command will create a number of directories within the directory /usr/local/locomotive:

bin -- Contains the programs and scripts which start and stop the Locomotive, as well as automation and notification scripts. The stoploco and locolink native-code programs are in architecture-specific directories, such as windows, solaris_sparc, linux, and freebsd. There is now a new stoploco shell script that runs an all-Java stoploco program. It seems to run okay on UNIX operating systems, but may not run right under Windows.

config -- Contains the main configuration files like loco.conf and hrt.conf files, which are required to run the Locomotive.

localconfig -- Contains custom configuration files for when you want to set up multiple instances of the Locomotive, each with different configuration settings.

db -- Contains the database initialization files and schema files that create the database tables needed by the Locomotive, as well as the SQL procedures required for operating the Locomotive.

docs -- Contains the various documentation files for the Locomotive, including this document (The Locomotive Installation Guide), the Steam Manual, the Developer's Guide, and the Administrator's Guide. This directory is not necessary for the Locomotive to operate, and can be moved anywhere you like.

images -- Contains the images that the documents and sample modules use. You probably should copy (or symlink) this directory to someplace within your web server's document root.

lib -- Contains the Locomotive's Java shared objects and libraries (in files ending with .jar or .zip), and the Locomotive's native code shared objects (in files ending with .so or .dll, if any). The Java shared object .jar files are compiled Java classes that are stored in a Java ARchive (JAR) format file, and when you run startloco, these .jar files will automatically be added to your CLASSPATH environment variable for you (you do not need to add them to your CLASSPATH before running the startloco script). For the native code shared objects to work properly, such as the NSAPI locolink Tunnel, the path to this directory must be contained within the shell environment variable LD_LIBRARY_PATH. Another option is to move them to a directory already within the current LD_LIBRARY_PATH.

logs -- Contains the log files that record the activity of the Locomotive. The Locomotive keeps two main log files: the Events Log, which records statistics each time a page is viewed; and the Server Log, which records errors and server statistics, such as memory usage. The names of these files can be configured in the loco.conf file.

servlet -- Containts administrator-installed servlets. When you install servlets into the Locomotive, you should put the servlet's class files in this directory.

src -- Contains all of the Java source code for the Locomotive, the Bean Directory, the Locomotive Embedded Web Server, the C source code for the locolink CGI program and web server tunnel modules, and the java source for the example servlets and handlers.

templates -- Contains all STEAM templates that are converted into HTML and sent back to the web server. (STEAM templates are simply HTML documents with embedded Steam commands.) This directory may or may not be different from the document root of the web server. The difference is that this directory contains STEAM templates, whereas the web server's document root directory contains real HTML documents and other multimedia content. You may wish to make both of them the same directory, to better integrate static content and images with the HTML templates used to generate dynamic content. However, you may wish to separate them if you have different machines running Locomotives, but only one machine running a web server, because you need a templates directory on each Locomotive machine, but a web document root only on the web server machine.

upload -- This is the directory that any files uploaded via multipart forms will be saved. The name of the directory must be specified in the loco.conf file. Uploaded files are saved with the time of upload in milliseconds followed by the original file name. Note that these files can be moved and renamed from within your Locomotive module. See the Multipart Handler class example for more detail on how to do this.

As noted above, each of these directories, with the exception of the docs and src directories, must exist for the Locomotive to operate properly. If none of your modules allow users to upload data to your web site, then you do not need the upload directory.

% export LOCO_HOME=/usr/local/locomotive

And, remember to add to your CLASSPATH any directories or archives containing Java classes that are necessary for your database drivers.

You may also want to add the Locomotive's bin directory to your PATH environment variable, so that you can execute the Locomotive's scripts and executables without having to type their full pathnames:

% export PATH=$PATH:$LOCO_HOME/bin

The Locomotive implements version 2.1 of the Servlet API. The Servlet 2.1 classes are available, and are currenltly included in the latest distribution of the Locomotive.

First, check to make sure you have the classes- they're in a file at LOCO_HOME/lib/servlet-2.1.0.jar. If you have this file, then you're all set. It is automatically added to your CLASSPATH environment variable when you run the startloco shell script.

If you need to download the Servlet 2.1 classes, you can get them from Servlet 2.1 Specification Page.

Once you have the Servlet 2.1 package downloaded, you'll have to unpack with the following command:

% uncompress servlet2_1-api-sol.tar.Z; tar xvf servlet2_1-api-sol.tar

After that, you'll want to take the jar file you find in the root directory and put it in the $LOCO_HOME/lib directory so that it will be used whenever you run the startloco shell script.

The Locolink Tunnel is a program that receives requests from a third-party web server (such as the Apache web server, or one of Netscape's web servers) and passes those requests on to one or more Locomotives. Presently, there are three incarnations of the tunnel: an NSAPI module, an Apache module, and a CGI executable, all written in C. Note that if you're just going to use the Locomotive Embedded Web Server that comes with the Locomotive, you do not need to configure a Locolink Tunnel, but you need to configure the Embedded Web Server instead. To learn more about each of the Locolink Tunnels, see the Locolink Tunnel Documentation.

Installing the required Locomotive schema depends on the type of database you'd like to use, but roughly requires the following:

1. Creating a loco database user
2. Creating the necessary tablespaces/dbspaces to hold the tables
3. Creating the core Locomotive tables and procedures
4. Inserting the Locomotive Admin user into the user table
5. Adding the schema of any sample applications you'd like to use

Each of the previous steps is slightly different for each database; Below are links to instructions for each of the databases we currently support:

Oracle
Informix
Solid
MySQL
Cloudscape

Before you can install any Locomotive table schema, you should create a database user for the Locomotive. You can do this by starting SQL/PLUS as the database manager and using the following lines:

SQL> CREATE user loco IDENTIFIED by loco_pw;
SQL> GRANT CONNECT, RESOURCE to loco;
SQL> GRANT CREATE SESSION to loco;

If you prefer, you can run the script db/oracle/loco_create_user.sql, which executes the commands listed above.

Once you have the user created, you can reconnect to the database as that user using:

SQL> connect loco/loco_pw;

Now, you need to create the tablespaces the Locomotive tables will reside in. An example script for creating tablespaces can be found in db/oracle/loco_tablespaces.sql. You'll probably have to alter a the lines that contain paths to the files that hold the new tablespaces. Once your done editing the script, you can run it with the following command:

SQL> start /usr/local/locomotive/db/oracle/loco_tablespaces.sql;

If /usr/local/locomotive is where you've installed the Locomotive. Now, you have to load the necessary tables and sequences. Sample scripts for doing this can be found at db/oracle/loco_user.sql and db/oracle/loco_session.sql. If you altered the names or structure of the tablespaces, you might have to edit this to get it to install everything correctly. Otherwise, you can run it with the following:

SQL> start /usr/local/locomotive/db/oracle/loco_user.sql;

SQL> start /usr/local/locomotive/db/oracle/loco_session.sql;

That should install the fundamentals for the Locomotive, including the Locomotive Admin user. You can check to make sure everything went okay by typing the following command:

SQL> select * from loco_users;

You should see something like the following:

USERID     USERNAME                         PASSWORD
---------- -------------------------------- --------------------------------
LOCO_FLAGS ADDED     MODIFIED  LAST_LOGIN
---------- --------- --------- ---------
1 admin                            changeme
7 15-OCT-98 15-OCT-98 15-OCT-98

If you don't, there's something wrong with your script. Check it and try running it again; if you still have problems email us.

Once you've finished the main installation, you may want to install the sample applications. You can read a brief summary of each in our Sample Module Descriptions.

Informix Databases

Before you start installing the Locomotive schema, you'll have to create at least one dbspace for the tables to reside in. To create a dbspace, you should login as the Informix user on your system and start onmonitor. Once the program starts up, select DBSpaces and create a new one. We recommend using at least one dbspace of at least 20 MB. We also recommend using logical links for your dbspaces, so you can move them around to whatever disk has the most room without bringing down the database.

Now that you have your dbspaces, its probably best to create a loco database user. To do this, you first have to create a loco user for your OS. Once that's done, you can grant the necessary privileges to the loco user by starting dbaccess, selecting Query Language and any database, and entering:

grant connect, resource to loco_user;

After you've created the dbspaces, you're ready to create the tables the Locomotive requires. You probably want to create these as the loco user, so you should login as the loco user on your OS. Now you may want to edit the table scripts to change the names of the dbspaces to your own names. Once your done with that, go into the db directory and run the command dbaccess. Choose any database, and select Query Language. Select Choose from the Query Language menu, then select loco_create_db. Now, when you select Run, dbaccess will create the necessary database, tables, and procedures.

Solid Databases

Once you have Solid up and running (follow the directions available within the distribution or on Solid's web site ), you need to do two things:
1) create the loco user
2) add the tables and stored procedures for the Locomotive from the included schema files

Connect to the database using Solid's solsql utility:

bin/solsql -c database/default

(C) Copyright Solid Information Technology Ltd 1993-1998
Execute SQL statements terminated by a semicolon.
Exit by giving command: exit;
Username: dba
Password: 
Connected to default server.

create user loco identified by loco_pw;
commit work;

bin/solsql -c database/default -f /usr/local/locomotive/db/solid/loco_tablespaces.sql

MySQL Databases

Installing the Locomotive Schema with MySQL is a two part process. First, you have to create the Locomotive database and the loco user. You can use the script db/mysql/loco_create_db.sql to do this using the command:

% mysql -uroot -p(password) mysql < /usr/local/locomotive/db/mysql/loco_create_db.sql

Next, you'll need to reload the MySQL permissions; to do this use the following:

% mysqladmin -uroot -p(password) reload

Now, your ready to install the schema. You can use the scripts db/mysql/loco_user.sql db/mysql/loco_session.sql to do this- you should run it as the user you just created with the following commands:

% mysql -uloco -ploco_pw dev < /usr/local/locomotive/db/mysql/loco_user.sql

% mysql -uloco -ploco_pw dev < /usr/local/locomotive/db/mysql/loco_session.sql

That should install all the necessary files. If you have a problem, try to run the scripts from inside mysql manually by cutting and pasting. If this fails, email us.

If all the scripts for each database ran correctly, there should be a default Admin user installed in the database. This user has a username of 'admin' and a password of 'changeme'. You should change either of these to what you prefer. This Admin user has been given all the flags necessary to administer the Locomotive, such as:

1. The ability to tell a Locomotive server to shut down
2. The ability to look at the internal state variables of a Locomotive
3. The ability to change those internal state variables.

SQL> insert into loco_users (username, password, userid, loco_flags, 
added, modified)
values ('Myusername', 'Mypassword', 
loco_users_userid_sq.nextVal,
7, SYSDATE, SYSDATE);

SQL> commit;

where Myusername and Mypassword are a username and a password that you choose for yourself. You can run this command as many times as you'd like, to create as many superusers as you'd like. The value 7 for loco_flags, when expressed as a binary number, is 111; so, it turns on all three superuser powers (Wondertwin powers activate! ;^).

In Informix, start up dbaccess, choose "Query-language", then choose your database, then choose "New" and type in the command:

execute procedure create_user (0, 'Myusername', 'Mypassword', 7)

For each of the other databases, just look in the scripts and should find the correct command.

To learn more about the Locomotive administration flags, see the Administration manual.

Here's a list of the configs you'll want to change before you first start up the Locomotive. For more detailed information, see our configuration docs.

The Locomotive needs to know where you installed it. To set the installation path, find the following line in your config/loco.conf file:

SYSTEM_SERVER_ROOT_PATH                 /usr/local/locomotive

When you change the port number for a Locomotive, you also need to change its configuration file so that it will start up listening at that new port number. Use a text editor to change the following line in the file loco/config/loco.conf:

# port this particular server should run on.
# Locomotives operating in parallel must bind to different ports
LOCO_PORT                                5421

If you are running more than one Locomotive, you need to change loco.conf for each Locomotive.

You also need to modify loco.conf so that the Locomotive knows which database driver to use. For example, if you use Oracle drivers for an Oracle database, you might use the following lines:

DB_TYPE oracle

DB_DRIVER_CLASSNAME oracle.jdbc.driver.OracleDriver

DB_CONNPOOL_URL jdbc:oracle:oci7:@

The DB_TYPE variable is used within your code to tell what kind of database you're using. DB_DRIVER_CLASSNAME is the Java class of the JDBC driver, to be loaded dynamically by the Locomotive. (* Don't forget to add the Java class path of the driver to your CLASSPATH environment variable.) DB_CONNPOOL_URL is the URL used by JDBC to locate and connect to your database. We supply several alternative setups for different drivers in loco.conf; to use them, simply remove the '#' in front of each line, and add '#' to the lines for the drivers that you're not using. (The '#' character comments out lines in loco.conf) for drivers we've found to work, see the Drivers appendix. For information on the Cloudscape driver, see the Cloudscape section below.

Usually, relational databases require you to log in as a valid "database user", with a valid password. The following two lines allow you to specify the username and password for your database user:

# additional database connection parameters.
DB_CONNPOOL_USERNAME loco

DB_CONNPOOL_PASSWORD loco_pw

For each Locomotive you want to run, you also need to customize loco.conf so that Locomotive will write to a Server Log with a unique filename, and to an Event Log with a unique filename. You can do this in the following two lines:

# the '%' will be replaced with the current date, YYYYMMDD format.
# the path is relative to the server root directory.
LOG_PATH logs/loco1-%.log

# like above, but for the event log
EVENT_LOG_PATH logs/events1-%.log

Since cookies are checked for each locomotive request, it's important to make sure this is set to your domain.

LOCO_COOKIE_DOMAIN_MAIN                  .yourdomain.com

In order to use your Locomotive with the NSAPI Locolink tunnel, you have to let it know what the NSAPI identification URL token is, so that is can interpret everything that comes afterwards as Locomotive URL tokens. You do this by setting the NSAPI_TUNNEL_URI_TOKEN_PREFIX config variable. For example, if the web server uses */locolink* as the Locolink tunnel identifier, then your loco.conf file should look like:

NSAPI_TUNNEL_URI_TOKEN_PREFIX  /locolink

For more information on configuring the Locomotive for use with the NSAPI Locolink tunnel, see the Locolink documentation.

For more information on how to configure the Locomotive, including how to activate the sample handlers, please take a look at the configuration docs.

Finally, a number of utilities have been included in the Locomotive to enhance performance and ease of use. Refer to the Locomotive Administrator's Guide about these utilities. The following utilities are included in either the /bin or the /src/c directories of the distribution:

startloco This script calls the java command that gets the Locomotive up and running. It requires the LOCO_HOME environment variable to be set to the location of your Locomotive. It takes an optional command line argument of the path to the loco.conf file to be used for the Locomotive. If the argument isn't specified, then it tries to use $LOCO_HOME/config/loco.conf.

stoploco This is a program that tells the Locomotive to finish handling any requests, close its database connections, and die. You can specify the port number and IP address of the Locomotive to stop, using -p <port number> and -a <address>; the defaults are port 5421 and localhost, 127.0.0.1. You can find the stoploco program in your architecture-specific directory, such as locomotive/bin/solaris_sparc, locomotive/bin/linux, and locomotive/bin/freebsd. You should copy (or symlink) the stoploco binary for your platform to the bin directory:

% cp locomotive/bin/linux/stoploco locomotive/bin/

restartloco This script simply runs the two above scripts in order. It takes three possible parameters. Here's the usage:

restartloco [-p port] [-a IP address] [-f config-file]

Feel free to customize this script for your own Locomotive(s).

parse_events.pl This is a Perl script which generates summary statistics about the usage of your site, by using the information in the Locomotive's Event Log files. (See the section "Gathering Statistics about Site Usage" in the Administrator's Guide.)

watchloco.pl This is a Perl script which is able to monitor each of the Locomotives that you're running on your site. It is intended to run forever, in the background, like a daemon. You can find out more about it in the Administrator's Guide.

% startloco /home/loco/config/loco.conf
[13821]

http://yourmachine.yourcompany.com/locolink/

Now, to stop a Locomotive, you need to know the port number and the IP address of that Locomotive. For example, if the port is 1212 and the address is 225.16.0.9, then you would say:

% stoploco -p 1212 -a 225.16.0.9

If you intend to use the CyberSource Locomotive extension to execute electronic financial transactions, then you must install the appropriate libraries and set up the appropriate CyberSource environment. To get the CyberSource Libraries, please contact us. Once you have the libraries, you'll need to set a new shell environment variable called ICSPATH to point to the cybersource directory in your Locomotive distribution, for example:

    % setenv ICSPATH /usr/local/locomotive/cybersource

You'll also need to add a directory to your LD_LIBRARY_PATH environment variable, namely, the directory in the cybersource directory which contains the CyberSource linkable libraries that are specific for your operating system. For example, if you're using Solaris, you might say:

    % setenv LD_LIBRARY_PATH  /usr/local/locomotive/cybersource/lib/solaris:$LD_LIBRARY_PATH

Then, after this, you need to follow the instructions in the CyberSource documentation for generating your own public and private CyberSource keys, and then mail your public key to the CyberSource Company so that they can register you with their server. For more information, refer to the CyberSource documentation and the Java API documentation for the org.locomotive.commerce.ics package on how to write your E-Commerce modules using the CyberSource API.

Note: For this version Cloudscape is not supported. We've had problems getting Cloudscape to work with this version. If you are able to get Cloudscape to work with this version please email us at locomotive-dev@locomotive.org with the details.

The Cloudscape Embeddable JBMS presents a new direction in information storage. In contrast to heavyweight database server, Cloudscape can be embedded in any java process that invokes it, thus bypassing the often cumbersome details of setting up a separate database. Though Cloudscape has a small footprint, it provides most of features one would want from a data storage application- it is a SQL-92 compliant fully relational database with transaction capabilities. It also has support for Java-based stored procedures, as well as its own SQL interface for storing and querying on Java objects. For a small site whose data requirements are fairly small and who doesn't anticipate the need to expand to multiple instance of the Locomotive, Cloudscape provides an easy and powerful alternative to more traditional databases.

Presently, you can download a free evaluation copy of Cloudscape from the Cloudscape web site You can also buy a version of Cloudscape online at Cloudscape's store.

Here are some simplified directions for installing Cloudscape. We assume that you will be only creating one database- the one used for the Locomotive. For a more sophisticated setup, we suggest you look at Cloudscape's documentation. Here are the steps you need to perform to get a basic Cloudscape system up and running:

Unpacking Cloudscape

You need to unpack your distribution of Cloudscape into the directory of your choice. For example, on a UNIX system, you can use

cd /usr/local; gzip -dc cloudscape.tar.gz | tar xvf -

This will unpack Cloudscape into /usr/local/cloudscape. You can also install Cloudscape directly in your Locomotive directory.

Setting the CLASSPATH You must add the necessary Cloudscape ZIP files to your CLASSPATH environmental variable, to allow java to know where to find Cloudscape. For instance, if on a UNIX system using the tcsh sell, if you've installed Cloudscape in /usr/local/cloudscape, then you'd use the command:

setenv CLASSPATH ${CLASSPATH}:/usr/local/cloudscape/lib/embeddedJBMS.zip
setenv CLASSPATH ${CLASSPATH}:/usr/local/cloudscape/lib/tools.zip

The embeddedJBMS.zip file contains the classes for the database; the tools.zip file contains some tools you'll need to install the Locomotive table schema.

Installing the Locomotive Table Schema 

Next, you'll have to get acquainted with the Cloudscape interactive query tool, ij. ij is a simple tool for loading queries that makes it easy to install query files. If you want to use the scripts we provide to set up your Cloudscape database, you should make sure that you're in the directory you want the database files directory installed into. For instance, if you want the database files to be in your Locomotive directory, you'd change your directory to /usr/local/locomotive or wherever your Locomotive lives before running ij. You start ij by saying:

java -Djdbc.drivers=COM.cloudscape.core.JDBCDriver COM.cloudscape.tools.ij

run 'db/loco_create_db_CLOUDSCAPE.sql';

Note:  The script will create the database in whatever directory you were in when you started ij. If you want your database in a particular place, you should enter that directory and then run ij. If you've already installed the database in the wrong directory, you should delete the database you just created, enter the desired directory, restart ij, and re-run the script.

If you have problems running the script, try manually entering the commands by cutting them out of the script and pasting them into ij. If that doesn't work, email us.

Once the script finishes and you've exited ij, if you want to connect to your database again, you can do so directly with the command:

java -Djdbc.drivers=COM.cloudscape.core.JDBCDriver \
     -Dij.protocol=jdbc:cloudscape: -Ddatabase=/usr/local/locomotive/loco_dev \
     COM.cloudscape.tools.ij

At this point, you can choose to install the Graffiti Wall demo application. To do that, start ij with the commands listed above, and type:

run 'db/demos/loco_graffiti_tags_CLOUDSCAPE.sql;

Configuring the loco.conf file 

Now, you have to change some variables in the main server config file. The default config file is LOCO_HOME/config/loco.conf. For detailed information on the configs variables in the loco.conf file, see the Config Documentation. Here's a list of the variables you'll have to alter specifically to use Cloudscape and some sample values; you'll have to alter some others too.

DB_TYPE                         cloudscape
DB_DRIVER_CLASSNAME             COM.cloudscape.core.JDBCDriver
DB_CONNPOOL_URL                 jdbc:cloudscape:/usr/local/locomotive/loco_dev

That's it- you should be able to start up your Locomotive using Cloudscape! For more info on how to start and stop the Locomotive, see the install docs and the Administration docs.

The Locomotive can be used with many different databases. The following Listing contains both drivers known to work with the Locomotive, and those known to have problems and bugs. If you would like to use a driver not on this list, please let us know what kind of your using and whether it worked, and we'll get it on the list for the next version. For a complete list of all the common JDBC drivers, you can visit The Javasoft JDBC Drivers Page.

You may notice that many middleware brokering drivers are not included on this list. We feel that introducing another layer of brokering into the Locomotive system would decrease efficiency and probably should be avoided. For that reason, we have not tested any of those kinds of systems.

Compatible Drivers

• Oracle all-Java version
• Oracle Type-2 drivers
• Weblogic native UNIX version

Incompatible Drivers

• Oracle native UNIX version

Compatible Drivers

• Informix ODBC Driver, CLI SDK version 2.5
• Informix JDBC Driver: Currently Untested. Previous version would not return values from stored procedures.

• Weblogic Informix4 JDBC/Kona driver. The UNIX distribution is currently missing a class required for use with the PreparedStatement.setObject() method.
• Intersolv ODBC Driver, version 3.01. Contained in Informix's CLI SDK version 2.8. Incompatible with the JDBC-ODBC Bridge, both versions 1.1 and 1.2.

Compatible Drivers

• Terrence Zeller's twz1 Driver, Version 1.0.3
So far this driver seems to work perfectly. You can find the latest version here.

• jms Version 1.3.0 beta. Problems with Prepared Statements and stored Procedures.
• exgweMysql Version 0.9.2. Problems with Prepared Statements
• mm.mysql Version 0.6. No PreparedStatement implementation.

Compatible Drivers

• Solid produces their own JDBC drivers. In our use, they appear to be a pretty full blown implementation offer good performance. Company web site, JDBC Driver Page