home *** CD-ROM | disk | FTP | other *** search
/ Shareware Overload / ShartewareOverload.cdr / progm / pibasy.zip / README.DOC < prev    next >
Text File  |  1987-11-11  |  9KB  |  228 lines
  1. INTRODUCTION
  2. ============
  3.  
  4. PIBASYNC.ARC is an archive file which contains a set of routines for
  5. implementing fully-buffered asynchronous serial port I/O from Turbo Pascal
  6. on the IBM PC and compatibles.  The routines have been extracted
  7. from my PibTerm v4.0 program and converted for used with Turbo Pascal v4.0.
  8.  
  9. Features of PibAsync:
  10.  
  11.    -- Both input and output buffering for the serial port, resulting
  12.       in improved performance especially under multitaskers
  13.    -- Buffer sizes are user-definable up to 32K bytes each for
  14.       the input and output ring buffers
  15.    -- Speeds up through 38400 baud
  16.    -- Support for Com1: through Com4:
  17.    -- The ability to re-define port addresses, base RS 232 addresses,
  18.       and IRQ lines for non-standard ports
  19.    -- Optional XON/XOFF handling at the interrupt level
  20.    -- Optional CTS/DSR handling at the interrupt level
  21.    -- Machine code (via INLINE) provides respectable speed for
  22.       the basic functions
  23.  
  24. Limitation:
  25.  
  26.    -- Only one serial port is supported at a time.  It would be
  27.       an interesting project for someone to provide multiple
  28.       simultaneous port access.
  29.  
  30.  
  31. ARCHIVE CONTENTS
  32. ================
  33.  
  34. The following 18 files should be present in PIBASYNC.ARC:
  35.  
  36.      ASCII.GLO     --- Some Ascii character set definitions
  37.      ASYINT.ASM    --- ASM source for asynchronous handler
  38.      ASYNCREC.ASM  --- ASM source for receive-a-character routine
  39.      ASYNCSEN.ASM  --- ASM source for send-a-character routine
  40.      DUMBTRM.PAS   --- Sample dumb terminal emulator
  41.      FDELAY.ASM    --- ASM source for 1 ms delay calculation
  42.      FIXBRACK.PAS  --- Routine for neatening .OBJ files produced
  43.                        by the INLINE assembler.
  44.      GLOBTYPE.GLO  --- Global declarations for non-async-related variables
  45.                        needed by async code
  46.      GLOBTYPE.PAS  --- Main program for unit GLOBTYPE.TPU.
  47.      MAKEDUMB.BAT  --- Batch file which calls TPC to compile DUMBTRM.PAS
  48.      PIBASYN1.MOD  --- Asynchronous I/O routines, part 1
  49.      PIBASYN2.MOD  --- Asynchronous I/O routines, part 2
  50.      PIBASYN3.MOD  --- Asynchronous I/O routines, part 3
  51.      PIBASYNC.GLO  --- Global declarations for async-related variables
  52.      PIBASYNC.PAS  --- Main program for PIBASYNC.TPU.
  53.      PIBTIMER.PAS  --- Time of day interface routines
  54.      README.DOC    --- What you're reading now
  55.      TIMEREC.ASM   --- ASM source for receiving character with delay
  56.  
  57. The .ASM files can be assembled with Dave Baldwin's program INLINE.COM,
  58. which converts the assembler source to Turbo Pascal INLINE statements.
  59. (You will need at least v2.11 of INLINE.COM to correctly assemble this code.)
  60. The PIBASYN*.MOD files already contain the processed assembler source,
  61. so you do not need to run INLINE on the .ASM files unless you want to alter
  62. them.
  63.  
  64.  
  65. COMPATIBILITY WITH PREVIOUS VERSIONS
  66. ====================================
  67.  
  68. The calling sequences of these revised routines are largely compatible
  69. with those previously available as part of earlier versions of
  70. PibTerm.  If you used those earlier routines, you should be able
  71. to convert to these (with a resulting increase in efficiency) with
  72. very little trouble.  The major important changes are that the
  73. routines Async_Init and Async_Close now take arguments.
  74.  
  75. In the conversion to Turbo Pascal v4.0, I took advantage of the
  76. new availability of the WORD type to add 38400 baud.
  77. Hence, routines in which the baud rate is passed as an argument
  78. (Async_Open, Async_Reset) now have the baud rate as a WORD
  79. instead of an INTEGER.
  80.  
  81.  
  82. DOCUMENTATION
  83. =============
  84.  
  85. See the documentation block headers for individual routines in PIBASYN*.MOD
  86. for details on the calling sequences and usage of the routines.
  87.  
  88.  
  89. SAMPLE PROGRAM
  90. ==============
  91.  
  92. The DUMBTRM.PAS routine demonstrates how to use the PibAsync routines to
  93. build a dumb terminal emulation program.
  94.  
  95.  
  96. USE OF THE ROUTINES
  97. ===================
  98.  
  99. You may use these routines for any NON-COMMERCIAL purpose whatsoever.
  100. If you change these routines, you MUST make the revised source
  101. available.  Many individuals used the code from previous versions
  102. of PibTerm and incorporated interesting changes in the async routines,
  103. but did NOT make the resulting changes available in source form
  104. so that all of us could benefit.  I take a dim view of that;  I have
  105. made this source code available so that others can learn from what
  106. I have done (and correct my mistakes).  I expect you to provide
  107. the same courtesy in return.
  108.  
  109.  
  110. SUPPORT
  111. =======
  112.  
  113. Please realize that these routines are not a commercial effort and that
  114. I simply cannot afford the time or money to individually support users.
  115. I WILL NOT return phone calls about these routines, and I WILL NOT
  116. fix your code for you.
  117.  
  118. There are a number of commercial packages of asynchronous routines
  119. available for Turbo Pascal.  If you need a package for commercial
  120. development, you should consider one of them.
  121.  
  122. You may send messages to me as indicated below, if you wish.  I will not
  123. necessarily answer all queries individually, however.
  124.  
  125.  
  126. COMMENTS, ETC.
  127. ==============
  128.  
  129. You may send comments to me via one of the following means.
  130. I may not answer all messages individually.  Also, I don't check for
  131. mail in these systems every day, so don't expect that a message
  132. will reach me in less than a couple of weeks (except via BITNET).
  133.  
  134. BITNET:     PIB@NUACC.BITNET
  135.  
  136. CompuServe: CIS ID  72437,62
  137.  
  138. BBSs:
  139.  
  140.      Gene Plantz's BBS   (subscription only)
  141.      Ron Fox's BBS       (312) 940 6496  (open)
  142.      Bob Blacher's BBS   (202) 547 2008  (open)
  143.  
  144. -- Thanks,
  145.    Phil Burns   11/01/86
  146.  
  147.  
  148. Changes for v4.1 of these routines:
  149. ===================================
  150.  
  151. I corrected delay loops by avoiding the use of a Turbo run-time library
  152. variable.  This 1-millesecond delay variable changed meaning at
  153. v3.02 of Turbo, causing the various delay loops in PibAsync to
  154. run incorrectly (for too short a time).  I now calculate and use
  155. my own delay loop value, independent of Turbo's.
  156.  
  157. -- Phil Burns   12/27/86
  158.  
  159.  
  160. Changes for v4.2 of these routines:
  161. ===================================
  162.  
  163. A couple of routines incorrectly left a word on the stack that should
  164. have been popped in cases when the circular buffers were full.  Those
  165. problems have been fixed in this version.
  166.  
  167. -- Phil Burns   01/24/86
  168.  
  169.  
  170. Changes for v4.3 of these routines:
  171. ===================================
  172.  
  173. The send routine incorrectly tested for the wrong circular buffer pointer
  174. when the output buffer was full.  This resulted in output buffer overruns
  175. with lots of attendant nasty problems.
  176.  
  177. -- Phil Burns   03/25/87
  178.  
  179.  
  180. Changes for v4.4 of these routines:
  181. ===================================
  182.  
  183. The code to setup mark and space parity was incorrect.  This has been
  184. corrected in this version.
  185.  
  186. -- Phil Burns   07/20/87
  187.  
  188.  
  189. Changes for v4.5 of these routines:
  190. ===================================
  191.  
  192. I have converted the async routines to a UNIT for v4.0 of Turbo Pascal.
  193.  
  194. To use the async routines, just do a
  195.  
  196.    USES
  197.       DOS, PIBASYNC;
  198.  
  199. You don't need to include the code at all.  Just compile PIBASYNC.PAS
  200. and place the resulting PIBASYNC.TPU in your unit include subdirectory.
  201.  
  202. 38400 baud is now supported.
  203.  
  204. I've altered the character send routine to wait for a slot before 
  205. overwriting an existing buffer character when the output buffer is full,
  206. rather than overwriting and then waiting.
  207.  
  208. The code to support serial ports 3 and 4 has been corrected.  Make sure
  209. to call Async_Setup_Port before using ports 3 and 4, or when you're using
  210. a non-standard port address on ports 1 and 2.  Async_Setup_Port will
  211. now insert the port address you specify at the proper offset from
  212. $0:$400, the address of the 8250.  If you set port address = -1, the
  213. default port address is used; if you set irq = -1, then the default
  214. IRQ is used.  The new function Async_Port_Address_Given can be used to
  215. check if the RS232 base address is installed in memory or not.
  216.  
  217. The preprocessor symbol MTASK should be defined if you are using
  218. these routines in conjunction with the PIBMDOS routines for interfacing
  219. to multitaskers.
  220.  
  221. The routines DOS_Set_Intrpt and DOS_Get_Intrpt have been removed and
  222. replaced by the standard TP4 routines GetIntVec and SetIntVec, respectively.
  223.  
  224. The batch file MAKEDUMB.BAT makes the DUMBTRM.EXE sample program
  225. using the command line compiler (TPC.EXE).
  226.  
  227. -- Phil Burns   11/11/87
  228.