Clarion for Windows Assistant (CWA) - Carl Barnes

Posted December 1 1997

Printer-friendly version

I first programmed for an IBM mainframe computer. This was in the mid-sixties and the computer was a 1401 with 16K of memory. In those days we designed data records by laying-out fields either for an 80-column card or for tape. When we created routines to solve a specific problem we would code a copy on a coding sheet and store it for future reference. Paper was everything and a loose-leaf book was our reference library.

Programming Today

CW programmers enjoy a wealth of features built into the standard and professional versions. Yet, with all these features we still have needs beyond CW's direct capabilities. For example, I use Zoot. Zoot is an information repository and I have used it to store everything from passwords to various on-line services to code for solving specific problems. However, it's not specifically designed for programmers, so when Carl Barnes announced a new product called CWA I was interested. When Carl announced his latest version I had a brief dialog with him about the features of the product. He suggested I try the demo and I did (more on that later). But I was left with many questions and decided to bide my time. So now I have an opportunity to review CWA and I'm struck by how helpful it is for today's CW programmers.

Digesting CWA (burp!)

Think of CWA as an organized jumble of tools to help you with your daily programming.

Starting CWA

The major CWA features are: Message Maker, Dictionary and File Viewer, MAP Viewer, String Builder, Keycode Finder, Window Key Analysis, Template Code Builder, Color Designer, Equates Helper, ASCII Table, Error Helper, Code Library, Template Registrar, and Stick Note. I found that the best way to approach CWA was to use it in my daily programming work. So what follows is in an order dictated by my needs.

Where I began

You will find that the way to use CWA is to first start Clarion and then start CWA. You can use Microsoft's "Cool Switch" (Alt + Tab) to flip back and forth between your Clarion app and CWA. Also, before attempting to use a tool read the help file on that specific CWA tool. You'll find that there are many features to each tool that are not always immediately obvious.

Dictionary and File Viewer

Once Clarion and CWA were started, I began with the Dictionary and File Viewer. CWA stores dictionary information in its "DIC" format. This requires a one-time import of the dictionary data. Once imported, I opened the dictionary file and found it rather easy to examine file and field properties.

I found a wealth of features. Right clicking on a file shows you the file properties. Double clicking on a file brings up field and key list in a tree structure. The keys can be expanded to show their comprising fields. I next read the help file and found many helpful features including the ability to cut and paste field names into source code. Additionally, I found that I could cut and paste virtually all file commands from Open to setting up a next loop for a file.

Code Library

Next I found myself using the code library to store my snippets of code. Visually, the code library consists of a window with three browses labeled Type, Code Description, and Source Code. Think of Type as a category. The product comes with some pre-defined Types including Dates, File, and File Dialog. If I highlight Dates I find that the second browse describes two snippets of code: Compute Age, and Day of Week. Highlight the appropriate description (e.g. Day of Week) and you'll see the appropriate source code snippet. Now you can press the To Clip button and copy the code to the clipboard for pasting into your app.

The CW Assistant Code Library

The other day I came across a message on CompuServe from Burton Page (thank you Burton) on how to start Word and pass some data from a CW program. This was interesting so I used the cool switch to bring up CWA, clicked the Ins button and added a type of MS Word. Then I clicked on Insert for Code Description where I entered a description, and below it I pasted the actual code. Now I have it for whenever I need it.

Have you ever found that a piece of code you've been using for some time isn't working exactly as you suspected it would? First you have to find every place you've used the code. Then you have to write the new code. A better way might be to save the correct code as a snippet in the code library. Then simply locate each place where you have the bad code; highlight it; and then paste the code from the code library. This way it's right every time. Even smarter would be to place a comment as the first line of the code snippet. This way if you ever have to find the code to change it you have something to search for.

Error Helper

I found the Error Helper to be an interesting combination of reference tool combined with source code generator. I find it difficult, if not impossible, to remember all of the error codes that I need to check for. Worse, I rarely find the correct error code on my first look up. So when I saw this feature I was interested to try it. I highlighted the File Open command type and double clicked File Not Found from the list of Errors for Open. Then I hit the To Clip button and, just for you, I pasted the result below.

CASE ERRORCODE()
OF NoError !0 No Error Occured
OF NoFileErr !2 File Not Found
ELSE
STOP('Error: '&ERRORCODE()&'-'&CLIP(ERROR()))
END !CASE Error

