CLACom - from GAP Development

by Drew Bourrut

Published 1999-04-01    Printer-friendly version

The CLACom product has been around for years. It looks it. This is a good thing. I mean it is really polished. There is a manual... A printed... bound... paper manual that you can actually hold in your hands. For that alone I'd like the product. But there's a lot more to like about CLACom.

If you've been reading my reviews you will know that I'm not always happy with the products I review. Sometimes they have glaring gaps in design. Sometimes a feature just doesn't work. But lately I've found myself liking the products I review. In fact, I find myself really liking them. This is not good. It'll ruin my reputation. Here I am a surly individual who has been smiling too much. This product didn't help. I'm still grinning, although not quite so much (more on that later).

But what is CLACom? Here is GAP's answer: "An Asynchronous Communications Library that provides sophisticated access to the Serial Port, far beyond the two functions that Windows provides to Send and Receive data".

Asynchronous Communication, Serial Ports... that means modems, right? Sure, but to quote GAP again as to who can use it: "Any Clarion Developer needing access to a Serial Port in order to communicate with Modems, Scales, POS Displays, Medical Instruments, Bar Code Readers, Robots, PBX devices, just about any device that connects to the computer via the RS-232 Serial Ports. ... Especially useful for Companies that need to transmit data to mainframe computers."

In other words, there's a lot more than just modems to talk to out there. If you do need modem to modem, CLACom also supports all of the common file transfer protocols (including all flavors of Xmodem and Ymodem, as well as Zmodem).

Where I began

Now, I make no claim to being a communications expert. I've written programs that require communication between multiple PCs separated by many miles, but I've always used tools to handle the communications aspect. So I decided to begin by looking to see if there were any demo apps that came with the product. I didn't have to look far.

Included as part of the documentation is a sheet that lists 5 example programs that may be downloaded from the GAP Development website, plus a modem database that contains those pesky initialization strings for over 1000 modems. I chose to look at gtermw32.exe. This program is a fully functional terminal emulator for 32-bit Windows. Since I had a client where I wanted to implement a terminal emulator into a contact manager, it seemed like a good starting point.

[Review Editor's Note: For those who may not have started out in the mainframe world - a terminal was/is basically just a CRT and keyboard that captures keystrokes and displays information, using serial communications to send information back and forth to a host computer (a mainframe or mini) which does all the thinking/processing. A terminal emulator is a program that enables your expensive, fancy PC to pretend it is one of those dumb terminals and talk to a mainframe in the mainframe's own language.]

So first I installed the disks. This went flawlessly. I registered the templates, which were located in a CLACom directory, and this seemingly caused a minor problem that I'll tell you more about later. Once the problem was out of the way I decided to use the demo app (gterm32.app) that came on the installation disks. It compiled without errors. This app produces a "fully functional terminal emulator for 32 bit windows." Next I took a look at the website where I downloaded a self-installing file that contained all of the app demos.

The CLACom product

As I was waiting for the file to complete downloading (2.6megs for the apps) I perused the manual. Remember, a bound paper manual! I found something quite unique to this product. The templates make it easier to use the product, but you can use the product without the templates also.

The templates consist of four control templates for the automatic prompting of default baud rate and protocol. There is a DialNumber template to automate the dialing of a phone number and logging onto a remote system. There is a CheckForPrevInstance procedure template that checks to see if your app is already running and if it is bring it to the foreground. There are these additional procedure templates:

• EncryptBuf - Encrypts and Decrypts the buffer
• GetOpenSaveFile - prompts the user for a file to Open or Save As.
• Initialize Port - Initialize a serial port to the correct Baud rate, parity, data bits and stop bits.
• PhoneMonitor - monitors the serial port and answers the phone when it rings
• WaitForString - monitors the serial port looking for a specified string of characters
• WaitForQueString - waits for multiple strings instead of just one.
• WaitForStringCapture - writes all received characters to the Capture File

The manual

In addition to describing how to get started, the templates and product concepts, there is something of a tutorial that helps you understand how to use the product by describing, in detail, what is contained in one of the demo apps. In addition there are over 100 pages of a detailed reference of all of the functions available with the product.

I wouldn't call the manual perfect, since I ran into some problems with it. For example, there is no true tutorial. I realize that part of the reason for the absence is the very nature of what this product is all about (the ability to create an unlimited variety of communications-based applications). However, one tutorial that would take a person through the steps of using the templates to create any basic application would be a great addition.

My Trial Application

I decided to try to implement two of the CLACom features in one of my programs. I have a client who needs to use a terminal program and has been using Hyperterm but I thought it would be interesting to integrate the terminal program with his contact manager. In addition, I decided to start by adding the phone dialer capabilities to my personal contact manager to gain an understanding of how CLACom worked. Finally, I decided to implement these features using the CLACom templates because I felt it would be time consuming for me to learn all I would need to learn to attempt this without the templates.

The dialnumber functionality

First I read the manual reference on DialNumber and then I began to examine the phone.app thinking this was the place for me to begin. I was wrong. While this app does implement the dialing functionality of CLACom, it does so using pure source code. This was interesting and at another time would provide a wonderful example of how to do this. Howeve,r for now I needed an example of the templates. So I decided to now look at the trmsdi32.app which incorporates both features I needed. After seeing how the template was implemented I was ready to add part one into my app.

