Dec 072017
 
Good public domain comm library, with C source code.
File ASYNC130.ZIP from The Programmer’s Corner in
Category C Source Code
Good public domain comm library, with C source code.
File Name File Size Zip Size Zip Type
ASYNC.C 15231 3811 deflated
ASYNCDEF.H 3271 959 deflated
ASYNCLIB.DOC 44315 9877 deflated
BREAK.C 769 369 deflated
CREASYNC.BAT 1268 551 deflated
EOF.C 726 375 deflated
GETC.C 1057 451 deflated
GETLCR.C 415 218 deflated
GETLSR.C 425 225 deflated
GETMCR.C 424 225 deflated
GETMSR.C 416 219 deflated
GETS.C 1977 877 deflated
IFLUSH.C 880 435 deflated
MYPROG.C 3164 1356 deflated
OFLUSH.C 426 231 deflated
PRINTF.C 763 382 deflated
PUTC.C 2350 872 deflated
PUTS.C 906 491 deflated
READ.C 815 438 deflated
SETLCR.C 381 203 deflated
SETMCR.C 487 258 deflated
SETXON.C 949 486 deflated
UNGETC.C 891 438 deflated
WAITFOR.C 1817 643 deflated
WAITQUIE.C 2023 850 deflated
WRITE.C 660 350 deflated

Download File ASYNC130.ZIP Here

Contents of the ASYNCLIB.DOC file


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);



a_break

Function: Turn on the BREAK signal for a specified duration.

Syntax: int a_break(ASYNC *p, int t);

Remarks: a_break holds the transmit line of the async port in
the BREAK state for t 18ths of a second.

Return: a_break returns 0 if port p is open. A value of -1
is returned if port p has not been opened. (An
unopened port is recognized by a NULL value in p.)


a_close

Function: Close an async port.

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

Remarks: a_close closes port p. This involves deallocating
the memory occupied by its input buffer, output
buffer (if one was allocated for it), and by the
ASYNC structure itself. Also, the interrupt that
was enabled when the port was opened is disabled
(provided that no other port is using it).

Value of fc may be any combination of the bits of
MCR_DTR and MCR_RTS to leave the DTR and/or RTS
signals active after the port is closed.

Return: a_close always returns NULL. This is to facilitate
resetting the ASYNC pointer variable to NULL. For
instance, you might close a port by saying:

port=a_close(port,0);

This would close the async port, drop DTR and RTS,
and give port a value of NULL at the same time.
While a_close(port,0) would work all by itself,
setting port to NULL at the same time is the
preferred method of closing a it.


a_eof

Function: Determine whether or not data has stopped comming in
over a given port.

Syntax: int a_eof(ASYNC *p,int t);

Remarks: a_eof waits for up to t 18ths of a second for data
to arrive in the input buffer of port p.

Return: If data appears in the input buffer before the
specified interval expires, a value of 0 is
returned. Otherwise a value of 1 is returned to
indicate that the specified port is in an EOF state.


a_icount

Function: Return the number of characters in the input buffer
of an async port.

Syntax: int a_icount(ASYNC *p);

Remarks: a_icount is a macro that returns the value of the
icount field of the ASYNC structure to which p
points.

Return: a_icount returns the number of characters waiting to
be read from the input buffer of port p.


a_iflush

Function: Discard any data in a port's input buffer.

Syntax: int a_iflush(ASYNC *p);

Remarks: Any characters in the input buffer of port p are
removed. If an XOFF character has been sent out, an
XON character is sent when the input buffer is
emptied. This lets the equipment on the other end of
the line know that it's ok to send data again.

Returns: a_iflush returns 0 if the operation is successful.
Otherwise, a value of -1 is returned.


a_getc

Function: Retrieve a character from an async port.

Syntax: int a_getc(ASYNC *p);

Remarks: a_getc attempts to retrieve one character from the
given async port.

Return: If a character is in the input buffer of the
specified port, the value of that character (without
sign extension) is returned as an integer. If no
character is available from the specified port, a
value of -1 is returned.


a_getlcr

Function: Get the value of the Line Control Register.

Syntax: int a_getlcr(ASYNC *p);