Now I can fill in my code and I'm done. This is far simpler than thinking!

The Help Organizer

Do you use a bunch of third-party tools? If so, you know the occasional problem of finding their help files. Or even if its not lost, you can't invoke it from the point where you are. Cool Switch to CWA and start the Help Organizer. Now, the first time you use it, you'll have to ask it to search for help files, but after that you can simply double-click on a specific help file and it starts. This is a wonderful feature.

Message Maker

I was working on an application where I wanted a process to pause until the user entered a floppy in the drive. This was an opportunity to try the Message Maker. The message maker makes it easy to create a message without have to write code. The tools of CWA have a similar feel about them so for this message I did not have to read the help. I typed a title for the message and then the text of the message. Next I copied it to the clipboard and pasted it into my source code embed. The code looked like this.

BEEP(BEEP:SystemDefault) ; YIELD()
CASE MESSAGE('Please insert a floppy in your drive', |
'I''m waiting for you', , |
BUTTON:OK, BUTTON:OK, 0)
OF BUTTON:OK
END !CASE

The message maker, among other features, permits you to play a sound at the time the message appears, add an icon to the message, and select a variety of buttons for the message box. An interesting aspect of message maker is its ability to rename the buttons appearing on a message box. For example, in the above example instead of an OK button I wanted a button that said "Floppy Ready." I clicked on the rename button an inserted my desired "renamings." Here's the generated code after this change.

BEEP(BEEP:SystemDefault) ; YIELD()
LOCALE('CLABUTTON','Floppy Ready,,,,,,,')
Btn#=MESSAGE('Please insert a floppy in your drive', |
'I''m waiting for you', , |
BUTTON:OK, BUTTON:OK, 0)
LOCALE('CLABUTTON','OK,&Yes,&No,&Abort,&Retry,&Ignore,Cancel,&Help')
CASE Btn#
OF BUTTON:OK !Renamed: Floppy Ready
END !CASE

Just a warning. After renaming buttons, they stay renamed until you "unrename" them. Follow the help directions and you should have no problem.

Additional Features

String Builder.

This feature makes it easy to create relatively complex concatenations of strings. For example suppose your file has separate fields for: Prefix, First Name, Middle Initial, Last Name and Suffix. The string Builder makes it relatively easy to create the code to combine these fields for a field called GLO:NAME. This is most effectively used with the Dictionary feature. You can drag the various fields into the string builder, dropping them into a work area. So, for example, I drag each of the fields mentioned above into the work area. I end up with something that looks like this:

{CLIP(CUS:PREFIX)} {CLIP(CUS:FIRST_NAME)} {CLIP(CUS:MIDDLE_INIT)}
{CLIP(CUS:LAST_NAME)}{CLIP(CUS:SUFFIX)}

Then I press the To Clip button and paste the resultant code into my app. It appears like this.

CLIP(CUS:PREFIX)&' '&CLIP(CUS:FIRST_NAME)&' '&CLIP(CUS:MIDDLE_INIT)&' '& |
CLIP(CUS:LAST_NAME)&CLIP(CUS:SUFFIX)

You will notice that now there are ampersands and spaces properly placed between the items and remember, I did this simply by dragging the items to the work area. I did no typing and therefore produced no typing errors.

Template Code Builder

This is a difficult feature to write about. To quote the help documentation, "This one was hard to name and I'm not sure I have a good one. The basic idea is that to make template generated procedures do some things you need to work with the template equates and variables." I can only speak about how I see it.

This feature gives you the ability to create the correct code for certain standardized functions that all of our programs perform. For example, for a long time I could not remember the code for causing a window to be "refreshed." Here I can click on the button "TPL Code" and choose "Refresh Window." The following code is placed into a work area.

ForceRefresh=True
DO RefreshWindow

There is a series of such standardized code that you can use. The feature may have greater use but it's not obvious to me.

Keycode Helper

Do you remember the equates for a key you press. For example, what is the equate for "press the control key plus the shift key plus the letter S"? Using keycode helper you'll find that it is "CtrlShiftS." Additionally, you can clip this to the clipboard or clip it as well as some controlling code to the clipboard. For example, PRESSKEY(CtrlShiftS).

Color Designer

