CD Actual 13

home *** CD-ROM | disk | FTP | other *** search

/ CD Actual 13 / CDA13.ISO / cdactual / demobin / share / program / C / ASYNCH13.ZIP / ASYNC.DOC < prev next >

Wrap

Text File | 1990-11-28 | 43.3 KB | 955 lines

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.