Please email any bug reports, comments or suggestions to:
peter.hearty@ceasar.demon.co.uk
InstantDB comes with several utility programs, together with their source code.
These are intended to introduce users to JDBC programming, and to InstantDB in
particular.
- commsql - a simple command line utility that accepts
SQL statements and processes them interactively.
- sample - sample program that accepts SQL scripts.
- dump - a utility program that dumps the contents of
various InstantDB system files.
- InstantSQL - similar to commsql, but with a GUI
interface added.
- JDBCAppl - similar to InstantSQL but with a few
navigation and SQL builder additions.
"commsql" - short for Command line SQL - is a very simple program that accepts
SQL statements from the command line, and executes them interactively.
It always loads the InstantDB JDBC driver at start up, but you can easily
modify the code to load any other drivers you require.
commsql then prompts the user for a URL to connect to. In the case of InstantDB
this can be the URL for any InstantDB properties file. The database corresponding
to this properties file is then created if necessary and opened.
The user can then type in any valid InstantDB SQL commands. If these produce
a results set then the results are displayed.
When you want to exit the program, simply type "." (without the quotes) on a
line by itself.
"sample" was the original program designed to provide a simple illustration
of using InstantDB. However, it is now used as the InstantDB test harness,
and as such has become considerably more complex.
It always begins by opening a file called "sql1.txt". This is the initial
script containing commands to be executed. Every command begins with a
command letter, followed by either a SQL statement or further command
information. All commands must be terminated with a semi-colon - ';'.
The valid commands are listed below.
- 'c' command; - execute one of a list of alternative commands
- 'd' driver; - load a driver, e.g. d jdbc.idbDriver;
- 'e' sql; - execute command with no results set, e.g. e UPDATE table1 SET col1=col1+1;
- 'i' table; - get index info for table
- 'o' url; - open url, e.g. o jdbc:idb=sample.prp;
- 'p' sql; - create a prepared statement, e.g. SELECT * FROM ?;
- 'q' sql; - query with results set
- 's' param1,param2,...; - set parameters on a prepared statement and execute
- 't' script; - start off a new thread with its own input script
The 'd' command must be issued at the start of the sql1.txt script to load at
least one JDBC driver . This will normally be followed by an 'o' command to
open a database.
The 'c' is a sort of "catch all" for performing various miscellaneous tasks.
It must be followed by one of the textual phrases shown below.
- c autocommit on; - switches autocommit mode on.
- c autocommit off; - switches autocommit mode off. All further transactions
have to be explicitly committed or rolled back.
- c break; - a useful "no-op" command. By setting a break point on the line of
code in sample.java that handles this, you can get a script to break at any point
by simply placing this command wherever you want the break to occur.
- c use global prepared statement; - use the current "global" prepared
statement rather than the thread's own prepared statement.
- c set global prepared statement; - make the current prepared statement the
global statement that other threads can pick up.
- c use global connection; - use the global Connection object rather than
setting up a seperate connection for this thread.
- c set global connection; - make the current Connection object available to
other threads.
- c set isolation READ_UNCOMMITTED; - set the transaction isolation level
to Connection.TRANSACTION_READ_UNCOMMITTED;
- c set isolation SERIALIZABLE; - set the transaction isolation level
to Connection.TRANSACTION_SERIALIZABLE;
- c time; - The time in milliseconds that the previous command took to run.
- c close; - close the current Connection.
- c rollback; - rollback the current transaction using the JDBC Connection.rollback() method.
- c commit; - commit the current transaction using the JDBC Connection.commit() method.
- c show meta-data; - displays the type info and table list results sets.
- c wait for children; - wait for all child threads to complete.
- c exit; - exit the program immediately.
"dump" is a simple little class for dumping the contents of some of InstantDBs
system files. You can dump the contents of xxx$db$cols, xxx$db$tables, or of
the journal file.
You must be in the directory actually containing the file being dumped before
issuing the command. Output is normally to standard out, but you can of course
redirect to any file if required.
The syntax is as follows:
- java dump dbase t - This dumps the dbase$db$tables table contents of the
InstantDB database called "dbase" to standard out.
- java dump dbase t id - Dumps information from the dbase$db$cols table for the
table with TableID "id". ID can be obtained from a dump of the dbase$db$tables
table. If ID is 0, then information belonging to all tables is dumped.
- java dump dbase j - dumps the contents of the journal file.
As dump.java is included, you have access to the structure of these system files.
You are welcome to use this knowledge to develop more user friendly utilities. However,
you should be aware that the structure is likely to change over time.
Instant SQL is a neat little application. It offers essentially the same
functionality as commsql. It's so simple and easy to use that it really doesn't
need any instructions. Note however that this uses the JDK 1.1 event model.
My thanks to Jerry Smith for
providing this.
JDBCAppl illustrates InstantDB being accessed from a Java Applet. Opening
the ex1.htm example in your browser will show JDBCAppl at work. The
instructions for using JDBCAppl are included in ex1.htm.
Also included in ex1.htm, is a sample piece of JavaScript. This illustrates
how a Java Applet's public methods and properties can be accessed using the
JavaScript object model.
There are two issues that you'll have to consider in order to get the ex1.htm
example to work properly:
- JavaScript compatability.
- Applet security.
Internet Explorer 3.01 (build 4.70.1215) or above runs the JavaScript OK on
both '95 and NT 4. I had problems with its object model in version 3.00.
All versions of Netscape that I tried appeared to run the JavaScript OK.
Internet Explorer also seems quite happy to let a local applet perform
local file access (InstantDB needs permission to read and write to the disk
in order to operate). Note however that you should add the path for the
InstantDB and JDBCAppl classes to the class path in the registry:
HKEY_LOCAL_MACHINE\Software\Microsoft\Java VM\Classpath
The proper way to get the applet to work with Netscape Communicator
is to sign it with a digital certificate that is either trusted, or
has itself been signed by a trusted certification authority. Netscape's
web site has full details on how to do this.
As a work around, you can include the following import statement in the
applet:
import netscape.security.PrivilegeManager;
Then add the following lines to the method requesting the additional
priviliges:
PrivilegeManager.enablePrivilege("UniversalPropertyRead");
PrivilegeManager.enablePrivilege("UniversalPropertyWrite");
PrivilegeManager.enablePrivilege("UniversalFileRead");
PrivilegeManager.enablePrivilege("UniversalFileWrite");
PrivilegeManager.enablePrivilege("UniversalFileDelete");
(The file JDBCAppl.nets is simply a modified version of JDBAppl.java
that already contains the above changes).
Finally find Communicator's prefs.js file (mine was in
c:\program files\netscape \users \default), and add the following line:
user_pref("signed.applets.codebase_principal_support", true);
When compiling the applet, ensure that c:\progra~1 \netscape \communicator \program
\java \classes \java40.jar (or wherever your netscape java classes are),
is included in your CLASSPATH.
My thanks to Alok Singh for providing this information.
There's a class called JDBCmain that provides a main method and frame
for JDBCAppl, In order to run JDBCAppl outside of a browser all you have to do
is run JDBCmain, just as you would any other Java Application.