Remarks: a_getlcr gets the value of the Line Control
Register. The bitwise encoding of this register is
as follows:

Bits 1 & 0 - Word length:
00 = 5 bits
01 = 6 bits
10 = 7 bits
11 = 8 bits
Bit 2 - Number of stop bits:
0 = 1 stop bit
1 = 2 stop bits (1.5 if 5-bit word)
Bit 3 - Parity enable:
0 = no parity.
1 = parity enabled and checked.
Bits 4 & 5 - Parity mode:
00 = odd parity
01 = even parity
10 = mark parity
11 = space parity
Bit 6 - Break enable:
0 = normal operation
1 = Transmit line held active.
Bit 7 - Divisor latch access
0 = Bottom 2 port addresses used for
transmitting and receiving data
and for IRQ enable.
1 = Bottom 2 port addresses used for
LSB and MSB of baud rate divisor.

The a_params functions allows access to bits 0
through 5 and bit 7 in a much more intuitive way.
a_break allows timed access to bit 6. The a_getlcr
function is provided so that you can query the
communications port about its communications
parameters directly.

Return: a_getlcr returns an integer with bits 0 through 7
set to those of the line control register. Bits 8
through 15 are set to 0.


a_getlsr << New >>

Function: Get the value of the Line Status Register.

Syntax: int a_getlsr(ASYNC *p);

Remarks: a_getlsr gets the value of the Line Status Register.
The bitwise encoding of this register is as follows:

Bit 0 - Data received.
Bit 1 - Data Overrun.
Bit 2 - Parity Error.
Bit 3 - Framing Error.
Bit 4 - Break received.
Bit 5 - Can accept another word to transmit.
Bit 6 - Finished transmitting the last word.
Bit 7 - Always 0.

a_getlsr provides a way for you to verify the
integrity of the incomming data. If any of bits 1
through 3 is set to 1, you can assume that at least
one word of data has been lost.

The "data received" bit is set when the
communications port receives one whole word from the
async line and has made it available to the
computer. Since this also triggers an interrupt that
reads the data from the port, you should never see
this bit in an active state.

The "break received" bit can be used to test for
break signals received from equipment at the other
end of the async line.

Bit 5 has a value of 1 when the async port is ready
to receive a word to be transmitted. It holds this
word in a Transmit Buffer Register until it is ready
to actually transmit the word.

Bit 6 has a value of 1 when the async port has
finished transmitting a word and is able to start on
the next one. The next word will come from the
Transmit Buffer Register to be stored in the
Transmit Shift Register while it is being
transmitted.

Return: a_getlsr returns an integer with bits 0 through 7
set to those of the line status register. Bits 8
through 15 are set to 0.


a_getmcr << New >>

Function: Get the value of the Modem Control Register.

Syntax: int a_getmcr(ASYNC *p);

Remarks: a_getmcr gets the value of the modem control
register. The bitwise encoding of this register is
as follows:

Bit 0 - Data Terminal Ready (DTR)
Bit 1 - Request to Send (RTS)
Bit 2 - Modem Reset (OUT1)
Bit 3 - Interrupt Enable
Bit 4 - Loopback Enable

MCR_DTR, MCR_RTS, MCR_OUT1, and MCR_LOOP are
#defined in async.h to 1, 2, 4, and 16 for your
convenience.

For almost all communications applications, DTR and
RTS should be held high (set to a value of 1)
whenever the application is ready to accept data.
Some serial equipment is smart enough to stop
sending data to a device that is holding it DTR
and/or RTS lines low.

The OUT1 line can be used to reset some modems. Most
modems, however, have a command-set oriented method
for performing this function.

Bit 3 (interrupt enable) must remain high (set to 1)
for a port's interrupt handler to put incomming data
into the input buffer. This is the only way to
handle data at baud rates above 1200 baud. DON'T
TURN OFF THIS BIT!

Bit 4 (loopback enable) is for testing the port. If
this bit is high (set to 1), the async port will
echo back all characters that you send it to be
transmitted. One possible use for this feature to
test for the existance of an async port. If the
loopback feature fails to echo back to you the
characters that you send, the port is either missing
or broken.

Return: a_getmcr returns an integer with bits 0 through 4
set to those of the modem control register. Bits 5
through 15 are set to 0.


