FAQs
Frequently Asked Questions

(please read before reporting a bug)

• Is there an InstantDB mailing list that I can use to ask questions?
  
  Yes. To subscribe go to the Mailing Lists page.
  
  
• What is Java™? How do I set my CLASSPATH? Where can I get the JDK...?
  
  If you're just starting out programming in Java™ then you can do no better than to read Peter van der Linden's excellent Java™ FAQ. This is available from many web sites and news groups. Try here for an up to date copy.
  
  
• Where are the API definitions? The examples are too complicated.
  
  InstantDB uses Sun's JDBC™ API. This is described in your Java™ documentation, at sun's website and in numerous books and articles. You need to learn this API before you will be able to write programs that use InstantDB.
  
  
• InstantDB seems to allow the same PRIMARY KEY value to be used multiple times. Shouldn't this be illegal?
  
  Strictly speaking, yes, it should be illegal. However, not all databases enforce this. In order to be able to exchange data with such systems InstantDB relaxes this restriction on primary keys. You can enforce the restriction if you really want to using the UNIQUE PRIMARY KEY construct.
  
  
• Every time I start my program I see the message: "Database not shut down cleanly or in use by another program.

  Set recoveryPolicy=1 for automatic recovery. Should InstantDB attempt recovery now? (y/n)". This means that InstantDB has detected that there is information missing from the database files on disk. This can be for one of two reasons. Either the database was not shutdown cleanly or it is currently being accessed by another program. If you are sure that no other programs are currently accessing your database then you should type y and allow recovery to proceed. No information will actually have been lost, but InstantDB will perform various cross checks and will rebuild indexes on affected tables. If another program is accessing the database then you must not allow the program showing the recovery message to proceed. See documentation for full details.

• How do I set the base and step values for auto-increment columns?
  
  By default, all AUTO-INCREMENT int columns start at 1,000, and all AUTO-INCREMENT long columns start at 10,000,000,000. All values increment by 1. You can alter the base value using the SET INCREMENT_BASE... command. It is not currently possible to alter the increment step.

• String searches that worked OK before now seem to fail
  
  InstantDB uses hashes to create indexes. The String hashing algorithm changed between JDK 1.1 and JDK 1.2. Indexes built by one JDK are therefore not understood by the other. You will be affected by this problem if all of the following conditions hold.
  
  
1. You have char or varchar columns of width greater than 15 characters.
2. The columns are part of an index.

You built the database under 1.1 or 1.2 and then tried to run InstantDB using the other JDK.

From InstantDB 2.3 onwards, InstantDB calculates its own string hashes. If you think you are affected by this problem then DROP all affected indexes (including primary keys where applicable) and recreate the indexes using InstantDB 2.3.
String indexes created prior to InstantDB 2.3 under JDK 1.2 will not be understood by InstantDB 2.3 or later. To overcome this, set alStringHashing=1 in the database prpoerties file. This forces InstantDB to use the JDK's Object.hashCode() function instead of its own String hashing.

• I can open my database from the properties directory but not from another directory.
  
  You are probably using a URL like jdbc:idb:mydb.prp. Change instead to a fully qualified pathname for the properties file - something like jdbc:idb:c:/userdate/mydb.prp.
  


• What platforms and OS' is InstantDB known to run on?
  
  InstantDB has been known to run successfully under: NT4, '95, Linux, Solaris, AIX, OS2, MacOS, SVR4, EPOC32.
  
  
• What is the largest size of an InstantDB table?
  
  The largest InstantDB table tested so far was just over one million rows. Each row had about 20 columns.
  
  There is no limit to the size of InstantDB tables. However each index entry consumes, on average, about 15 bytes. So indexes on very large tables should only be used where sufficient physical memory has been allocated to the Java Virtual Machine™.
  
  
• If start up appears slow.
  
  The most likely explanation for this is that all connections were not properly closed from the previous database session. When a table gets modified, InstantDB marks that table as dirty. When the last database connection is closed, all dirty tables are closed cleanly and left in a consistent state.
  
  If the database is shut down abrubtly, say using ^C or an unhandled exception, then when it is next opened it enters a recovery mode. This involves full table scans of all dirty tables and the rebuilding from scratch of all modified indexes. This can take a substantial amount of time. The database must be shut down cleanly in order to save the recovered state.
  
  
• Index files are suspiciously very small.
  
  Again, this is due to an uncontrolled shutdown of the database. Indexes are held entirely in memory and are not written to disk until the last database connection is closed.
  
  
• I seem to get FileNotFound Exceptions with JServ.
  
  This is actually a file access permissions problem. Make sure that all of the database files have world read/write privilege.
  
  
• Inserts seem to slow down as the table size increases.
  
  If a single connection is adding records to a table with no indexes then InstantDB's insert performance is virtually constant over a very wide range of table sizes.
  However, if the table contains one or more indexes (even a PRIMARY KEY), then the time take to navigate the indexes will gradually increase. For bulk data imports, we recommend creating indexes after all of the data has been added.
  If there are additional connections performing queries against a table while INSERTs are being performed, then the time taken to perform the queries will also grow as indexes grow and full table scans take longer. These connections will therefore lock out insert statements for longer as the table size increases. They will also leave the random access file pointer for the underlying file in a sub-optimal position.
  
  
• The database occasionally just seems to lock up.
  
  Almost certainly due to a connection holding a table lock. By default, all InstantDB transactions are serializable. This means that, even for a query, all tables involved in a SQL statement are locked exclusively (all InstantDB locks are exclusive).
  A query retains its table locks until the results set has been completely read, or until a new query is executed. Simply by not reading the last row of a results set, a connection can lock all of the tables involved.
  The description of JDBC™ transaction handling is given in the java.sql.Connection documentation. Unfortunately it is spread out throughout the entire html page, and you really have to read it from top to bottom to understand what's going on. Once you've done that, read Transactions to understand how InstantDB implements transaction processing.
  
  
• Applications work but Applets seem to fail.
  
  Java™ imposes security restrictions on Applets. They are not allowed to read or write to disk and can only form network links to the location they were downloaded from. This prevents rogue Applets, downloaded from untrusted sources, from damaging your system.
  
  InstantDB makes extensive use of disk files and so an arbitrary Applet will not be able to access an InstantDB database. However, it is possible to get around this. The security restrictions imposed on Applets are enforced by a browser's security manager. If the security manager can be persuaded to trust the Applet then it will allow disk access to take place. Both Internet Explorer and Netscape allow you to digitally sign an Applet using a trusted key. Unfortunately, they do this in different ways, so it isn't possible to have the same Applet trusted by both major browsers.
  
  Netscape also provide proprietary extensions which allow Applets to talk directly to their security manager and remove the security restrictions. For an example of this see the JDBC™Appl example program.