You should now have the following sub-directories:
||holds the jar files containing the database classes
||holds various example files
||holds the source code for InstantDB's SQL functions
Add the Classes/idb.jar, Classes/idbf.jar and Classes/idbexmpl.jar
files to your CLASSPATH environment variable. Change to the Examples
sub-directory and enter the command:
java -ms16m -mx32m sample
or, if you are running JDK 1.2 or above:
java -Xms16m -Xmx32m sample
If all goes well, Sample 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
Note - the Classes/idb.jar file is 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 once the example programs are no longer required.
The Classes/idbf.jar file contains InstantDB's built in string,
date and numeric functions. This can also be ommitted if these functions
are not required.
If you get a ClassNotFoundException, or for some reason the sample
program doesn't load, then try the following:
- Check that both idb.jar and idbexpl.jar are in your CLASSPATH.
- Check that the above two files have been unarchived to your
/Classes subdirectory and that they are spelled correctly, all
in lower case.
- 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.
- Try upping the value in "-mx32m" to increase the amount of memory
available to the JVM.
- 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 Sample Scripting Program
The sample program takes its SQL from three files called sql1.txt,
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
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.
You can view the contents of the newly created database using the
java -ms16m -mx32m JDBCmain
This starts a small database browser. It initially displays the
system properties such as the Java Virtual Machine™ being used.
Click on Browse. This displays the contents of the current
directory. Click on sample.prp and then click on Open.
This constructs the URL for the database. 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.
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.
The properties file which defines the database, contains information
about the location of various database files. These are specified
using the following properties.
||Ordinary database tables
||Temporary tables such as Results sets
||System tables, such as the table of all columns
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:
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".
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
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.
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.
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.