a_getmsr << New >>

Function: Get the value of the Modem Status Register.

Syntax: int a_getmsr(ASYNC *p);

Remarks: a_getmsr gets the value of the Modem Status
Register. The bitwise encoding of this register is
as follows:

Bit 0 - CTS changed
Bit 1 - DSR changed
Bit 2 - RI has gone low
Bit 3 - CD changed
Bit 4 - Clear To Send (CTS)
Bit 5 - Data Set Ready (DSR)
Bit 6 - Ring Indicator (RI)
Bit 7 - Carrier Detect (CD)

Bits 4 through 7 may be examined to determine the
current status of CTS, DSR, RI, or CD. Bits 0
through 3 may be examined to detect an change in
CTS, DSR, RI, or CD.

Return: a_getmsr returns an integer with bits 0 through 7
set to those of the modem control register. Bits 8
through 15 are set to 0.


a_gets

Function: Retrieve a string from an async port.

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

Remarks: a_gets reads up to n-1 characters from port p into
the buffer pointed to by s. This function stops
reading the string when a \r character is read. The
\r is replaced with a null terminator in the string
buffer. Any \n characters or \0 characters that are
read from the async port are ignored. a_gets will
wait for up to t 18ths of a second for the string to
arrive in the input buffer.

Return: If at least one character is read from the port's
input buffer, the address of the string buffer is
returned, whether any characters actually made it
into the string or not. If no characters are read
from the input buffer at all during the specified
interval, a value of NULL is returned to indicate
and eof condition.


a_ocount

Function: Return the number of characters in the output buffer
of an async port.

Syntax: int a_ocount(ASYNC *p);

Remarks: a_ocount is a macro that returns the value of the
ocount field of the ASYNC structure to which p
points. This value is real handy if you have just
send a command over the port and would like to wait
for it to be transmitted before you start looking
for the reply.

Return: a_ocount returns the number of characters waiting to
be transmitted from port p. A value of 0 is always
returned if output buffering was not enabled when
the port was opened.


a_oflush

Function: Discard any data in a port's output buffer.

Syntax: int a_oflush(ASYNC *p);

Remarks: Any characters in the output buffer of port p are
removed.

Returns: a_oflush returns 0 if the operation is successful.
Otherwise, a value of -1 is returned.


a_open

Function: Open an async port for use.

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

Remarks: a_open opens an async port for use with the given
characteristics. This involves allocating space in
memory for its ASYNC control structure, input
buffer, and output buffer (if one is specified).
port may be any integer in the range from 1 to 8
corresponding to the COM1 through COM8
specifications that DOS uses. (COM3 through COM8 are
only available on PS/2s.) baud specifies the baud
rate to be used for this port and may be any integer
from 300 to 19200. (But stick to the more common
baud rates if you want your software to work with
other software.) par specifies the parity to be used
for this port. The choices are #defined in ASYNC.H
as PAR_NONE, PAR_ODD, PAR_EVEN, PAR_MARK, and
PAR_SPACE. dbits is the number of data bits to use
and must be in the range from 5 to 8. sbits is the
number of stop bits to use and must be either 1 or
2. ibufsize is the number of bytes to allocate for
the input buffer for this port. Make it large enough
to avoid allowing it to overflow. (From 4000 to 8000
bytes is generally a good number, but mileage may
vary.) obufsize is the number of bytes to allocate
for the output buffer for this port. If this number
is 0, no output buffering will be used. (Note: You
MUST specify an output buffer size greater than 0 if
you intend to use XON/XOFF handshaking in your
program.)

Return: a_open returns a pointer to the ASYNC control

structure for the port being opened. If, however,
the port cannot be opened (because of insufficient
memory for the buffers), a value of NULL will be
returned.


a_params << New >>

Function: Change the communications parameters of a port that
has already been opened.

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

Remarks: This function can only be used on a port that is
already open. p identifies the port to modify. Each
of the other parameters of this function are the
same as the corresponding parameters of the a_open
function.

Return: a_params returns 0 if all goes well. It does no
range-checking on the parameter data, but if the
port has not been opened, a_params returns a value
of -1.


a_portno

