InstantDB      Basic Topics      Advanced Topics      Reference Topics
Documentation Home Page

Installation Instructions

Install
Troubleshooting
Creating an InstantDB Database
The ScriptTool Sample Program
Directory Locations
Windows/OS2 Users
Apple MAC Users
Visual Age for Java™ users

Install

If you are upgrading to InstantDB from a previous release then always make sure that all databases have been shut down cleanly before upgrading.

  1. Create a new directory on your machine.
  2. Download the zip archive: idbx_x.zip, and place it in the newly created directory. "x_x" will usually be the latest version.
  3. Unzip the archive. Be careful to use a version of unzip that allows long filenames and that will recreate the full directory structure.

    You should now have the following sub-directories:

    Classes Holds the jar files containing the database classes
    Examples Holds various example files
    Examples/SQLBuilder Holds a JFC based database exploration tool.
    Examples/Win98 Holds a startup script for Windows 98 users.
    Examples/Linux Holds a startup script for Linux users.
    Functions Holds the source code for InstantDB's SQL functions
    docs Holds InstantDB documentation.

Windows 98 Users

  1. Using explorer find the file: Examples\Win98\setpath.bat, in your InstantDB directory.
  2. Right click on the file and choose Edit from the pop up menu.
  3. Change the settings for the environment variables IDB and JRE to point to the directories where you installed InstantDB and the Java Runtime Environment respectively.

    Note that the JRE directory is not necessarily the directory where the JDK is installed. For example, Sun's JDK 1.2.2 defaults to c:\jdk1.2.2. However the JRE defaults to C:\Program Files\JavaSoft\JRE\1.2.

  4. Using explorer, double click on Examples\Win98\start.bat

If you experience any problems with the above procedure then follow the instructions in the section below entitled All Other Users. This will explain how to run the example programs manually.

