QueryForm User's Guide[QueryForm Home Page]
INSTALLING QUERYFORMTo install or run QueryForm, you must first have the Java Runtime Environment, version 1.3 or later, installed on your computer. If you do not already have it, it is freely available and can be dowloaded at http://java.sun.com.
If you are installing QueryForm on a Windows PC, the easiest method is to use the automated installation program.* The automated installation program is packaged in a jar file named "qform-N.N-installer.jar", where "N.N" is the number of the version you are installing. The installation program can be downloaded from QueryForm's download page.
To run the installer program, first try double-clicking on its icon in the folder where it was downloaded. If your system is configured so that files with a ".jar" extension are associated with the Java virtual machine, the installer program should launch. If it doesn't, open a Command Prompt window (DOS shell), change to the directory where the qform-N.N-installer.jar is located, and run this command (making the appropriate substitution for "N.N"):
java -jar qform-N.N-installer.jar
Once the installation program has completed, you can run QueryForm by double-clicking its shortcut. If you chose not to create a shortcut during installation, you can run it by launching the file qform.bat, which will be located in the directory in which you installed QueryForm.
NOTE: The automated installation program will run on non-Windows platforms, however, no shortcut or launch script will be created. It is nonetheless a convenient way to install QueryForm along with all of it's required libraries.
Manual Installation: To install QueryForm manually, you will need the file qform.jar, which is packaged inside qform-N.N-bin.zip ("N.N" is the version number) and is available here. You will also need the required library jar files, which are available here. The libraries required to run QueryForm are listed in the file REQUIRED_LIBRARIES.TXT, which is distributed with QueryForm. If you don't have a copy, you can get it here.
The qform.jar file must be in your Java classpath, and the library jars should be in the same directory as qform.jar. As long as the library jars are in the same directory as qform.jar, they should not need to be in your Java classpath, because they are referenced in qform.jar's manifest file with the "Class-Path" header.
Within the directory where the qform.jar file is, create a subdirectory called "drivers". Place any jar or zip files containing JDBC drivers into that directory, and they will be loaded when the program is started.
If you're not familiar with what a Java classpath is, don't worry; simply arrange the qform.jar file, the libary jars and the drivers directory as described above, and try one of the launching methods described below. One of them should work.
As previously mentioned, if you have installed QueryForm with the automated installation program on a Windows PC, you can run the program simply by double-clicking the shortcut created by the install program. If you installed QueryForm manually, or on a non-Windows computer, or are experiencing problems with the shortcut or the supplied qform.bat file, this section explains how to launch the program from a command line or script.
If you have arranged qform.jar, the library jars, the drivers directory and any needed JDBC driver files (.jar or .zip) as described above, you can start QueryForm simply by executing the followng command from a command prompt, in the same directory where qform.jar is located:
java -jar qform.jar
If you want QueryForm to use JDBC drivers that are already in your system classpath, use this command line on a Windows system:
java -classpath qform.jar;%CLASSPATH% org.glasser.qform.QForm
and this command on Unix systems:
java -classpath qform.jar:$CLASSPATH org.glasser.qform.QForm
If qform.jar and all needed JDBC drivers are in your system classpath, and the library jars are in the same directory as qform.jar, you can run the program with this command:
java org.glasser.qform.QFormIf you are running QueryForm against a DB2 database (particularly one on a mainframe) and the program terminates abnormally, try starting it with this command line switch:
java -Dno.foreign.keys=true org.glasser.qform.QForm
Configuration information for QueryForm is stored in an XML file called qform.xml which normally resides in the user's home directory. If one is not found when the program is launched, it will be created. Alternate configuration files can be specified as a command line argument:
java org.glasser.qform.QForm S:/share/project/qform-share.xml
or by using the -D switch to set the "qform.config" system property:
java -Dqform.config=/etc/qform/config.xml org.glasser.qform.QForm
The order of priority for specifying a configuration file is:
NOTE: The configuration file is not locked while the program is running, and it is overwritten each time the program is exited normally. If you are sharing a configuration file with other users on a network, you may set its filesystem attributes to read-only to prevent individual users from modifying the configuration file. If QueryForm is unable to overwrite a configuration file, it will simply alert the user and then exit normally.
CONFIGURING A DATA SOURCEEventually, there will (hopefully) be detailed documentation for configuring a data source through QueryForm's data source dialog. For the moment, however, this program will be most useful to Java developers who are already familiar with JDBC (Java Database Connectivity), and who are familiar with concepts such as driver classes and URLs. If you fall into this category, the data source dialog should be self-explanatory.
For those who are not, but are familiar with ODBC data sources, here are brief instructions for connecting QueryForm to an ODBC data source that has already been configured on your computer:
RUNNINQ QUERIESOnce a connection has been established, you can query individual tables of the database. Use the following steps:
VIEWING TABLE METADATATo view table metadata, after you've connected to a database, select Table Metadata from the Connect menu. Select a table as you would to open a new query window. This will bring up a window listing all of the columns for the selected table, along with their data types, null/non-null attributes, etc. For some databases, a separate tab will show the foreign keys for the table as well.
PLUGGABLE LOOK-AND-FEELSA "pluggable look-and-feel" is an add-on module that can change the appearance of certain visual features of an application, such as fonts, buttons, icons, colors, borders, etc., without changing the application's code. QueryForm fully supports pluggable look-and-feels, and allows its look-and-feel to be changed while the program is running.
The Java runtime environment comes bundled with several look-and-feels, in addition to the default "Metal" look-and-feel. These will be available in the "Look and Feel" submenu (available through the Window menu) when QueryForm is started.
In addition to Java's bundled look-and-feels, a number of third-party look-and-feels, many of them free and open-source, are available. A partial list of available ones is at http://www.javootoo.com.
A third-party look-and-feel usually comes packaged in a jar file, and often the jar file may be contained inside a zip file. To use a third-party look-and-feel, the jar file must be placed into QueryForm's "drivers" directory (see the description of the drivers directory above) or it must be in QueryForm's classpath.
Each third-party look-and-feel has a main "class name" associated with it, and to use that look-and-feel, you must know the class name. This should be available from the look-and-feel's documentation. Unfortunately, most look-and-feel documentation is targeted toward Java developers, so it may take some digging to determine the main class name. One example is the Oyoaha look-and-feel, which is freely available at http://www.oyoaha.com/lookandfeel. Its main class name is:
The main class name for other look-and-feels will probably be structured similarly to Oyoaha's, and often they end in "LookAndFeel".
After you have placed a third-party look-and-feel's jar file into QueryForm's drivers directory or classpath, restart QueryForm. From the Window menu, select the "Look and Feel" submenu, and then the "Install new..." menu item. This will bring up a dialog box, into which you should enter the look-and-feel's main class name. When you close the dialog box, QueryForm will automatically switch its look-and-feel to the one you have just installed, and it will be available in the "Look and Feel" menu, even after QueryForm has been restarted.
ADVANCED USERS: By default, QueryForm will always start up with the default Metal look-and-feel. To use another look-and-feel at startup, edit the script, batch file or shortcut that you are using to start QueryForm, and add this system property to the command line, right after "java":
-Dqform.laf=<main class name of look-and-feel>
CAUTION: Third-party look-and-feels are of varying quality. Some are better behaved than others. Some of the less-well-behaved ones may modify QueryForm's appearance in a way that, when a new look-and-feel is selected from the menu, features of the old one will remain. (This can be remedied by restarting the program, however, and the effect is purely cosmetic rather than functional.) To be fair to the authors of these look-and-feels, however, it should be noted that most look-and-feels are designed with the intent that they will not be changed "on-the-fly" while a program is running, but rather act as a program's hardcoded look-and-feel. Some of the better-behaved ones I've encountered are Oyoaha, mentioned above, and several from JGoodies, available at:
Please understand that I will not be able to provide support for third-party look-and-feels.
NOTE: MANY THIRD-PARTY LOOK-AND-FEELS REQUIRE JAVA 1.4 OR LATER TO WORK PROPERLY.
*QueryForm's automatic installation program was created with IzPack, a free, open-source utility from IzForge.