Function: Return the port number (1 through 8) of a given
port.

Syntax: int a_portno(ASYNC *p);

Remarks: Find the number of the port with which p is
associated.

Return: a_portno returns an integer from 1 to 8 to indicate
the number of the port with which p is associated.
If p is not found to be associated with any port, a
value of 0 is returned.


a_printf

Function: Send formatted text to an async port.

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

Remarks: a_printf works exactly like fprintf except that the
first parameter points to an ASYNC structure instead
of a FILE structure. The length of the resulting
output string is limited to 1023 characters and its
is a really bad idea to imbed a null character in
the middle of it.

Return: a_printf returns 0 if the the port has been opened
or -1 if it has not.


a_putc

Function: Send a character to an async port.

Syntax: int a_putc(int c,ASYNC *p);

Remarks: a_putc attempts to send the character value of c to
port p. If the port is ready to transmit a
character, the character is transmitted immediately.
Otherwise, if an output buffer was allocated for
this port when it was opened, the character is put
into the output buffer. If no output buffer was
allocated for this port, a_putc waitw until the port
is ready to transmit another character, and
transmits the character value of c when the port is
ready.

Return: If the character is successfully transmitted,
a_putc() returns the value passed to it in c. If the
port is invalid (not opened), a value of -1 is
returned. If XON/XOFF (which is not currently
supported) is turned on, and an XOFF character has
been received, and the output buffer is full, a
value of -1 will also be returned.

Note: In versions prior to 1.03 of the ASYNC
library, a -1 would be returned if the an XOFF
character had been received (regardless of the state
of the output buffer) or if the output buffer was
full. Now, unless an XOFF character has been
received, a_putc will wait for the output buffer to
have room for the character it is trying to send.
This means that a -1 is only returned if an XOFF
character has been received and the output buffer is
full.


a_puts

Function: Send a string to an async port to be transmitted.

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

Remarks: a_puts sends the null-terminated string of
characters pointed to by s to port p. It calls the
a_putc function to do this. Only the characters
actually in the string are sent. No \r or \n
characters are appended.

Return: If the string is empty, return a value of 0.
Otherwise, return the value of the last character
transmitted. If the p is not a valid port, return a
value of -1.


a_read

Function: Read a block of data from an async port.

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

Remarks: a_read reads n objects consisting of s bytes each
from port p into the buffer pointed to by buf. This
routine will wait for a maximum or t 18ths of a
second for the block to be read.

Return: The number of whole objects (not necessarily bytes)
received is returned. If no data arrives at all or
if the port is not valid, a value of 0 is returned.


a_setlcr << New >>

Function: Set the value of the Line Control Register.

Syntax: void a_setlcr(ASYNC *p,int newval);

Remarks: a_setlcr sets the value of the Line Control
Register. The bitwise encoding of this register is
as follows:

Bits 1 & 0 - Word length:
00 = 5 bits
01 = 6 bits
10 = 7 bits
11 = 8 bits
Bit 2 - Number of stop bits:
0 = 1 stop bit
1 = 2 stop bits (1.5 if 5-bit word)
Bit 3 - Parity enable:
0 = no parity.
1 = parity enabled and checked.
Bits 4 & 5 - Parity mode:
00 = odd parity
01 = even parity
10 = mark parity
11 = space parity
Bit 6 - Break enable:
0 = normal operation
1 = Transmit line held active.
Bit 7 - Divisor latch access
0 = Bottom 2 port addresses used for
transmitting and receiving data
and for IRQ enable.
1 = Bottom 2 port addresses used for
LSB and MSB of baud rate divisor.

The a_params functions allows access to bits 0
through 5 and bit 7 in a much more intuitive way.
a_break allows timed access to bit 6. The a_setlcr
function is provided so that you can have complete
control over the break signal controled by bit 6.


a_setmcr << New >>

Function: Set the value of the Modem Control Register.

Syntax: void a_setmcr(ASYNC *p,int newval);

Remarks: a_setmcr sets the value of the modem control
register. The bitwise encoding of this register is
as follows:

Bit 0 - Data Terminal Ready (DTR)
Bit 1 - Request to Send (RTS)
Bit 2 - Modem Reset (OUT1)
Bit 3 - Interrupt Enable
Bit 4 - Loopback Enable