This feature allows you to try out color combinations before using them in your application. You can see how various color combinations look on various controls including listboxes, prompts, etc.

Map Viewer

While I did not need this feature during the review, I often have the problem of being in an embed and not remembering the name of a procedure I need to invoke. I can simply Cool switch to the CWA and bring up the map viewer. Then I can view the main CLW file for the app and be presented with a map list.

Window Key Analysis

This feature allows you to spot conflicts among the Alt, Key and Alert assignments as they appear in a window. To use this, copy a window definition to the clipboard. Cool switch to CWA and press the Key Analysis button. You will be presented with a list of your key assignments and any conflicts.

Stick Note

This feature allows you to keep a sticky note on your CWA screen to hold various reminders and other information.

Other Observations

There is a nice consistency of layout and functionality between the different tools, and there are some interesting interactions between certain tools. Quick Insert is a particularly nice feature found in several of the tools. This permits quick and easy insertion of common Clarion functions into the specific work area of a tool. This list is editable by you, so you can add or change this list, although I suspect most will use it unchanged.

The CWA String Builder

The dictionary interfaces quite nicely with other tools. For example, you can drag fields one by one to the String Builder. This makes for quick development of code. Then created code can be pasted into the Code Library for permanent storage.

Additionally, CWA makes effective use of the clipboard. It permits two modes of operation. The way you might expect is that items are copied to the clipboard, but there is another method. You can also add information to the clipboard. Using this method you can use multiple CWA tools, and for each tool you can paste a result to the clipboard. Then, in your application, you can paste the multiple chunks of code. Nice feature!

Suggestions for Improvement

The Demo mode of CWA

The current CWA demo mode is brutal. CWA has some wonderful features and I have to believe that a person who can create CWA can create a useable demo of the program. Simply put, Demo mode just doesn't work. The idea of the demo is fine. Allow users to try most aspects of the program for up to one hour, then close the program, requiring the users to re-open the program to continue. This would be fine but it just isn't what happens. Press any button. You will either get the one-hour message followed by a closing of the app or, if the feature is available in the demo, the feature will open. Finish using the feature and try another feature, and now you will get the one hour message and the app will close. This means that the user cannot realistically use the demo to try out the features.

Because of the intense richness of this product, the full documentation (not just help) should be available in the demo.

Carl Barnes reports that about the time you read this there should be a new version of the demo available for download. So for those of you who have tried the demo in recent months and been extraordinarily frustrated perhaps its time to try it again.

CWA help

Much of the help is quite clear, but not all. For example, the help for the dictionary functions does not make clear whether the Update Dictionary button is an update of your DCT file or whether it is an update of the CWA DIC file. By the way, in case you care, it updates the DIC file.

CWA documentation

Many of the third-party vendors argue that it is difficult, if not impossible, to provide documentation that is separate from the help file. I'm not convinced. But if it is too difficult, then at least provide us a copy of the help file in RTF format. That way we can print it out if we want a paper copy.

Dictionary and File Viewer

On opening a dictionary, four additional buttons become available on the toolbar. From left to right these are; Update Dictionary, Minimize Dictionary and File Views, Restore File Views, and Close Dictionary and File Views. The Restore File Views button does not work properly because once the minimize button has been pressed, the four buttons disappear so the Restore button is no longer available. This should be fixed.

Help Organizer

This is a fine tool but, as currently implemented, there appears to be no way to search multiple drives for help files. It would be a significant improvement to add multi-drive search capabilities.

Template Code

This tool needs either better documentation or further refinement. That is, either I can't figure out how to make effective use of it or it's not a useful as it might be. For example, it could be useful for writing standardized code for the code library and therefore it would be useful to have functions (numeric and string) included.

Template Registrar

There is no button for this tool. You find it as the last item listed on the Tools menu. This tool allows you to add one or more templates to your template registry. Now I know I'm probably asking for the impossible, but isn't that my job. It would be really useful to see what templates are currently installed in your registry and be able to then select templates to uninstall. Just a thought, Carl (he thinks with a malicious grin).

The Ratings

I found this a very useful program. If you write significant amounts of code, you'll find it very useful. If you rarely write code - for those few times you do, you'll find it essential. When Clarion4 is released, Carl will have an opportunity to review how his product can have an impact. It seems like a natural to use with OOP programming practices.

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

Article comments

Post a comment

You must be logged on to post comments.