Query Wizard 4.0 - Toolcraft Development

Posted June 1 1998

Printer-friendly version

ToolCraft's Query Wizard is a template module that allows the Clarion developer to add a wizard interface that allows end-users to create and save their own queries. They can then use those queries to view data in a browse, report or process without coding.

Trying to figure out the information users will eventually need is a daunting task even when specifications on output are well laid out. A flexible method of extracting data that the end-user can easily master should help you adapt to the changes that accompany even the best-planned projects. SQL was originally written to fulfill this requirement, but in today's point and click Windows environment the end user is used to a more sophisticated interface.

Major Features

With DOS programs, a single input form could be used for data and query entry. Windows programs tend to have multi-tabbed windows that would make this solution hard to implement. Recently QBE tables have become popular and are great for quick and dirty end-user programming tools such as Microsoft Access. Since people pay us for custom application programming, anything we can do to enhance the user interface is a plus. The Wizard interface was developed to lead an end-user along a set of logical steps with many outcomes. This stepped approach reduces the amount of errors that may be introduced in complicated procedures. ToolCraft saw the wisdom of this approach in early versions of Clarion for Windows and has been continually enhancing the product.

The latest version of Query Wizard version 4.0 includes features that allow the end-user to save and reuse queries. This feature also allows the developer to write pre-defined queries for reports, browses, and processes. Users may also be restricted from changing or adding queries to a specific procedure. Dropdown lists or buttons may be added to any window, or a query wizard may be invoked for any report. A new feature adds a navigation bar to any browse that can toggle the current query view on or off. VCR-like controls jump forward and backward between matched records. The developer can either choose to show only matched records or use different colored text lines, checked icons or both to enhance the browse. An example is provided at the end of this article that demonstrates all of these features. Another new feature allows you to include child relationships in a query; i.e., view all customers with invoice balances>500. A developer may even include a lookup procedure for selecting a value.

One of the added benefits to this version of Query Wizard is that all the source code is included. If TopSpeed keeps its promise that ABC templates won't break with every new release, a Clarion developer should be able to add functionality without having to worry about the core procedures. Query Wizard works with the standard templates as well as CPCS. I also tested it with the latest version of RPM and I had no problems.

Installation

I have included many Query tools in my applications over the years and have been using ToolCraft's Query Wizard in some of them since Clarion v1.5. I was glad to receive the latest version 4.0 in the mail promptly after ordering the upgrade for $99.00. An installation program and manual are included along with the template source. The installation went well with no problems; the STANDARD.TPW file is changed but a copy is kept in STANDARD.OLD. If any Clarion updates are applied in the future, a utility is provided called QWSTDFIX.EXE that makes the necessary changes without reinstalling the product. The change replaces the group %StandardWriteViewFilter with the statement #INCLUDE(C:\CLARION\TCTPL\TCQWSTD.TPW). This allows the queries to utilize keyed access to files when available. After registering both the ABC and 2003 templates, I was all set to go.

Implementation

Enabling Query Wizard in any application is as simple as adding the QueryWizardLib global extension to the application's global properties, then adding the QueryWizardMain local extension to a procedure. Next, add QWButtons or QWDroplist control templates to any browse procedure. Below is the global options screen where you can specify the image that is displayed when the wizard first comes up. There is also a language option of English, German, or Custom along with an Equates file. The last option, Saved Query Location, ensures that a new saved query file isn't created in more than one directory and that all your users are looking at the same saved query list.

The Global Options template

ToolCraft ships a Demo using a car dealer application and a tutorial in the manual goes through creating this application. The screen shots in this review are taken from the finished application. As a design consideration, it is important to start with your application's dictionary. The default variable names are generated using the field description in the dictionary. This value can be overridden using the field override options in the Query Wizard, but it is a lot more work to do this on every browse, report and process. If Do Not Auto-Populate option is checked in the dictionary the field will not appear in the Query Wizard field list. The dictionary option NOQW is used when you wish to have a field appear in a form but not in the Query Wizard field list.

The Wizard Configuration screen is available after installing the QueryWizardMain extension to a browse procedure. Query Classification is used to divide your queries into groups that may be used in different procedures. The Query Description field is used to describe the saved query, and the Query List Box Control specifies the browse control to use. The Disable Query Wizard Update Option, if checked, limits users to a dropdown list box of predefined queries.

The Wizard Behavior screen controls how the Query Wizard interacts with the user. These options limit how much control the user has and specifies how a report or process will work with the Query Wizard. Advanced options are available to specify how the Wizard appears at startup.

Wizard Behavior Options

The Files to Exclude tab enables you to remove files from the Query Wizard that are by default included in a Clarion view. The Fields Override tab allows you to control whether the field appears in the Query Wizard list or lets you override how it appears.

Wizard Field Override Options

