ProModem RS232 Interrupt Driven Serial Communication Library  v1.0


		       Written By Adrian J. Michaud

	   (C) Interactive Telecommunication Systems 1992-1993



			   Table Of Contents
			   -----------------

							      Page

Introduction                                                    1
Features/Supported Compilers                                    2
Registration                                                    3
Ording Form                                                     4

SetupControlBlock()                                             5
OpenCom()                                                       6
CloseCom()                                                      7
SendCharacter()                                                 8
CheckQueue()                                                    9
GetCharacter()                                                  10
ClearQueue()                                                    11
GetCarrierDetect()                                              12
SetBaudRate()                                                   13
SetDTR()                                                        14
DropDTR()                                                       15
SetDataFormat()                                                 16
SendString()                                                    17
SetFIFOMode()                                                   18
SetFIFOTriggerLevel()                                           19
WaitForCharacter()                                              20
DisableIRQ()                                                    21
EnableIRQ()                                                     22

TERMINAL.C - Example Terminal Program source file               23
BBS.C      - Example Bulletin Board source file                 24



  Page 1 - ProModem Users Manual         Interactive Telecommunication Systems

			    Introduction
			    ------------

     ProModem is a High Performance Interrupt Driven RS232 serial
   communication library that can be used for creating a Computerized
   Bulletin Board System, a Terminal program, a RS232 Networking Driver,
   or for RS232 Host to Host communications. ProModem supports the following
   UARTS: PC16550C, NS16550AF, PC16550CF, 16450, and the 8250. ProModem takes
   full advantage of a 16550 by enabling the 16 character FIFO to relieve
   the CPU of excessive software overhead. When using a 16550, internal
   FIFOs are activated allowing 16 bytes (plus 3 bits of error data per
   byte in the RCVR FIFO) to be stored in both receive and transmit modes.
   All the logic is on chip to minimize system overhead and maximize
   system efficiency.






  Page 2 - ProModem Users Manual         Interactive Telecommunication Systems

			      Features
			      --------


   ProModem contains the following features:

   o Interrupt driven INPUT directly VIA 8259 Peripheral Interrupt Controller.
   o Full 16550 FIFO support with selectable trigger levels.
   o Supports user definable Base Addresses using IRQ3 or IRQ4.
   o Automatic CTS/RTS Hardware Handshaking for Asynchronous Devices.
   o Baud rates up to 115k bits per second.
   o Handles unlimited Open Com Ports using IRQ3 and IRQ4.
     (overruns might occur with slow CPU's or High Baud Rates of course).
   o Supports both ISA (PC AT) and MCA (PS 2) machines
   o Small, (Large, and Huge memory models available to registered users).


			 'C' Compilers Supported
			 -----------------------

   Microsoft C     - v5.1, v6.0, QuickC v2.5, and C/C++ v7.0
   Borland TurboC  - v1.0, v2.0, v3.0, v3.1



  Page 3 - ProModem Users Manual         Interactive Telecommunication Systems

			     Registration
			     ------------

     ProModem is not a public domain program and is not free.  ProModem is
   Copyright (C) 1993 by Interactive Telecommunication Systems. Non-registered
   users of this library are granted a limited one month license to ProModem
   to evaluate the libraries suitability for their requirements.  Any usage of
   ProModem beyond evaluation time period requires registration of each copy of
   the library used.  Use of non-registered copies of ProModem beyond the
   original evaluation period is prohibited.

     The Shareware version of ProModem has been built with a small model.
   When you register ProModem you will receive FULL printed documentation
   along with a LARGE and a HUGE library for all compilers supported.
   Source code to all memory models for all supported compilers is
   also part of the registration package.

     There are two ways to register. The first is by sending $25 to
   Interactive Telecommunication Systems along with a registration form.
   Non U.S. residents, please send checks drawn on U.S. funds. We will accept
   non U.S. currency, but you must include an additional $5 (US) to cover
   exchange handling. Also add $5 overseas shipping/handling. See the page 4
   for the ordering form and ordering information.



  Page 4 - ProModem Users Manual         Interactive Telecommunication Systems


			  ProModem Ordering Form
			  ----------------------

     Please Remit To:      Eutecnics
			   C/O Adrian J. Michaud - ProModem!
			   30 Nagog Pk., Suite 105
			   Acton, Ma 01720

     Qty.    Description                                   Each     Total

     ____    ProModem Registration with 3.5" diskette    $25.00   ________
	     Includes ALL memory models with Source
	     Code and a printed Manual. MSC & TC.

     ____    ProModem Registration with 5.25" diskette   $25.00   ________
	     Includes ALL memory models with Source
	     Code and a printed Manual. MSC & TC.

	(U.S. orders add $2 shipping & handling)        Shipping   ________
	(Foreign orders add $5 shipping)

	(Add $5 for Foreign Currency Exchange)     Misc. Charges   ________

	(MA residents please add 7.25% sales tax)            Tax   ________

							   TOTAL  $________

     Name: _________________________________________________________________

  Company: _________________________________________________________________

  Address: _________________________________________________________________

	   _________________________________________________________________

	   _________________________________________________________________

 Where did you obtain ProModem? ( ) Friend   ( ) Shareware House   ( ) Other
				( ) BBS      ( ) User Group       __________

All checks or money orders must be drawn on U.S. Funds in U.S. Dollars.
Sorry, no C.O.D. orders will be accepted.

  Make All Checks Payable to:  Interactive Telecommunication Systems



  Page 5 - ProModem Users Manual         Interactive Telecommunication Systems


  Function: int SetupControlBlock(AJMS *controlBlock,
				  unsigned int baseAddress,
				  int irq,
				  unsigned int bufferSize);

  Description: Sets up a control block for a specific com port and IRQ
	       number. This is the first function that is always used when
	       preparing to communicate to a COM port. Each com port that
	       will be opened requires a different control block.

  Return Value: SUCCESSFUL    - Setup was successful.
		TOO_MANY_IRQS - Too many mounted com ports.

  Example Usage:

  #include "promodem.h"
  main()
  {
  AJMS controlBlock;

  /* This sets up a control block for COM1 (0x3f8), IRQ4, and a
     4096 Byte receive Buffer.
  */

  SetupControlBlock(&controlBlock , 0x3f8 , 4 , 4096);/*Init Control Block*/
  OpenCom(&controlBlock);                             /*Open COM port     */
  }





  Page 6 - ProModem Users Manual         Interactive Telecommunication Systems


  Function: int OpenCom(AJMS *controlBlock);

  Description: Opens a COM port for communication. This function allocates
	       an IRQ buffer and sets up the UART for communication.

  Return Value: BUFFER_ALLOCATION_ERROR - Could not allocate IRQ buffer.
		COM_ALREADY_OPEN        - Port is already open and ready.
		SUCCESSFUL              - COM port successfully opened.

  Example Usage:

  #include "promodem.h"
  example()
  {
  extern AJMS controlBlock; /* Assumes a control block has previously  */
			    /* been set up.                            */

  OpenCom(&controlBlock);   /* Open COM port */
  }






  Page 7 - ProModem Users Manual         Interactive Telecommunication Systems


  Function: int CloseCom(AJMS *controlBlock);

  Description: Closes a previously opened COM port. This de-allocates the
	       IRQ buffer that was allocated by OpenCom() and restores
	       the UART to its previous state before it was opened.

  Return Value: COM_PORT_NOT_OPEN - COM port was not previously Opened.
		SUCCESSFUL        - COM port successfully closed and IRQ
				    buffer has been de-allocated.

  Example Usage:

  #include "promodem.h"
  example()
  {
  extern AJMS controlBlock; /* Assumes a control block has previously  */
			    /* been set up and the COM port is OPEN    */

  CloseCom(&controlBlock);   /*Close COM port */
  }






  Page 8 - ProModem Users Manual         Interactive Telecommunication Systems


  Function: int SendCharacter(AJMS *controlBlock, unsigned char ch);

  Description: Sends a character to the COM port.

  Return Value: CARRIER    - If there is a carrier.
		NO_CARRIER - If there isn't a carrier.

  Also see: SendString()

  Example Usage:

  #include "promodem.h"
  example()
  {
  unsigned char ch;         /* Allocate ch on the stack */

  extern AJMS controlBlock; /* Assumes a control block has previously  */
			    /* been set up and the COM port is OPEN    */

  ch = (unsigned char)getch();      /* Get a character from the keyboard */
  SendCharacter(&controlBlock, ch); /* Send character to COM port        */
  }




  Page 9 - ProModem Users Manual         Interactive Telecommunication Systems


  Function: int CheckQueue(AJMS *controlBlock);

  Description: Checks the status of the IRQ receive buffer.

  Return Value: CHARACTERS_WAITING - If there are characters in queue.
		QUEUE_EMPTY        - If queue is empty.

  Also see: GetCharacter(), ClearQueue(), WaitForCharacter()

  Example Usage:

  #include "promodem.h"
  example()
  {
  extern AJMS controlBlock; /* Assumes a control block has previously */
			    /* been set up and the COM port is OPEN   */

  if (CheckQueue(&controlBlock) == CHARACTERS_WAITING) /* Check Queue     */
  printf("%c", GetCharacter(&controlBlock)); /* Print one byte from Queue */
  }






  Page 10 - ProModem Users Manual        Interactive Telecommunication Systems


  Function: int GetCharacter(AJMS *controlBlock);

  Description: Gets a single character from Receive IRQ Queue.

  Return Value: First Character that was placed in the receive Queue.
		The receive queue expands as more characters are
		received. GetCharacter() takes the first character
		from the queue and returns it as an (int) with the
		high byte masked.

  Also see: CheckQueue()

  Example Usage:

  #include "promodem.h"
  example()
  {
  extern AJMS controlBlock; /* Assumes a control block has previously */
			    /* been set up and the COM port is OPEN   */

  if (CheckQueue(&controlBlock) == CHARACTERS_WAITING) /* Check Queue     */
  printf("%c", GetCharacter(&controlBlock)); /* Print one byte from Queue */
  }






  Page 11 - ProModem Users Manual        Interactive Telecommunication Systems


  Function: void ClearQueue(AJMS *controlBlock);

  Description: Clears the contents of the Receive IRQ Queue.
	       This insures that there are no pending characters
	       in the Receive IRQ Queue.

  Return Value: None.

  Also see: CheckQueue()

  Example Usage:

  #include "promodem.h"
  example()
  {
  extern AJMS controlBlock; /* Assumes a control block has previously */
			    /* been set up and the COM port is OPEN   */

  ClearQueue(&controlBlock); /* Clears the Receive IRQ Queue */
  }