The start script will create a small test database and bring up DBBrowser (InstantDB's AWT based database explorer) with the test database opened. The script will prompt you before creating the database and before starting DBBrowser.

The left hand panel in DBBrowser displays the tables held in the database, including system tables and indexes. Click on the import1 table - the program creates the SQL: SELECT * FROM import1. click on Submit and this gets submitted to the database. The results are displayed in the right hand panel.

Always click on Disconnect before closing the DBBrowser program.

Read the section below entitled All Other Users. This section explains how to use InstantDB without the script files and how to turn off logging.

Linux Users

  1. Find the file: Examples/Linux/start, in your InstantDB directory.
  2. Open the file in your favorite editor.
  3. Change the settings for the environment variables IDB and JRE to point to the directories where you installed InstantDB and the Java Runtime Environment respectively.

    Note that the JRE directory is not necessarily the directory where the JDK is installed.

  4. At the command prompt change to the directory Examples/Linux/ in your InstantDB installation directory.
  5. Type the commands:

    chmod a+x start
    ./start
    

If you experience any problems with the above procedure then follow the instructions in the section below entitled All Other Users. This will explain how to run the example programs manually.

The start script will create a small test database and bring up DBBrowser (InstantDB's AWT based database explorer) with the test database opened. The script will prompt you before creating the database and before starting DBBrowser.

The left hand panel in DBBrowser displays the tables held in the database, including system tables and indexes. Click on the import1 table - the program creates the SQL: SELECT * FROM import1. click on Submit and this gets submitted to the database. The results are displayed in the right hand panel.

Always click on Disconnect before closing the DBBrowser program.

Read the section below entitled All Other Users. This section explains how to use InstantDB without the script files and how to turn off logging.

All Other Users

  1. Add the Classes/idb.jar, Classes/idbexmpl.jar and Classes/jta-spec1_0_1.jar files to your Enhydra, Bash or DOS CLASSPATH environment variable.
  2. Change to the Examples sub-directory.
  3. Enter the command:

    java -ms16m -mx32m org.enhydra.instantdb.ScriptTool

    or, if you are running JDK 1.2 or above:

    java -Xms16m -Xmx32m org.enhydra.instantdb.ScriptTool

    If all goes well, ScriptTool will create further sub-directories and create database tables in those sub-directories. You will also see some output on the screen. This is due to the fact that the supplied properties file enables a certain amount of logging. This can be easily switched off by editing the sample.prp file and setting traceLevel to zero.

  4. You can view the contents of the newly created database using the command:

    java -ms16m -mx32m org.enhydra.instantdb.DBBrowser

    This starts a small database browser. It initially displays the system properties such as the Java Virtual Machine™ being used.

  5. Click Browse. This displays the contents of the current directory.
  6. Click on sample.prp and then click on Open. This constructs the URL for the database.
  7. Click on Connect and the program connects to the database. The left hand panel displays the tables held in the database, including system tables and indexes.
  8. Click on the import1 table - the program creates the SQL:

    SELECT * FROM import1
    
  9. Click on Submit and this gets submitted to the database. The results are displayed in the right hand panel.

Always click on Disconnect before closing the DBBrowser program.

Note: The Classes/idb.jar and Classes/jta-spec1_0_1.jar files are the only .jar that you need to keep in order to use InstantDB. idbexmpl.jar contains only pre-compiled versions of the example programs. It can be deleted if the example programs are not required.

Troubleshooting

If you get a ClassNotFoundException, or for some reason the example program doesn't load, then try the following:

  1. Check that idb.jar, jta-spec1_0_1.jar and idbexmpl.jar are in your CLASSPATH.
  2. Check that the above files have been unarchived to your /Classes subdirectory and that they are spelled correctly, all in lower case.
  3. If you are using JDK 1.2 or later, try placing the jar files in the /jre/lib/ext directory. This will allow InstantDB to be found without being placed in the CLASSPATH.
  4. Try upping the value in "-mx32m" to increase the amount of memory available to the JVM.
  5. Use the -verbose function on the Java™ command line to ensure that it really is an InstantDB class which is not being found, and not one of its dependent classes.

Creating an InstantDB Database

If you were paying very close attention to the sample output, you may have spotted the URL "jdbc:idb:sample.prp". InstantDB refers to a database via a Java™ properties file. The properties file defines everything that InstantDB needs to know in order to create or open the database. Even the name of the database is derived from the properties file.

There is no separate database creation utility. If the properties file directs InstantDB to a database that does not exist, InstantDB creates the database itself.

The sample.prp file contains comments on the available configuration options. Those that are not self-explanatory are discussed later.

The ScriptTool Sample Program

When you ran one of the example script files above, or when you manually typed the ScriptTool command, InstantDB's ScriptTool class was invoked by the Java interpreter.

The ScriptTool program by default reads its SQL from the file called sql1.txt, although any other file can be supplied as a parameter. The particular sql1.txt supplied runs threads to interpret sql2.txt and sql3.txt in the sample sub-directory. This includes examples of some (but certainly not all) of the SQL syntax supported by InstantDB. Full details of the sample program are given in the examples section.

The test program also includes a test import file: "import1.txt". The format of this file is found in import_schema.txt. More information on importing tables is described later.

Directory Locations

The properties file which defines the database, contains information about the location of various database files. These are specified using the following properties.

Property Reqd Holds
tablePath Y Ordinary database tables
tmpPath N Temporary tables such as Results sets
systemPath N System tables, such as the table of all columns
indexPath N Index tables

If tmpPath, systemPath and indexPath are not specified then they default to the same value as tablePath.

Paths can be specified as either absolute paths, or as relative paths. If relative paths are used, then the paths are relative to the current user directory as specified in the system property user.dir. This is usually the directory that the Java Virtual Machine™ is being run in (i.e., the directory you were in when you typed the "java" command). Note that changing user.dir does not change the user's current directory, it simply changes the property. There is currently no way to change the user directory in Java™.

Paths relative to the properties file itself, rather than to the current user directory, are also supported. To enable this option, include the line:

relativeToProperties=1

in the properties file. Note that both absolute and relative paths can be specified using either forward slashes / or double backslashes \\ on Windows 95 and NT. Using relative paths with forward slashes provides the highest degree of portability.

The sample.prp file provided in the sample directory uses paths that are relative to itself.

Paths can also be specified using system properties. This is done by prefixing the path value with a '$' dollar sign. For example, setting tablePath=$user.dir will cause tablePath to be set to the runtime value of the System property "user.dir".

Windows/OS2 users

When table paths are specified relative to the properties file, make sure you pass a url that contains the full path of the properties file. e.g., jdbc:idb:c:\idb\sample.prp (double back-slashes if in Java™ code).

A url such as jdbc:idb:sample.prp will work fine when you are actually running your program from the directory containing sample.prp, but you must use the full path of the properties file if you are running the program from a different directory.

Apple MAC users

The current example text files are saved with CR/LF line terminators. You may have to convert some of these files to use standard MAC line terminators (CR only) to get the sample programs to work.

Thanks to David Bowser-Chao for pointing this out.

InstantDB automatically generates certain file names. Because of filename length limitations on the MAC, users are advised to restrict table and column name lengths. In particular, if binary columns are being used then the table and column names should be restricted to no more than 4 or 5 characters.

Visual Age for Java™ Users

For some reason, Visual Age for Java™ cannot import the current InstantDB JAR files. To import into VAJ, simply unarchive the JAR files into an empty directory and import the directory instead.


Copyright © 2000, 2001 Lutris Technologies. All rights reserved.