ASYNCx.LIB 1.30 Documentation                         11/28/90

                                  HISTORY:
          Version 1.00 - 3/7/89:
            This version supports the basic functions of interrupt
            driven asyncronous communications on the IBM PC and PS/2. It
            supports COM1 and COM2 on PCs and COM1 through COM8 on
            microchannel machines. XON/XOFF control routines and logic
            exist, but do not work. But since everything else tests out
            OK, I'm going ahead and releasing the library without the
            XON/XOFF stuff fixed. (Just don't turn on XON/XOFF
            handling.)

          Version 1.01 - 4/25/89:
            Oops. I forgot to provide a way to modify the communications
            parameters of a port while it's open. The a_params function
            has been added for this purpose.

          Version 1.02 - 4/28/89:
            More oversights sighted. This version adds 6 new functons
            (a_getlcr, a_getlsr, a_getmcr, a_getmsr, a_setlcr, and
            a_setmcr) to handle direct read and writing to control and
            status ports of the UART.

          Version 1.03 - 11/30/89:
            This version fixes an initialization problem that was
            experienced on some machines. On these machines, if a
            character was received before one was sent, no interrupt
            would be generated for the character to be read from the
            UART'd data buffer and over-run error would result from any
            further data received. This has been fixed.

            Also, the a_putc() function has been mostly re-written. See
            the description of this function where it is listed in the
            FUNCTIONS: section of this document for more details.

          Version 1.10 - 11/06/89
            The only real change in this version is an extra parameter
            for the a_waitquiet() function. I provided a way for the
            programmer to specify a maximum amount of time to wait for
            the desired gap in the incomming data stream. (Previous
            versions of a_waitquiet() would never return if presented
            with a continual stream of incomming data.)

          Version 1.20 - 12/11/89
            The XON/XOFF flow control has finally been added. Because of
            this, I have changed the interfaces to some of the functions
            of this library. The modifications are detailed in the
            disucussions of the appropriate functions, but here is a
            summary of the changes made:

            1. int a_puts(char *s,ASYNC *p) now returns the number of
               characters that it successfully transmitted. If an XOFF
               character is received in the middle of the transmission,
               this count may fall short of the length of the string.

            2. int a_iflush(ASYNC *p) sends an XON character if an XOFF
               character has allready been sent. If the XON character
               cannot be added to the output buffer (under the same
               constraints that apply to a_getc), the buffer is not
               flushed and a value of -1 is returned. Otherwise, the
               buffer is flushed and a value of 0 is returned.

            A few of the other functions received a minor logical face-
            lift. The a_open function does not turn on XON/XOFF flow
            control. If you want to take advantage of XON/XOFF, you must
            set XON and XOFF buffer threshold levels using the setxonoff
            function.

          Version 1.21 - 01/17/89
            The a_gets() function has been modified so that it will only
            return a value of NULL (to indicate an EOF state on the
            async port) if no characters at all are received over that
            port. In previous versions, NULL would be returned if a
            blank line was received.

          Version 1.30 - 01/18/89
            The a_open() function no longer takes DTR and RTS down and
            back up during initialization of the async port. It just
            leaves both up. Also, a_close() has sprouted a new parameter
            that allows the application closing an async port to control
            whether DTR and RTS are left up or down when the port is
            closed.

                                 PHILOSOPHY:
          The interface to the routines in this library is closely
          analogous to the interface used with the ANSI C streem I/O
          functions. I made every effort to allow you to handle the
          async ports of the computer in the same way in which you would
          handle a stream opened in binary (as opposed to text) mode.
          While the nature of an asyncronous environment forced certain
          concessions in the conformity vs. practicality battles, I
          believe C programmers will find the interface to these
          functions familiar and intuitive.

          If you were wondering: I'm not asking for any money for this.
          I'm making no claim that these routines are suitable for you.
          I don't even claim that the use (proper or otherwise) will not
          harm (or even destroy) hardware or software that you value.
          One last thing that I don't do is tell you who I am, where I
          live, or how to get in touch with me for support. I wrote this
          async library because I needed it; not to make a fast buck.
          Just think of me as a philanthropic programmer who wants to
          give other programmers a leg up in communications programming.

                                  FEATURES:

          o All source is available. Turbo C 2.0 or higher is required
            for recompilation.

          o Supports COM1 and COM2 on PC/XTs and COM1 through COM8 on
            PS/2s.

          o Bit rates from 300 to 19200,
            Even, odd, mark, space, and no parity,
            1 or 2 stop bits, and
            from 5 to 8 data bits per word.

          o Input and output buffering for support of the higher bit
            rates.

          o Output buffering can be turned off to make programming in an
            async environment a little simpler.

          o XON/XOFF flow control with individually adjustable
            thresholds is supported.


                           A LITTLE MORE TECHNICAL:
          COM1 is handled via INT 0xC (IRQ 4) and COM2 through COM8 are
          handled via INT 0xB (IRQ 3). The base port addresses for COM1
          through COM8 are 0x3f8, 0x2f8, 0x3220, 0x3228, 0x4220, 0x4228,
          0x5220, and 0x5228, respectively. When the a_open function
          opens a port, the UART corresponding to that port is told to
          generate an interrupt whenever a character is sent or
          received, but not when an error or line-level change occurs.
          This, of course, is turned off when the port is closed. The
          routines in this async library completely bypass BIOS INT 14h.
          This allows reliable communication at speeds up to 19200 baud.

       北北北北北北北北北北北北北北北北北北北北北北北北北北北北北北北北北北
       北 NOTE: When a you open a port with the a_open function, you are 北
       北 changing either interrupt vector 0xB or 0xC, depending on what 北
       北 port you open. If you fail to close the port with the a_close  北
       北 function, these vectors will never be restored to their        北
       北 original values. If you allow your program to end without      北
       北 EXPLICITLY CLOSING ALL OPENED PORTS, your machine will         北
       北 probably crash the next time there is any activity on your     北
       北 async line (or modem or whatever).                             北
       北北北北北北北北北北北北北北北北北北北北北北北北北北北北北北北北北北

                      Creation and use of ASYNCx.LIB files:
          The batch file CREASYNC.BAT has been provided to compile each
          of the modules into a .OBJ form and to put each .OBJ file into
          the ASYNCx.LIB file. CREASYNC.BAT takes one single-character
          parameter on its command line. This character is t for tiny, s
          for small, m for medium, c for compact, l for large, or h for
          huge memory model and will replace the x in ASYNCx.LIB to
          produce ASYNCT.LIB, ASYNCS.LIB, ASYNCM.LIB, ASYNCC.LIB,
          ASYNCL.LIB, and ASYNCH.LIB, respectively.

          These 6 library files (assuming that you create all 6 of them)
          should be copied to where ever it is that you keep the rest of
          the .LIB files. This way Turbo C will know where to find them
          when it wants them.

          To compile and link a program that uses one of the ASYNCx.LIB
          files, issue a command similar to the following:

            tcc -ms myprog.c asyncs.lib

          Note that the -ms option (for small memory model) will only
          work with ASYNCS.LIB and not any of the other 5 ASYNCx.LIB
          libraries. If you want to use the huge memory model, you would
          issue a command similar to the following:

            tcc -mh myprog.c asynch.lib

          A program called MYPROG.C has been provided for you. It is a
          very rudimentary communications package. It's heavily
          commented and I hope it'll help you to get started with the
          ASYNC library.

                                   FUNCTIONS:

          This is a list of all the functions in the ASYNC library. Each
          is described in detail on the following pages. (The functions
          are listed in alphabetical order by function name.)

          int a_break(ASYNC *p, int t);

          ASYNC *a_close(ASYNC *p,int fc);

          int a_eof(ASYNC *p,int t);

          int a_icount(ASYNC *p);

          int a_iflush(ASYNC *p);

          int a_getc(ASYNC *p);

          int a_getlcr(ASYNC *p);

          int a_getlsr(ASYNC *p);

          int a_getmcr(ASYNC *p);

          int a_getmsr(ASYNC *p);

          char *a_gets(char *s,int n,ASYNC *p,int t);

          int a_ocount(ASYNC *p);

          int a_oflush(ASYNC *p);

          ASYNC *a_open(int port,int baud,int par,int dbits,int sbits,
                        int ibufsize,int obufsize);

          int a_params(ASYNC *p,int baud,int par,int dbits,int sbits);

          int a_portno(ASYNC *p);

          int a_printf(ASYNC *p,char *format,...);

          int a_putc(int c,ASYNC *p);

          int a_puts(char *s,ASYNC *p);

          int a_read(void *buf,int s,int n ASYNC *p,int t);

          void a_setlcr(ASYNC *p,int newval);

          void a_setmcr(ASYNC *p,int newval);

          a_setxonoff(ASYNC *p,int xon,int xoff);

          int a_ungetc(int c,ASYNC *p);

          int a_waitfor(ASYNC *p,char *s,int t,int mode);

          void a_waitquiet(ASYNC *p,int t,int max,int mode);

          int a_write(void *buf,int s,int n,ASYNC *p);


          諛哪哪哪