async.doc

source code for visa card

This is a set of rather simple serial communication routines written in 
assembly, and to be called from C.  If it is not stated elsewhere, this code
is public domain!  Do with it as you wish, put it in your programs, etc, etc.

This is the second 'release' of the ASYNC functions.  Since the first release
several people have contributed modifications to the routines, to which I
want to give them thanks and some credit where credit is due.

Roy M. Silvernail --  [e-mail] - OR-  cybrspc![e-mail]

	For clarifying the documentation of AsyncHand() and AsyncSet().  He
	added a few #define's to further clarify AsyncSet().  He also is 
	responsible for adding some error checking to AsyncInit()-- it now
	returns a non-zero on error (when the COM port isnt there).

Steve Miller  -  uunet!pictel!miller

	For finding a rather obscure bug.  If a character was recieved and
	sent at exactly the same time, then it would stop receiving or
	sending characters.  

Thanks again.

In addition, the buffer size has been increased from 1024 to 8196 characters.


Here is a list of all the files included in this package:

	async.doc	- 	What you are reading.
	async.h		-	The C prototypes/header file
	async.asm	-	The assembly source
	term.c		-	The source for a simple terminal program
	asyncs.obj	-	The .obj async.asm file for the SMALL model
	asyncc.obj	-	The .obj for the COMPACT model
	asyncm.obj	-	The .obj for the MEDIUM model
	asyncl.obj	-	The .obj for the LARGE model
	term.exe	-	The executable for the terminal program

I have used these with Turbo C, and Turbo ASM without any problems.  It
should work with Microsoft C and ASM, but a bit of re-writing will be needed
to make the assmebler part work.  I have also used it with Turbo C++ and 
Turbo Assembler 2.0 without any problem, but you will have to treat the 
Async functions as standard C, rather than C++.

Here is a short tutorial of the Async functions:

AsyncInit( int Port)
AsyncStop( void)
These functions start and stop the interrupt handlers.  No characters can be
recieved if it isn't started, and the computer will crash if they are not 
stopped before the program is exited.  The paramater 'port' is the COM port
to use, there are #defines in the header file that defines the values to be
used.  It would be 'more bug proof' if AsyncStop was called via the atexit()
function (check your compiler manual).

AsyncInit() will return a non-zero value upon an error (when the COM port is
not there).


AsyncClear( void)
Clears the internal buffers.


AsyncOut( int c)
Sends out a character.


AsyncIn( void)
Returns the next character in the buffer or a NULL upon an empty buffer.  Use
AsyncInStat() to check for the number of characters in the buffer.


AsyncHand( int handshake)
Sets the status of the handshaking lines.  The values are defined in the 
header file and can be or'd together.  A typical call would look like this:
	AsyncHand( DTR | RTS);

Roy M. Silvernail found confusion in this rather simple explanation of 
AsyncHand().  I thought of editing the above description, but his description
is better than mine, so here it is:

"The AsyncHand routine wants the whole set of flags upon invocation. At
first, I had tried AsyncHand(~DTR) to drop DTR, but soon found it didn't
work. With the 2 main control bits being DTR and RTS, AsyncHand(RTS)
drops DTR just fine, and (of course) AsyncHand(DTR | RTS) raises it once
again."


AsyncSet( int Baud, int Control)
This sets the baud rate, paraty, etc, of the serial line.  The paramater 'Baud'
is the baud rate (ie 1200, 2400, 9600, etc), and 'control' is a number that
represents parity, length and stop bits.  There are defines for this in 
ASYNC.H, but here are a few commonly used examples:

	AsyncSet( 2400, BITS_8 | STOP_1 | NO_PARITY )   for 2400 baud 8N1.
	AsyncSet( 9600, BITS_7 | STOP_1 | EVEN_PARITY)  for 9600 baud 7E1.


AsyncInStat( void)
This frunction returns the number of characters in the input buffer.


AsyncOutStat( void)
Returns the number of characters in the output buffer.


AsyncStat( void)
Returns the status of the handshaking lines.  Use the & and | oporaters with 
the values defined in the header file to extract any useful informaton out of
this value.

The values used include the normal DCD, RI, and CTS, but also include D_DCD for
'Delta-DCD' or CHANGE IN DCD.  This is useful in detecting changes in the 
handshaking lines since the last time the status was read.


These routines do have their limitations, however.  They cannot deal with more
than one serial port, and cannot take advantage of the 16550 UART.  There is 
also no routines for input and output of strings-- there is so many ways of 
doing it that I left it up to whoever used these routines.  

Enjoy, and if you have any questions, dont hesitate to ask.

David Kessner - [e-mail]            | do {
1135 Fairfax, Denver CO  80220  [phone] (p.m.) |    . . .
If you cant flame MS-DOS, who can you flame?          |    } while( jones);