Now that the QueryWizardMain local extension has been added, the next step is to add either the QWButtons - Query Wizard Call and Reset button control template or theQWDropList - Query Wizard Droplist of Saved Queries template. The QWButtons control lets you allow the end-user to Append/Join Queries by selecting an option in the Actions tab for the control. For the ultimate in precision, the developer may even allow end-users to manually enter or tweak queries using Clarion syntax.

The QWDropList control is useful when you want to limit the end-user to predefined queries. Additionally, a run time entry value may be added by inserting the QwRtEntry - Query Wizard Run Time Value Entry as a procedure extension. This is useful for getting range values for a report or process, or selecting a particular filter using a lookup table. This could be also be used with a calendar for selecting date ranges, or for selecting area codes or state abbreviations.

Another new feature for browses in version 4 is called 'match' mode. In addition to the standard filter mode where non-matching records disappear from the list, match mode can continue displaying all the records while allowing you to specify how the matching and non-matching records are displayed. For example, matching records could have a 'check' icon and be the normal color while non-matching records are displayed 'grayed out' with no icon. A navigation bar allows the end-user to turn match mode on or off, and also helps them navigate between matching records by automatically skipping non-matching records.

Note: If you are unfamiliar with how to add colors and icons to a browse you may wish to review your Clarion help file on this subject.

The QWChildTree extension allows the end-user to query both parent and child fields. This can be helpful when selecting records that have multiple criteria based on information contained in both the parent and the child.

The Query Wizard is broken up into at least four screens. First, you select the field on one screen and then the operator on the next screen. A value must then be supplied by using either a lookup table or an entry field. Finally, you can choose to finish the query or continue it with an AND or an OR. If you continue, the cycle repeats again; a cancel button is available at any time to end the query process. Two new operators Does Not Begin With and Does Not Contain are new to version 4. After building your query, you are prompted on whether you would like to save it if the developer has allowed it.

The screen below depicts how the application displays the queried results in match mode using a predefined query located in a Dropdown list box. Notice how the text line color and checkbox icon usage really highlight the matched records. The navigation bar allows the end user to jump between highlighted records.

Wizard Application Result in Match Mode

Overall I found using the Query Wizard templates easy to configure and use, adding to my application's professional quality.

Performance

According to the documentation, if a key is available the Query Wizard will use it. I did not have a large enough data set to see if this helped speed up general queries. Since the Query Wizard uses Clarion's Prop:Filter you should expect similar performance. Since you can't tell what your end-users will want for reports, I found that creating a small application with just a Query Wizard button and general list report is a good way to process a large database where a quick answer is needed. This application can be minimized when it is processing and the Clarion Report preview will popup when it is completed. I have noticed 32 bit applications seem to perform faster on queries.

Documentation

The ToolCraft documentation is concise and complete. It includes an installation section, tutorial section and troubleshooting section. The actual documentation is in a spiral bound notebook that lets you flip easily from page to page without breaking the binding. (My Clarion resource books always end up with broken spines trying to keep them open to a specific page.) The installation, configuration and use of each control and extension is documented. The prototypes for each function are also documented; this is more useful now that the source code is included.

I wish more Clarion add-ons would come with manuals - reading entire help files can be very tedious. David Bayliss stated at EuroDevcon that the easiest way to hide a feature is to include it in the readme file. Although we live in a digital age, we tend to like printed reference material.

Technical Support

I ordered Query Wizard version 4 just before it was completed and the beta had a few bugs. On-line questions where answered promptly and correctly on-line and the single phone call I had to make was returned the next day. ToolCraft also forwarded all testing issues to registered users via e-mail. Over the years, ToolCraft's support has been consistently good and I have had no complaints. Paid phone support is available for $49 per call (up to ½ hour) and application review is $99 (up to 1 hour).

Summary

The Query Wizard performs as advertised and dramatically improves the look and feel of your applications. The only improvement that I can see would be to have Query Wizard generate a native SQL query against a SQL database. Currently, Clarion's SQL performance leaves something to be desired using the PROP:Filter.

 

Category	Product Score
Ability to do the task	Excellent
Ease of use	Excellent
Ease of Installation	Very Good
Documentation	Excellent
Technical Support	Excellent
Modifies Shipping Templates	Yes
Black-Box DLLs/LIBs	No

QW 4.0 version supports both the Standard Clarion template set as well as the ABC (Object Oriented) template set.

Query Wizard 4.x can be purchased directly from ToolCraft Development for $199 US. A special upgrade price of $99 US is available for registered owners of Query Wizard 2.x. Full ordering information is available at the Toolcraft web site (http://www.toolcraft.com) or via phone (209) 586-1710 or fax (209) 586-1750.

More detailed product information and a downloadable demo of QW 4 are also available on their website. Special note: According to their website (when this review was published), if you order now you also receive a 2.003 version of QW with all of the new 4.0 features.

Article comments

Post a comment

You must be logged on to post comments.