home *** CD-ROM | disk | FTP | other *** search
/ Programmer 7500 / MAX_PROGRAMMERS.iso / PASCAL / COMM_TP4.ZIP / COMM_TP4.DOC next >
Encoding:
Text File  |  1989-02-02  |  11.4 KB  |  292 lines
  1.  
  2.       Comm_TP4.PAS Ver. 1.01, RS-232 Support for the IBM PC - Documention
  3.  
  4.                           Author:  Kevin R. Bulgrien
  5.                                    February, 1989
  6.  
  7.                             LeTourneau College
  8.                             Microcomputer Services
  9.                             P.O. Box 7001
  10.                             Longview, TX 75607
  11.  
  12.  
  13. INTRODUCTION
  14.  
  15. This utility is an answer to the many public domain serial port routines which
  16. I have acquired in the quest for good RS-232 support under Turbo Pascal. Unlike
  17. the others, this one works.  Not only does it work, but it also allows you to
  18. use both COM1 and COM2 at the same time.  Designed to be relatively simple and
  19. easy to use, I hope many will benefit from it.
  20.  
  21. This code only works under Turbo Pascal versions 4.0 and 5.0.  For functionally
  22. equivalent routines that work under Turbo Pascal 3.0, look for COMM_TP3.  Also,
  23. a Turbo C version called COMM_TC2 is available.  While it was written for Turbo
  24. C 2.0, it will probably also work for lower versions.
  25.  
  26.  
  27. DISTRIBUTION POLICY
  28.  
  29. This package may be used in any application without restriction, although I do
  30. ask that it is not distributed in a modified form unless you give credit where
  31. credit is due.  This document must always accompany the software as well.  The
  32. files which make up this package are called COMM_TP4.PAS and COMM_TP4.DOC.
  33.  
  34.  
  35. CREDITS
  36.  
  37. Credit for this product must go to the various authors who showed me that if I
  38. wanted something that worked, I would have to write it myself - I won't bother
  39. to mention their names.  The most credit, however, must go to the book "Systems
  40. Software Tools" by Ted J. Biggerstaff.  I was amazed to find a book that so
  41. clearly outlined the IBM PC interrupt and serial port hardware.  The world of
  42. IBM PC technical information is a desert, and this book is a rare oasis in the
  43. midst of it.
  44.  
  45.  
  46. FEATURES
  47.  
  48.  - Interrupt driven receive routine
  49.  - Easily expandable interrupt routine
  50.  - Uninstalls the interrupt handlers on abnormal program termination
  51.  - Carrier Detect monitoring for modem support
  52.  - COM1 & COM2 simultaneously supported
  53.  - Example TTY and Port Setup routines included
  54.  - Easy to use even if you don't understand how it works
  55.  - Turbo Pascal 4.0 & 5.0 compatible source code
  56.  - The price tag reads "FREE"
  57.  
  58.  
  59. DISCLAIMER
  60.  
  61. While the author has extensively tested the routines in this package, he will
  62. not be held responsible for any consequence arising from the use thereof.  It
  63. is the responsibility of the user to determine whether or not the enclosed
  64. routines will satisfactorily perform the required functions.
  65.  
  66.  
  67. GETTING STARTED - DOES IT REALLY WORK?
  68.  
  69. If you want to prove that these routines really work, just run the program as
  70. it is distributed.  What you will see is a crude terminal emulation program
  71. that is capable of receiving information from both COM ports at the same time.
  72. The screen echoes data from the "logged" COM port and buffers the data from
  73. the other port.  When the other COM port is logged, the buffered data is sent
  74. to the screen.  Also provided is a setup routine that lets you select a baud
  75. rate from 110 to 38400.  The other protocol attributes are also selectable.
  76.  
  77.  
  78. SETTING COMM_TP4 UP TO USE IN YOUR OWN PROGRAMS
  79.  
  80. Important Note:  Never compile interrupt driven routines with the stack
  81.                  checking code enabled.  Doing so will cause the program to
  82.                  crash whenever the interrupt is invoked.
  83.  
  84. In order to use the serial routines, you may remove all of the extra code that
  85. is included for the TTY example routines.  It is not important for you to
  86. understand how the routines work, but the following declarations are not
  87. optional and are required for normal RS-232 operation:
  88.  
  89.      USES DOS, CRT;
  90.  
  91.      CONST
  92.        MaxSize = 511; { This is the input buffer size, and you may change it }
  93.  
  94.      TYPE
  95.        INS8250 = RECORD
  96.                    THR : INTEGER;
  97.                    RHR : INTEGER;
  98.                    DLL : INTEGER;
  99.                    IER : INTEGER;
  100.                    DLM : INTEGER;
  101.                    IIR : INTEGER;
  102.                    LCR : INTEGER;
  103.                    MCR : INTEGER;
  104.                    LSR : INTEGER;
  105.                    MSR : INTEGER;
  106.                  END;
  107.  
  108.       ComSettingsRecord = RECORD
  109.                             Baud : BYTE;
  110.                             Parity : BYTE;
  111.                             Stop : BYTE;
  112.                             Bits : BYTE;
  113.                           END;
  114.  
  115.        ComSettingsType = ARRAY [1..2] OF ComSettingsRecord;
  116.        ComBuffersType = ARRAY [1..2, 0..MaxSize] OF BYTE;
  117.  
  118.      CONST
  119.        RS232 : ARRAY [1..2] OF INS8250 = ( ( THR:$3F8; RHR:$3F8; DLL:$3F8;
  120.                                              IER:$3F9; DLM:$3F9; IIR:$3FA;
  121.                                              LCR:$3FB; MCR:$3FC; LSR:$3FD;
  122.                                              MSR:$3FE ),
  123.                                            ( THR:$2F8; RHR:$2F8; DLL:$2F8;
  124.                                              IER:$2F9; DLM:$2F9; IIR:$2FA;
  125.                                              LCR:$2FB; MCR:$2FC; LSR:$2FD;
  126.                                              MSR:$2FE ) );
  127.  
  128.      VAR
  129.        IntInstalled : ARRAY [1..2] OF BOOLEAN;
  130.        OldIntVector : ARRAY [1..2] OF POINTER;
  131.        InHead, InTail : ARRAY [1..2] OF WORD;
  132.        Carrier : ARRAY [1..2] OF BOOLEAN;
  133.        ComSettings : ComSettingsType;
  134.        InBuffer : ComBuffersType;
  135.        ExitSave : POINTER;
  136.        MaxPorts : WORD;
  137.        Regs : REGISTERS;
  138.  
  139.      PROCEDURE DisableInts; INLINE ($FA);
  140.      PROCEDURE EnableInts; INLINE ($FB);
  141.      PROCEDURE SetupRS232 (Com, Baud, Parity, StopBits, DataBits : BYTE);
  142.      PROCEDURE IntHandler; INTERRUPT;
  143.      PROCEDURE InstallInt (Com : BYTE);
  144.      PROCEDURE RemoveInt (Com : BYTE);
  145.      PROCEDURE RemoveIntOnExit;
  146.      FUNCTION Equipment : WORD;
  147.  
  148. The following declarations are optional in that you can write your own routines
  149. to actually send and receive RS-232 information in the form that you wish to
  150. send it.  They are not optional if you do not write your own replacements.
  151.  
  152.      PROCEDURE WriteCOM (Com : BYTE; Data : STRING);
  153.      FUNCTION ReadCOM (Com : BYTE) : CHAR;
  154.  
  155. These routines are relevant only to the TTY emulation, but you may be able to
  156. use them to better understand how to use the actual port routines:
  157.  
  158.      PROCEDURE SetUpPort (Com : BYTE);
  159.      PROCEDURE TTY (LocalEcho : BOOLEAN);
  160.  
  161. The main program MUST include the following code as it will cause the program
  162. to safely remove the interrupt handlers no matter how the program terminates:
  163.  
  164.      BEGIN
  165.        ExitSave := ExitProc;
  166.        ExitProc := @RemoveIntOnExit;
  167.        IntInstalled [1] := FALSE;
  168.        IntInstalled [2] := FALSE;
  169.  
  170.        { MaxPorts provides error checking in some of the required procedures }
  171.  
  172.        MaxPorts := (Equipment AND $0E00) SHR 9;
  173.  
  174.        { The rest of your program body goes here }
  175.  
  176.      END.
  177.  
  178.  
  179. HOW TO USE THE INTERRUPT HANDLERS IN YOUR PROGRAM
  180.  
  181. At any time you may invoke SetupRS232 to change the settings of the COM ports.
  182. Unless you are sure the port is already set up correctly, you should invoke
  183. SetupRS232 before you install the interrupt with InstallInt.
  184.  
  185. You may install either COM1, COM2 or both with InstallInt at any time and in
  186. any order.
  187.  
  188. You may uninstall either COM1, COM2 or both with RemoveInt at any time and in
  189. any order.
  190.  
  191. To read data that has come in from the port, one of the following is required:
  192.  
  193.      1) FUNCTION ReadCOM (Com : BYTE) : CHAR;
  194.  
  195.         where Com is 1 or 2 for COM1 or COM2.  If no data is available, this
  196.         routine waits until it arrives.
  197.  
  198.      2) DisableInts;
  199.         CharReady := InTail [Com] <> InHead [Com];
  200.         EnableInts;
  201.  
  202.         where CharReady is a user defined BOOLEAN that will be TRUE if data is
  203.         waiting in the buffer or FALSE if not data is waiting.
  204.  
  205.         DisableInts;
  206.         CharData := CHR(InBuffer [Com, InHead [Com]]);
  207.         InHead [Com] := (InHead [Com] + 1) MOD (MaxSize + 1);
  208.         EnableInts;
  209.  
  210.         where CharData is a user defined CHAR variable that will contain the
  211.         next item in the buffer IF AND ONLY IF CharReady is TRUE.  The item is
  212.         removed from the buffer with the statement following the assignment.
  213.  
  214.         NEVER omit the DisableInts and EnableInts from these program fragments.
  215.         To do so would cause the program to operate unpredicatably.
  216.  
  217. To write data to the port, use one of the following methods:
  218.  
  219.      1) PROCEDURE WriteCOM (Com : BYTE; Data : STRING);
  220.  
  221.         where Com is the 1 or 2 for COM1 or COM2 and Data is either STRING or
  222.         CHAR data to be sent to the port.  This routine will pause until all of
  223.         the data has been sent.
  224.  
  225.      2) PortReady := ((PORT [RS232 [Com].LSR] AND $20) = $20);
  226.  
  227.         where PortReady is a user defined BOOLEAN variable which will be TRUE
  228.         if the port Transmitter Holding Register is ready for a character to
  229.         send to the port.
  230.  
  231.         PortReady := PortReady AND ((PORT [RS232 [Com].MSR] AND $30) = $30);
  232.  
  233.         This statement allows you to see if the CTS and DTR lines indicate that
  234.         the other serial device is ready to receive data.  It may be omitted if
  235.         you do not want to check these lines.
  236.  
  237.         DisableInts;
  238.         PORT [RS232 [Com].LCR] := PORT [RS232 [Com].LCR] AND $7F;
  239.         PORT [RS232 [Com].THR] := ORD (CharData);
  240.         EnableInts;
  241.  
  242.         where CharData is a userdefined CHAR variable that contains a character
  243.         to send to the port.  PortReady MUST be TRUE before placing this data
  244.         in the Transmitter Holding Register otherwise the previous data item
  245.         will be lost.
  246.  
  247.         NEVER omit the DisableInts and EnableInts from these program fragments.
  248.         To do so would cause the program to operate unpredicatably.
  249.  
  250.  
  251. SUPPORT
  252.  
  253. User support may be obtained by contacting me via  the LeTourneau College BBS
  254. at (214) 237-2742.  The BBS runs 24 hours a day and accepts calls at 300, 1200,
  255. and 2400 baud.  Since I am the SysOp of this board, this is the fastest way to
  256. reach me.  My GEnie mail address is K.BULGRIEN, but money being at a premium,
  257. I do not always check in on a regular basis.  I may also be reached during
  258. business hours at (214) 753-0231 ext. 352.
  259.  
  260. Support will be limited to clarification of the routines I wrote.  I will not
  261. debug your routines or enhance my routines for your specific application.
  262.  
  263.  
  264. UPDATES
  265.  
  266. I will place updates of the enclosed routines on LeTourneau College BBS at
  267. (214) 237-2742.  The BBS runs 24 hours a day and accepts calls at 300, 1200,
  268. and 2400 baud.
  269.  
  270. I will also place updates in the BORLAND RT on the GEnie information service.
  271.  
  272. Possible updates may include:
  273.  
  274.      1) An interrupt driven transmitter
  275.      2) More complete support of the Modem Status interrupt
  276.      3) Support of the Line Status interrupt
  277.      4) Support additional COM ports
  278.      5) Miscellaneous enhancements
  279.      6) Bug fixes
  280.  
  281.  
  282. VERSION HISTORY
  283.  
  284.  1.00  11/88  The original version placed in the Borland Roundtable on GEnie.
  285.  1.01  02/89  Bug fix in Procedure RemoveInt.  It correctly uninstalled the
  286.               interrupt code except that it would disable all IRQ interrupts
  287.               except the one used by the specified COM port.  (An AND instead
  288.               of an OR in the statement writing to PORT [$21].  Uploaded the
  289.               new version to GEnie to replace the old one.
  290.  
  291. THE END
  292.