QueryForm User's Guide

CONTENTS

1. Installing QueryForm
2. Running QueryForm
3. Configuring a Data Source
4. Running Queries
5. Viewing Table Metadata
6. Pluggable Look-and-Feels

top

INSTALLING QUERYFORM

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.

top

RUNNING QUERYFORM

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.QForm

    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:

1. First the presence of a command line argument is checked for.
2. Second, the presence of the "qform.config" system property is checked for.
3. Third, the presence of a file "qform.xml" in the user's home directory is checked for.
4. The configuration file is created in the user's home directory.

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.

top

CONFIGURING A DATA SOURCE

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:

1. From the Connect menu, select Data Source...
2. In the dialog that appears, click the New button to make the fields editable. Then make the following entries:

• Display Name - This is any descriptive name that you choose for this data source, for example, "Test Database".
• Driver Class - Select sun.jdbc.odbc.JdbcOdbcDriver from the dropdown list of available drivers.
• Database URL - type in the following:

     jdbc:odbc:<ODBC Data Source Name>
     

  and substitute the name of the ODBC data source for <ODBC Data Source Name>.
• Requires Login - Check this box if a username/password combination must be sent to the database when a connection is made.
• User Name - This should be a user name that can be used to connect to the ODBC data source indicated in the Database URL field.
• Password - This is the password that can be used in combination with the given user name. It can be stored here for convenience, however it will be saved in the configuration file in CLEAR TEXT. You may leave this field blank, and a login dialog will be presented to you when you attempt to connect.
• Max Connections - QueryForm pools connections, and will not use a connection for other purposes while there is an open resultset associated with it. An open resultset is a large one, of more than 500 records, that have not all yet been read from the database. You can tell that a resultset is open when the status bar message says something like "Row 45 of 750 read". If an entire resultset has been read, the status message will say something like "Row 53 of 97". The absence of the word "read" means that the entire resultset has been read from the database and the connection has been made available again in the pool. If you don't expect to have many large resultsets open simultaneously, then a small number, such as 3 should suffice. Otherwise use a larger number.
• Login Timeout - This is the number of seconds after which, if a successful connection is not established, QueryForm should abort the attempt. This value should usually be set to between 15 and 30 seconds.

top

RUNNINQ QUERIES

1. From the Connect menu, select Query Form...
2. In the table selector dialog that appears, you may select the data source from the top list, which will show the ones you're currently connected to. Then, select the schema or the owner of the table you wish to query from the second list. Then, you can select the table from the third list. NOTE: If your datbase contains views as well as tables, the views will be included in the table list. They will be listed, however, below all of the tables in the list and their names will appear in italics.
3. After you've selected a table, click OK to close the dialog. A new internal frame showing a Form View and a Grid View tab will appear. To enter query parameters in the form, select Form Query from the Action menu. This will make the form editable.
4. Once the form has been opened for editing, enter search criteria in the fields you want to query on. For example, entering Mary in a field labeled "FIRST_NAME" will return all records where the FIRST_NAME field is "Mary". You may also enter '%' characters as wildcards, for example, M% would match Mary, Mike, Matt, Mavis, etc. The matching may or may not be case-sensitive, depending on the database you're connected to. The comparison operators '<' and '>' can be used in numeric fields, for example, entering "> 100" in a numeric field will return all records with a value greater than 100 in that field. An SQL "BETWEEN" clause can also be entered in a numeric field, for example, "BETWEEN 100 AND 200".
5. You may browse query results in the form, or switch to the grid view to view them in a table. To select which columns will be visible in the grid view, right-click on the Grid View tab and choose "Select Columns..." from the popup menu. In the dialog that appears, hold the control key and click column names to select or deselect them. To export a resultset to a file, right-click on either tab of the query frame and select one of the export options.

top

VIEWING TABLE METADATA

top

PLUGGABLE LOOK-AND-FEELS

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:

    com.oyoaha.swing.plaf.oyoaha.OyoahaLookAndFeel

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:

http://www.jgoodies.com/freeware/looks/index.html

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.