Comm_TP5.PAS Ver. 2.50 - RS-232 Support for IBM Compatibles - Documentation (c) Copyright, 1989, 1990, 1991 Kevin R. Bulgrien January 27, 1999 Mail Address: Kevin R. Bulgrien EMail: kbulgrien@att.net P. O. Box 563 Longview, TX 75606 Other: Kevin R. Bulgrien c/o K. A. Bulgrien Obtain latest address 1700 Sheldon Road information by EMail. Sandusky, MI 48471 INTRODUCTION Back in 1986, I needed some serial port communications routines that would work with Turbo Pascal. My search for a good library resulted in my obtaining about twelve public domain or shareware serial port handlers. It was amazing to see so much code which either: 1) did not perform satisfactorily, 2) had inadequate documentation, 3) was so complex that only an expert could use it, or, 4) did not contain modifiable source code. The one that would have satisfied my meager requirements had absolutely no documentation, and had a bug that would lock up the computer the first time you used it after a cold boot. This utility is an answer to all of those serial port routines which I acquired in the quest for good RS-232 support under Turbo Pascal. I finally realized that I would need to write my own routines in order to get the kind of support that I needed. Well, I could have bought one, but I couldn't bring myself to do that. It has taken several years of evolution, but now, I feel confident that many would-be serial port programmers will find this package very useful, and even easy to use. It has not always been so. My first versions were hard to use, especially since Turbo Pascal version 3.01 did not allow units. Each successive version has become better and better, until I now have a product which I feel I can be justifiably proud of. I feel confident that most programmers will be able to understand why I think they will like Comm_TP5. It is feature-rich and internally complex, but this complexity has been successfully hidden behind a remarkably simple interface. The documentation has material for both the casual user, and also for those who want to know exactly what is going on inside of Comm_TP5. This code works under Turbo Pascal versions 5.0 and above. Similar routines, though more primitive, are available for Turbo Pascal 4.0 and Turbo Pascal 3.0 routines are distributed under the names Comm_TP4 and Comm_TP3 respectively. A Turbo C version called Comm_TC2 is also available. While it was written for Turbo C 2.0, it will probably also work for lower versions as well. My future work will probably consist of porting Comm_TP5 to other programming language environments. DISTRIBUTION POLICY The following files must all be present whenever this package is distributed: COMM_IO5.H - Turbo Pascal include file COMM_IO5.PAS - Turbo Pascal include file COMM_TP5.H - Turbo Pascal include file COMM_TP5.PAS - Turbo Pascal TPU source code COMM_TP5.ASM - Turbo Assembler support source code COMM_TPA.OBJ - Pre-assembled OBJ file with serial interrupt COMM_TPB.OBJ - Pre-assembled OBJ file without serial interrupt COMM_TP5.DOC - Documentation for this complete code library COMM_TTY.PAS - Demo terminal emulator which uses Comm_TP5 Comm_TP5 may be used without any restrictions if all of the following conditions are met: Only free, or public domain, software applications are created with this code library. Source code is not included with the completed product. Minor restrictions apply under the following conditions: If only a compiled Comm_TP5.TPU file is distributed with your free or public domain application, this document file must be included with the completed product. Additionally, you shall clearly document any changes that you made to the original version of Comm_TP5. If your free or public domain application is distributed with either modified or unmodified Comm_TP5 source code, this entire, UNMODIFIED set of files must be included with the completed product. A one-time registration fee of $25.00 shall be paid to me at the above address if any of the following conditions are met: This package is to be used to develop software which will be sold or released with a shareware notice. You are being paid for your services while you develop application(s) that use Comm_TP5. All paid registrations will be acknowledged by a receipt which will be sent to the entity which pays for the registration. Because this source code is a platform from which one can build other tools, no entity is exempt from payment of a registration fee in the event that Comm_TP5 must be modified to make it fit a specific application. Considering the fact that commercial serial port libraries cost $100 and above, this is a very reasonable charge. A great deal of effort has been expended in its development. I specifically prohibit any distribution of the source code where a disk fee is charged, unless I have granted written permission to the specific vendor making such a charge. A general usage fee to an electronic bulletin board system is not considered to be a disk fee. I also specifically prohibit any person, or entity, from claiming copyright on this material without first obtaining my personal, written consent. Monetary compensation to me will be required for any such agreement to be valid. This does not infer that you may not copyright material which uses this product. DISCLAIMER While I have extensively tested the routines in this package, I will not be held responsible for any consequence arising from the use thereof. It is the responsibility of the user to determine whether or not the enclosed routines will satisfactorily perform the required functions. This software directly accesses the Intel 8250 UART as well as the Intel 8259 interrupt controller hardware. Though they are IBM standards, it is possible that some manufacturers could use different hardware to supply these functions, in which case, program compatibility might be questionable. This is true for any software which accesses hardware directly in order to obtain higher levels of performance. Additionally, because this software directly accesses the computer hardware, it may conflict with other hardware dependent software. Again, it is the user's responsibility to: (1) determine if conflicts exist, and (2) find ways to avoid using the ambivalent programs together. CREDITS All of the enclosed code is completely original to me, and has not been stolen, borrowed, or purchased from any other source. Some credit, though, must go to the various authors who showed me that if I wanted something that worked, I would have to write it myself (or pay for a code library). Credit for the information on the IBM compatible hardware goes to the Prentice-Hall book "Systems Software Tools" by Ted J. Biggerstaff. I was amazed to find a book that so clearly outlined the IBM PC interrupt and serial port hardware. The world of IBM PC technical information is a desert, and this book is a rare oasis in the midst of it. Additionally, credit also goes to the "DOS Programmer's Reference" by Terry R. Dettmann, which is published by the QUE corporation. I would recommend it to any programmer who needs a good DOS or BIOS reference. FEATURES - Assembly language support for efficiency - Complete, modifiable, interrupt driven routines - Convenient TPU format keeps your code uncluttered - Run-time allocation and configuration of the port handlers - Easy to customize for your hardware, and software requirements - Uninstalls the interrupt handlers on abnormal program termination - Number of COM ports limited only by CPU speed and available memory - The TPU is less than 8K when fully debugged (error checking off) - Carrier Detect & Ring Indicator monitoring for modem support - Example TTY and port setup routines included - Optional error checking and error messages - Extensive documentation for software use - Heavily commented source code DESIGN PHILOSOPHY This is a rather grand heading, but I think now is a good time to share the philosophy used while writing this software. This, along with a look at the code and the rest of the documentation, will help you to decide if Comm_TP5 is for you. Perhaps one of the most important guiding principles I have tried to abide by can be summed up with a KISS (Keep It Simple Stupid). I have seen one or two communications packages that provided a plethora of low level routines which could be used to manipulate every aspect of the hardware. I have deliberately kept this type of code out of Comm_TP5 in the interest of providing a simple-to-use package rather than an it-does- everything one. I figure that if someone knows how to use the low-level operations, they probably know enough to be able to add them to my code. Because most people do not need complicated routines, I felt I would gain more friends by making Comm_TP5 easy-to-use than enemies by not making Comm_TP5 "exhaustive". Most serial applications which I have been involved with were very simple in nature. I did not require a super-high-performance-do-everything- imaginable piece of software, and as a result, I wrote a port handler which reflected my particular needs. As time goes on, I build in more and more capabilities as they become needed. This generally means that Comm_TP5 will be feature-rich, a fact which makes it necessary to accept the fact that it is not fine-tuned for high-speed, high-throughput communications. All that being said, it is still possible to strip power-hungry features to gain higher performance. In summary, I am confident that the routines are high-performance enough to satisfy the bulk of serial port applications. They do not, however, provide a do-everything-imaginable user interface, and yet, there is little that one cannot do. Easy-to-use, flexible, and growing are the key words.