Having seen their (GAP Development's) example it was clear to me what I needed to do. I, however, did not precisely follow the instructions in the manual. There are several points that are unclear in how to precisely implement the feature but it becomes quite clear after looking at the example.

Here's what I did:

• I clicked on the procedure/new menu option and selected a procedure name of DialNumber (the name is important).
• I selected DialNumber from the Class CLACom procedure type.
• I now opened my main frame where I was to put my button and added a button to the toolbar.
• I then went to the actions tab for the button and clicked on embeds where I added source code that invoked the DialNumber procedure passing parameter values as indicated by both the manual and the sample app.

Ok... confession time... It didn't work.

I decided to compile the trmsdi32.app and try it. Of course, it compiled flawlessly. At that point I could have gotten frustrated and just had my program call the trmsdi32 program or I could have just imported the procedures into my app. But that would have been cheating... Wouldn't it? After all, my goal was to gain an understanding of how CLACom works.

It took a little time to figure out that I had filled out one of the parameters wrong. I had filled out the code for the initport function, but was attempting to call the initializeport procedure. In addition I failed to use the setport function. Here is the minimal code I found was required (and I do mean minimal).

if setport(COM2,1)
end
if initializePort(COM2,38400,NOPARITY,8,ONESTOPBIT,'ATZ&F^M')
      message('Unable to initialize communications port','Port Error',|
          ICON:Exclamation, Button:Ok)
end
if DialNumber(COM2,4994300,ConnectString,10,60,1)
end
resetport(COM2,1)

One thing I found odd was that if I left out the message under the above "if initializeport" code, the code would not work. This code was placed on the accepted embed for the button.

Two procedures needed to be added to my app. These were: DialNumber and InitializePort. With this in-place it works like a charm. Now on to the Terminal procedure.

The Terminal Procedure.

My client is using Bell Atlantic's online telephone directory. This crude service allows a customer to obtain phone number directly without having to call for an operator. As I had said above, the client had been using Hyperterm but was not happy.

So, now that I had a better understanding of what was going on I proceeded to delete my code and imported the trmsdi32.app procedures into my app. The time I spent doing the first piece on my own definitely was not wasted. I not only had a better understanding of some basic functions of CLACom but I also understood that I'd better import these procedures as it would take quite some time to write all the code.

First I merged the two dictionaries by copy/paste into my contact manager's dictionary. Then I imported all procedures from the trmsdi32.app. I then placed the name of the first procedure to be called (terminal1) into the button actions tab and compiled without error.

emulator window)

So now I have a contact manager with a terminal program making it easy to connect to the Bell Atlantic online directory to get phone numbers for new prospects.

Tech Support

During this whole process I ran into one problem I could not solve. It turned out to be a trivial problem of where to place the templates and where to place the libraries and include files. But it wasn't obvious, thus necessitating several rounds of email to the GAP Development technical support people. Response was extremely quick.

If I were being cynical, I'd think it was because they knew I was doing a review (they did). But it was the quality of the comments and suggestions that made me appreciate the quality of the technical support. A product like CLACom that may be purchased by anyone from programming novice to communications expert requires a special support capability that GAP definitely demonstrated.

Summing up and the ratings

When I began this review I had no idea the roller coaster ride I would be on. I was so enthused by the manual. Then I started to code and realized that, without examining the sample apps, I would be lost. Then I found that even with the sample apps I was lost for a while. But in the end I got everything to work. And for every problem I had, having a bound manual made solving the problem easier.

Some sort of tutorial would raise the documentation rating to excellent. It would also be nice if the placing of the templates, libs, and inc files were easier and, of course, the ease of use rating is partially a factor of my abilities.

Finally, I love the fact that the product (primarily written in C) has tools for the novice and functions for the communications expert.

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

CLACom is available directly from GAP Development via secure transaction at their website: http://www.gapdev.com. CLACom for Windows can also be ordered from TopSpeed Corporation (1-800-354-5444). The price is $249.

GAP also offers reduced version of CLACom (known as CLACom Lite) which sells for $49. It is available for download only, does not include a Printed Manual, File Transfer functionality, or Terminal Emulation. A list of the exact differences is available on their Web site

More information, FAQ's, demos, etc., can be found at their website. You can also download the CLACom For Windows documentation in Windows Help File format to give yourself a detailed overview of the product.

Vendor Comments from Gap Development:

There is a FAQ on our Web Site which explains why it is difficult to offer "step by step" Instructions. That is one reason why we developed so many example programs. In fact, except for the main Terminal Emulator example, all of the others were written for specific customers - free of charge. They told us what they needed and we provided the basic functionality as an example program. We believe the example programs to be the best tutorial. Especially since nearly every line of embedded source code is commented. However, based upon this review, we will attempt to create some sort of "step by step" tutorial so that customers are not faced with the "now what do I do" syndrome. It is not clear why Drew had to place a Message statement in the IF/END construct for the InitializePort call. It shouldn't be necessary and we often use empty IF/END constructs with this particular function in our own programs. We recently added the "PROC" attribute to the InitializePort prototype, since it is rare that an error will occur. For the record: When Drew submitted a problem report to Technical Support, we didn't associate his name with the pending review. He never mentioned the fact and we considered him to be a "regular" customer. He received no special treatment and it wasn't until after the review that his name and the problem report "clicked". We take customer problems seriously and expend whatever effort it takes to resolve the problems - no matter who the customer is. The problem Drew was having with a Template procedure error was resolved - but not to our satisfaction. Drew fixed the problem himself but, in our opinion, his solution was a Clarion work-around. The problem report remains open.

Printer-friendly version

Copyright © 1999-2009 by CoveComm Inc. All Rights Reserved. Reproduction in any form without the express written consent of CoveComm Inc., except as described in the subscription agreement, is prohibited.

Clarion Magazine ISSN 1718-9942