Why use CLACom for Windows

GAP Development Company has been providing Serial Port Communications solutions since 1987. We are experts in this field.

Starting with our Bulletin Board software and then CLACom For DOS (which is coded entirely in Assembly Language) we continued on to include support for what TopSpeed said was impossible - Protected Mode interfacing to the Serial Ports.

We brought our experience to the Windows arena and CLACom For Windows was born.

An Asynchronous Serial Communications Library that provides sophisticated access to the Serial Port, far beyond the two functions that Window's provides to Send and Receive data.

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. Such uses include Sending Ordering Information and Accessing Medical Records. Also used by Companies that need to provide Dial Up Access for their customers to provide, for instance, Financial Data, Real Estate Information, and other data that is processed by Clarion's powerful database manager.

CLACom is more than a mere "wrapper" around the Windows Communications API. Instead of a single function to Retrieve characters from the serial port (as provided by the API and WinEvent), CLACom provides over 10 powerful functions to retrieve this data.

CLACom takes the drudgery out of Serial Communications. It accounts for the differences in 16 and 32 bit Windows and even the differences between Windows NT and Windows 95/98. CLACom shields the developer from the Windows API to provide High Level functionality around the Low Level communications routines in the API.

Unlike a VBX or an ActiveX Control (or any other Communications Library), CLACom is written exclusively for Clarion. No need to write function prototypes. No need to learn Basic or "C" to understand the example code in the Manual. Example Programs are written in Clarion, not in "C" or Basic.

Many tasks associated with remote communications are pre-written. Template Procedures are provided to Dial a Phone Number and Answer the Phone. A fully customizable Terminal Emulator is included. Need to display a drop down list of supported Baud Rates? Already written - simply place the control onto your Window.

Save weeks of time by not having to prototype the Windows API or learn VBX or ActiveX "methods". Need an example of how to utilize a certain function? It's there, in the printed manual, written in the Clarion language you are already familiar with.

Several powerful, fully functional, example programs are already written. They can be used as a Template for your own project. All of them are easily customizable because they are written in Clarion and fully commented.

The main difference is that CLACom Lite does not include File Transfer capability, Terminal Emulation, and some of the Templates (pre-written procedures).

CLACom includes a Printed Manual. You will need to print the CLACom Lite Manual yourself (from either the supplied PDF file or the Windows Help file).

Refer to the Functions By Category chart ** LINK ** and the Feature Comparison chart ** link ** for more information about the differences between the Lite version of CLACom and the Full Featured version.

It should be noted that the Lite version is not a "crippled" version of CLACom. It is the same Communications Library with the so called "advanced features" removed. This results in a smaller size for the Library.

WinEvent is a fine product and worthy of your consideration. WinEvent includes other, non RS-232, functionality and should not be excluded from your Clarion Toolbox if you need any of the features it provides. Our comparison is based solely upon the Serial Port Communications functionality which is derived from the freely available documentation.

CLACom Lite carries with it our years of experience interfacing with Serial Ports and Windows. We bring this expertise to you at reduced cost so that you do not have to pay for the "advanced features" that you do not need.

WinEvent does not support Receive and Transmit Buffer sizes in 32 bit Windows, claiming that the buffer sizes are not necessary. The fact is, if you set the Buffer sizes too small, then 32 Bit Windows will increase the size of the Buffers to its own optimal values - which may not be what you want. Win 98 uses a default Receive buffer size of 4096 bytes and a default Transmit buffer size of 0 bytes - these are the sizes you end up with if you omit (do not specify) buffer sizes. CLACom Lite uses optimal buffer sizes in both 16 and 32 bits and you may change these sizes if you wish.

CLACom Lite supports CTS/RTS and DSR/DTR Hardware Flow Control (as well as XON/XOFF if you need it). Most devices that you attach to the Serial Port will need some sort of Hardware Flow Control, with proper timeouts. Modems, for instance, require CTS/RTS flow control and Printers generally use DSR/DTR flow control.

It is often useful (in fact mandatory) that your program check to see if an attached device is turned on and ready to receive data. The only way for your program to do this is to check the Modem Status Register (which is a misnomer since it applies to any device, not just modems). CLACom Lite provides a low level function as well as a Template Procedure (that takes care of all the low level details) to accomplish this with. WinEvent calls this sort of Status Checking "advanced programming features" and makes them available only in 32 bit programs.