MCR_DTR, MCR_RTS, MCR_OUT1, and MCR_LOOP are
#defined in async.h to 1, 2, 4, and 16 for your
convenience.

For almost all communications applications, DTR and
RTS should be held high (set to a value of 1)
whenever the application is ready to accept data.
Some serial equipment is smart enough to stop
sending data to a device that is holding it DTR
and/or RTS lines low.

The OUT1 line can be used to reset some modems. Most
modems, however, have a command-set oriented method
for performing this function. This bit is set and
then cleared when a port is opened with the a_open
function. This is necessary to reset the UART so
that it will generate the appropriate interrupts.

Bit 3 (interrupt enable) must remain high (set to 1)
for a port's interrupt handler to put incomming data
into the input buffer. This is the only way to
handle baud rates above 1200 baud unless the
communications application is to run on a fairly
fast machine. <<< DON'T CLEAR THIS BIT! >>> At the
risk of infuriating some programmers, I wrote
a_setmcr() in such a way that it can't be used to
clear bit 3.

Bit 4 (loopback enable) is for testing the port. If
this bit is high (set to 1), the async port will
echo back all characters that you send it to be
transmitted. One possible use for this feature to
test for the existance of an async port. If the
loopback feature fails to echo back to you the
characters that you send, the port is either missing
or broken.


a_setxonoff << Not yet operational >>

Function: Set the levels at which XON and XOFF characters will
be sent. Xon and Xoff can also be turn off with this
function.

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

Remarks: XON/XOFF is handled by the ASYNC routines in the
following way: If there are at least xoff characters
in the input buffer, an XOFF character will be
sent. If this has already happened and the number of
characters in the input buffer drops to or below
xon, an XON will be sent.
To turn off XON/XOFF, set both xon and xoff to 0. If
XON/XOFF is being turned off and an XOFF character
has been sent, an XON character is sent so that
communications will not be frozen.

Return: Returns 0 if p, xon, and xoff are all valid. Returns
-1 otherwise.


a_ungetc

Function: Put a character into the input buffer of an async
port so that it will be the next character read from
that buffer.

Syntax: int a_ungetc(int c,ASYNC *p);

Remarks: a_ungetc puts character c into the input buffer used
by port p so that it will be the next character read
from that port. This operation may be performed
until the input buffer is full.

Return: The value of c is returned if the operation was
successful. If p is invalid or if the input buffer
for port p is full, a value of -1 is returned.


a_waitfor

Function: Wait for a given string to arrive from an async
port.

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

Remarks: a_waitfor waits for the string pointed to by s to be
received from port p for up to t 18ths of a second.
If mode is 0, the string must match exactly. If mode
is 1, the case of the received string may vary from
that of the string s points to. All data received
from the input buffer up to and including the string
being searched for is discarded. Any data that
arrives in the input buffer after the string is
found is left in the buffer.

Return: A value of 0 is returned if a matching string was
found. If no match was found, or if p is not valid,
a value of -1 is returned.


a_waitquiet

Function: Wait for no characters to arrive in the input buffer
of an async port for a given time interval.

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

Remarks: a_waitquiet waits for up to max 18ths of a second
for t 18ths of a second to elapse without any
characters arriving at port p. If mode is set to 0,
any characters that do arrive during the execution
of this routine are discarded and the input buffer
for port p is empty when this routine returns. If
mode is set to 1, characters arriving at port p are
detected but not discarded. Be careful of buffer
overflow if you use mode 1. If the buffer overflows,
the least recent data will be lost and the newest
data will be retained.

Return: This function returns a value of 0 if t 18ths of a
second were found to elapse between characters
arriving at port p within max 18ths of a second. If
no appropriate break in the incomming data stream is
found within max 18ths of a second, a value of -1 is
returned.


a_write

Function: Write a block of data to an async port.

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

Remarks: a_write sends n objects, each of which consists of s
bytes, to port p from the buffer pointed to by buf.

Return: This function returns the number of whole objects,
not necessarily bytes, written to port p. If p is
not valid, a_write returns a value of 0.


 December 7, 2017  Add comments

Leave a Reply