CLACom Lite provides several methods of Reading and Writing data to the Serial Port. WinEvent supports a single Write procedure and a single Read procedure.

CLACom Lite is intelligent enough to know that if you try to send 100 bytes and there is only room in the Transmit Buffer for 50 bytes, it will send each byte as space becomes available. The Win API (and presumably, WinEvent) will take your 100 bytes, try to place it in the Transmit Buffer, and if doesn't all fit, will tell you how many bytes did fit. CLACom insures that your data is sent exactly as you intended (all 100 bytes in this case).

Refer to the Feature Comparison chart ** LINK ** for more information about the differences between the Lite version of CLACom and WinEvent.

You certainly can!

You will need a Win 16 and a Win 32 API Reference ($80 - already more than the cost of CLACom Lite). You will need to Prototype the COMM API Functions. Then you will need to write the code, as it is not a simple matter of calling a Win API function and expecting it to do what you want.

16 Bit Windows treats Comm Ports as Devices. 32 Bit Windows treats them as Files. You'll need to know the difference and program accordingly. There are a lot of differences, not just between 16 and 32 bit Windows, but between NT, Win 95/98, 16 bit programs under a 32 bit Operating System, and Windows 2000 and XP.

Let's assume that you are only interested in writing 32 bit programs using the 32 bit Communications API.

You'll need an API Reference (which you probably already have - and if you don't, the Reference manual itself will cost you more than CLACom Lite). You can use the API Tool Kit that comes with Clarion to produce the function prototypes so you don't have to write them yourself.

You are now faced with the task of interfacing to these Comm functions. Now what do you do?

The first thing you have to do is create Event Handlers. There are three of them. We've now moved beyond the basic API functions that you thought were associated with Serial Ports, and the API reference that you have probably doesn't tell you this. Why? Because in 32 Bit Windows, these Serial Ports are treated as Files and you must now study up on the File I/O API.

The second thing you have to do is call CreateFile. Remember that the Serial Port is treated as a File, not a Device. Whoops, wait a second. Your Call to CreateFile failed because you are trying to open COM10 or higher! What's the deal here? Humm, special formatting required.

Ok, we have the Serial Port open, now what? That's it, right? Open the port and send data to it? Nope. Now you have to set the Time Outs. Next you have to set the Buffer Sizes. Then you have to set the Baud Rate, Data Bits, Parity, Stop Bits, and Flow Control.

Did your program make it this far? OK, now its time to send some data. No problem, you'll simply use WriteComm and send some bytes out the Serial Port. Whoops! Not that easy. This is 32 bits, remember? Serial Ports are treated as Files, so we need to study up on the WriteFile, GetLastError, and GetOverlappedResult API functions. Remember those Event Handlers that had to be configured before opening the Port? Well, they are coming into play now and have special meaning, and if you don't get it right, your program will not work on Windows NT.

If you've gotten this far implementing what has been discussed, then in Programming Hours, you have spent well over 10 times the price of the full version of CLACom, and you are not finished yet!

It is time to retrieve data from the Serial Port. By now you've figured out that you use ReadFile instead of ReadComm. But wait! You call ReadFile and your program suddenly locks up because ReadFile never returns. Humm, did you set your Time Outs correctly? What happens if there is no data available? Must have something to do with those timeout settings? What about Flow Control and the timeout settings associated with it?

What happens if there is a Serial Port Error? Did you know that Windows will virtually shut the port down if there is a Receive or Transmit error? If you don't do something about those errors, you won't be able to send or receive another byte.

This is supposed to be easy, right? It's all right there in those expensive API books we purchased! The books tell you what the API functions are but they don't tell you how to use those functions properly.

If you are simply writing a program for your own use, then by all means use the Win API to the best of your abilities. If you are writing software that will be used on unknown hardware, Windows 3.x, 95/98, NT 3.x, 4, 2000, and XP, then use CLACom and save yourself a lot of grief and frustration - not to mention the days or months you will spend trying to figure this API out.

Thanks for visiting GAP Development
code development in Dana Point, California