Programmer 7500

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

/ Programmer 7500 / MAX_PROGRAMMERS.iso / PASCAL / PCL4P31.ZIP / PCL4P.USR < prev next >

Wrap

Text File | 1992-03-11 | 45.2 KB | 1,322 lines

Personal Communications Library For the Turbo Pascal ( PCL4P ) USERS MANUAL Version 3.1 March 1, 1992 This software is provided as-is. There are no warranties, expressed or implied. Copyright (C) 1992 All rights reserved MarshallSoft Computing, Inc. Post Office Box 4543 Huntsville AL 35815 Phone (205) 881-4630 PCL4P Users Manual Page 1 Table of Contents Chapter Page Introduction........................................3 Registration........................................4 Library Overview....................................5 Initialization & Termination.....................5 Configuration....................................5 Modem Control & Status...........................6 Serial I/O.......................................6 Error Detection..................................7 General Support..................................7 Installation........................................8 Using the Library...................................9 Compiling...........................................10 Talking to your Modem...............................11 Problems............................................12 Function Summary....................................13 Serial Communications...............................14 IBM Communications Ports............................15 RS232 Signals.......................................16 National INS8250, INS16450, and INS16550 UARTs......17 Register Summary....................................18 Example Code........................................20 SIMPLE...........................................20 TERM.............................................20 LOOPBACK.........................................20 MODEM............................................20 Revision History....................................21 License.............................................22 Warranty............................................22 PCL4P Users Manual Page 2 Introduction The Personal Communications Library for Turbo Pascal ( PCL4P ) is an asynchronous communications library designed for experienced software developers programming in Turbo Pascal. An IBM PC/XT/AT or compatible is required. The PCL features: o 28 communications and support functions. o Support for INS16550 UART o Interrupt driven receiver. o Supports 300 baud to 115,200 baud. o Supports COM1, COM2, COM3, and COM4. o Adjustable receive queues from 8 bytes to 16 KB. o Control-BREAK error exit. o 17 communications error conditions trapped. o Allows 2 ports to run concurrently. o Complete modem control & status. o Written in assembly language for small size & high speed. A typical application program using PCL4P might look like the following code outline: ****************************************************************** * * * program YourProgram * * * * uses PCL4P; * * ... * * ... * * var Buffer : array[0..1023] of Char; * * ... * * begin (* YourProgram *) * * RetCode := SioRxBuf(Port,Ofs(Buffer),Seg(Buffer),Size1024); * * RetCode := SioParms(Port,NoParity,OneStopBit,WordLength8); * * RetCode := SioReset(Port,Baud2400); * * ... * * ... ( application code ) * * ... * * RetCode := SioDone(Port); * * end. (* YourProgram *) * ****************************************************************** In the above example, SioRxBuf is called to set up the a 1024 byte receive buffer; SioParms is called to set up the parity, stop bit count, and word length; SioReset is called to set the baud rate to 2400 and reset the UART ( Univeral Asynchronous Receiver / Transmitter ). Before leaving your application, SioDone is called to restore the prior state of the serial communications system. PCL4P Users Manual Page 3 Registration The shareware version of PCL4P.LIB is provided so that you may personally determine the usefulness of the product for yourself. If you can use the Personal Communications Library, please register your use with us. Send $45 plus $3 S&H ( $6 outside of the USA, Canada, and Mexico ) to: MarshallSoft Computing, Inc. Post Office Box 4543 Huntsville AL 35815 Please pay by check in US dollars drawn on a US bank. Purchase Orders ( POs ) are accepted from US companies listed in Dunn & Bradstreet. Print the file PCL4C.INV if an invoice is needed. The registered package is mailed first class US Mail ( packet air mail overseas ). If you are in a hurry, please call us and we can ship immediately within the US by COD ( street address and phone number required ). The registered package includes: o Turbo Pascal library without the shareware screens. o Assembler source code for the library. o Printed Users Manual. o Printed Reference Manual. o Telephone support for one year. o All updates ( with printed manuals ) are $15 plus $3 S&H ( $6 outside of USA, Canada, & Mexico ). PCL4P.ASM is the source code for the library. The source code is copyrighted by MarshallSoft Computing, Inc. The user is granted a license to use the PCL4P object code in his own application only. PCL4P.ASM is not shareware and may not be sold or given away to anyone. The registered user will receive the latest version of PCL4P by return mail. A 5.25" diskette is provided unless a 3.5" diskette is requested. Be sure to specify the "Pascal" version. PCL4P Users Manual Page 4 Library Overview The PCL4P library is organized into six categories of functions. Refer to the PCL Reference Manual ( PCL4P.REF ) for details on individual functions. 1. Initialization & Termination There are six functions in the initialization and termination category. Together, SioParms, SioFIFO, SioRxBuf, and SioReset initialize your serial communications system. Your application must call SioParms and SioRxBuf before calling SioReset, and SioReset must be called before any serial I/O processing can be done. After initialization, SioParms and SioBaud can be called again to change the communications parameters without resetting the serial port. Before exiting from your application, SioDone must be called. Failure to call SioDone can crash your system later. SioRxBuf -- Sets up receive buffer. SioFIFO -- Sets the FIFO trigger level ( INS16550 only ) SioParms -- Sets parity, stop bits, and word length. SioReset -- Initialize a serial port for processing. SioDone -- Terminates further serial processing. SioBaud -- Sets the baud rate of the selected port. 2. Configuration There are two functions in the configuration category. SioUART is used to change the UART base address for a communications port at a non-standard address, while SioIRQ is used to assign a nonstandard IRQ line to a port. ( See the chapter IBM Communications Ports for more details on standard UART addresses and IRQ lines ). The configuration category functions should be called before calling SioReset in order to have any effect. There is no "error checking" done, so be very careful in using these functions. SioUART -- Sets the UART base address. SioIRQ -- Assigns an IRQ line to a port. PCL4P Users Manual Page 5 3. Modem Control & Status There are seven functions in the modem control and status category which provide your application with complete control over the status and control bits of your modem. There are two modem control bits, "Data Terminal Ready" ( DTR ) and "Request To Send" ( RTS ). These bits can be read, set, or cleared by SioDTR and SioRTS. There are four modem status bits, "Data Set Ready" ( DSR ), "Clear To Send" ( CTS ), "Ring Indicator" ( RI ), and "Data Carrier Detect" ( DCD ). SioModem can read any of the modem status bits. SioDSR, SioCTS, SioRI, and SioDCD can only read their respective modem status bit. Refer to the chapter entitled "RS232 Signals" for a discussion of each of the control and status bits. SioDTR -- Set, clear, or read the Data Terminal Ready (DTR) bit. SioRTS -- Sets, clears, or reads the Request to Send (RTS) line. SioModem -- Reads the modem status register. SioDSR -- Reads the Data Set Ready (DSR) modem status bit. SioCTS -- Reads the Clear to Send (CTS) modem status bit SioDCD -- Reads the Data Carrier Detect (DCD) modem status bit. SioRI -- Reads the Ring Indicator (RI) modem status bit. 4. Serial I/O There are six library functions in the serial I/O category. Together, these functions give the programmer complete control over serial I/O. Higher level functions such as protocols and smart modem communications can be completely implemented in terms of these functions. Refer to the example code. SioGetc and SioPutc perform all the actual serial I/O. SioUnGetc and SioRxFlush modify the receive queue. SioLine can be used to test for UART errors. SioGetc -- Reads the next character from the serial line. SioPutc -- Transmit a character over a serial line. SioUnGetc -- "Un-gets" (puts back) a specified character. SioRxFlush -- Flush ( clears) the receive buffer. SioRxQue -- Returns the number of characters in the receive queue. SioLine -- Reads the line status register. PCL4P Users Manual Page 6 5. Error Detection There are four functions in the error detection category. They are concerned with detecting or reporting communications errors. Use of these functions can make your application significantly more robust. SioBrkKey can be used as an "emergency" exit from your application. SioBrkSig can read or modify the UART break bit. This is useful for signalling the remote system that a fatal condition has occurred. SioLoopBack can be used to test the integrity of your UART. SioError displays a error message corresponding to an error code returned from a PCL4P function ( every PCL4P function returns a code ). SioBrkKey -- Returns non-zero if the Control-BREAK key was pressed SioBrkSig -- Asserts, cancels, or detects BREAK signal. SioError -- Displays error in text. SioLoopBack -- Performs a UART loopback test. 6. General Support There are two functions in the general support category. SioDelay delays a specified number of clock tics while SioTimer returns the system clock tics. SioDelay -- Delays one or more tics. SioTimer -- Returns the number of system clock tics. PCL4P Users Manual Page 7 Installation (1) Before installation of PCL4P , your compiler should already be installed on your system and tested. If you are not familiar with makefiles, refer to your compiler manual. Examine the file "FILES.LST" for a list of all the distribution files. (2) Make a backup copy of your distribution disk. Put your original distribution disk in a safe place. (3) Create a work directory on your work disk ( normally your harddisk ). For example, to create a work directory named PCL4P, we first log onto the work disk and then type: MKDIR PCL4P (4) Copy all the files from your backup copy of the distribution disk to your work directory. For example, to copy from the A: drive to your work directory, we type: CD PCL4P COPY A:*.* (5) Compile SIMPLE.PAS: TPC SIMPLE SIMPLE.PAS should compile without any problems. (7) The recommended way to test SIMPLE is to run it on two computers connected by a null modem cable. Whatever is typed on one computer should be displayed on the other. (8) Compile and run each of the remaining example programs. PCL4P Users Manual Page 8 Using the Library The PCL4P has been tested on a TANDY 1000 ( 4.77 MHZ 8088 IBM PC clone ), a TANDY 3000 ( 80286 IBM AT clone ), a TANDY 1400LT ( IBM XT clone ), and a Gateway 2000 Cache ( 25 MHZ 80386-DX ). PCL4P has been tested under MSDOS 2.11, 3.2, 3.3, 4.01, and 5.0. Please examine the PCL4P.PAS file. Note that COM1 is defined as port zero, not port one. The user must assume the responsibilty for passing the correct information when calling PCL4P functions. For an example of PCL4P use, examine the terminal emulator program SIMPLE.PAS. The user should compile and link SIMPLE.PAS as a test of the library. If you have two computers, then you can connect them together with a null modem cable and run SIMPLE or TERM on both machines. Whatever is typed on one machine should appear on the other, and vice versa. If you have a modem, use TERM to call up any bulletin board system ( BBS ). Be sure to un-comment the code that initializes th modem. in the source code so that TERM sends an initialization string to your modem. There are many free BBSs around the country. Look in any issue of "Computer Shopper" ( available in bookstores, computer shops, and many grocery stores ) for a list of current systems. PCL4P Users Manual Page 9 Compiling Registered users may wish to assemble PCL4PLIB.ASM. To assemble using the Microsoft assembler: MASM PCL4PLIB /DPASCAL_MODEL; To build the library TPU: TPC PCL4P To compile the sample programs: TPC SIMPLE.PAS TPC LOOPBACK.PAS TPC TERM.PAS /m A makefile ( TERM.MAK ) is also provided for the TERM.PAS program. To compile TERM and all dependent units, type: MAKE -FTERM PCL4P Users Manual Page 10 Talking To Your Modem If your application uses a Modem ( as opposed to using a null modem cable ), then you should always send an initialization string to your modem if it is a programmable modem such as those made by Hayes. Communication programs such as PROCOMM and TELIX always send such a string automatically as soon as they start up. The particular initialization string depends on the make of your modem. For Hayes and Hayes compatible modems, the following string ( followed by a carriage return ) should work: AT E1 S7=60 S11=60 V1 X1 Q0 S0=0 Refer to your Hayes User's Guide for a full discussion of these commands. A brief description is as follows: AT Modem attention command. E1 Modem will echo what you send to it. S7=60 Wait 60 seconds for carrier and/or dial tone. S11=60 Use 60 milliseconds for tone dialing duration & spacing. V1 Display result code as words ( not numbers ). X1 Use the extended result message ( CONNECT XXXX ) set. Q0 Modem returns result codes. S0=0 Do not answer RING. If your application will answer incoming calls, then set the S0 register to the ring on which to automatically answer. If you send the above codes by using SioPutc ( as opposed to typing them from the keyboard ), then follow these guidelines: (1) Send an initial carriage return before the initialization string. (2) Pause at least two tics ( 18 tics to the second ) after each character sent as your modem needs the time to perform its own internal processing. Pause a little longer if your modem is not accepting your initialization string. (3) Pause one and a half seconds after sending any initialization command such as ATZ or AT&F since your modem must do quite a bit of processing. If you experience any problems in initializing your Hayes modem, you should first reset it to factory settings by sending: AT&F Refer to the TERM program ( functions SendTo and WaitFor in the file MODEM_IO.PAS ) for an example of sending an initialization string to a Hayes compatible modem. PCL4P Users Manual Page 11 Problems If you cannot get your application to run properly, first compile and run the terminal emulator program TERM provided on your distribution disk. If you are using a null modem cable or a non-programmable modem, be sure to set the HAYES constant to 0 in the source code ( #define HAYES 0 ). If you are using a Hayes compatible modem, set the HAYES constant to 1. If you are using a programmable modem which is not Hayes compatible, then you must modify the initialization string for your particular modem. If your application does not run but TERM runs correctly, then you have most likely made a programming mistake in your application. MarshallSoft Computing cannot debug your application, especially over the telephone! However, consider each of the following when searching for an error in your application. 1. Did you include the "uses PCL4P" statement ? 2. Is your receive buffer large enough ? If you are using 1K data blocks in YMODEM, then your receive buffer should be at least 1K ( 2K if baud rates above 38400 are to be used ). 4. Have you selected too high a baud rate ( if you are using a slow PC ) ? If only one COM port is being run, you should be able to run at 38400 baud on 8088 machines and 115200 on most 286 and all 386 and 486 machines. 5. Are you attempting to run another application in the background ? Try running without any other programs running in the background ( unload all TSR programs ). 6. If you are running two COM ports simultaneously, are you using separate receive buffers ? ( you should ). 7. Did SioReset return a zero value ? If not, then you must call SioReset again. See TERM.PAS for an example. 8. Did you send the proper initialization string to your modem ? Did you set DTR and RTS ? ( you should ). 9. Do you have more than one COM1 port, etc. For example, if you have a COM1 port on your motherboard, you cannot add another COM1 port or modem board that uses COM1 without first disabling the COM1 on the motherboard. Registered users can call (205) 881 - 4630 from 5 PM to 8 PM CST Monday through Friday for help. PCL4P Users Manual Page 12 Function Summary Refer to the PCL4P Reference Manual ( PCL4P.REF ) for detailed information on the communications and support functions. A one line summary of each function follows: SioBaud Sets the baud rate of the selected port. SioBrkKey Returns non-zero if the Control-BREAK key was pressed. SioBrkSig Asserts, cancels, or detects BREAK signal. SioCTS Reads the Clear to Send (CTS) modem status bit. SioDCD Reads the Data Carrier Detect (DCD) modem status bit. SioDelay Delays one or more tics ( 18 tics per second ). SioDone Terminates further serial processing. SioDSR Reads the Data Set Ready (DSR) modem status bit. SioDTR Set, clear, or read the Data Terminal Ready (DTR) bit. SioError Displays error in text. SioFIFO Sets the FIFO trigger level ( INS16550 only ). SioGetc Reads the next character from the serial line. SioIRQ Assigns a IRQ line to a port. SioLine Reads the line status register. SioLoopBack Performs a UART loopback test. SioModel Returns a code corresponding to the memory model used. SioModem Reads the modem status register. SioParms Sets parity, stop bits, and word length. SioPutc Transmit a character over a serial line. SioReset Initialize a serial port for processing. SioRI Reads the Ring Indicator (RI) modem status bit. SioRTS Sets, clears, or reads the Request to Send (RTS) line. SioRxBuf Sets up receive buffer. SioRxFlush Flushes ( clears ) the receive buffer. SioRxQue Returns the number of characters in the receive queue. SioTimer Returns the number of system clock tics. SioUART Sets the UART base address. SioUnGetc "Un-gets" ( puts back ) a specified character. PCL4P Users Manual Page 13 Serial Communications The heart of serial communications is the UART ( Universal Asynchronous Receiver Transmitter ). The IBM PC/XT/AT and compatibles use the INS8250, INS16450, or the INS16550 UART. The purpose of the UART is: (1) To convert bytes from the CPU ( Central Processing Unit ), into a serial format by adding the necessary start, stop, and parity bits to each byte before transmission, and to then transmit each bit at the correct baud rate. (2) To convert the incoming stream ( at a specified baud rate ) of serial bits into bytes by removing the start, stop, and parity bits before being made available to the CPU. The UART is part of the serial interface circuitry which allows the CPU to send and receive signals over the RS232 lines. This can be diagrammed as follows: Serial Interface ********************* * * ******* Data Bus * ******** * RS232 Signals * CPU ************** * UART * ****************** ******* * ******** * * * ********************* The INS8250/16450/16550 UART is capable of operating in one of two modes, "polled" and "interrupt driven". The serial communications functions in the BIOS uses the polled method. In this approach, the CPU is typically in a loop asking the UART over and over again if it has a byte ready. If its does, the polling code returns the byte. But, if the next byte comes in before the polling code is executing again, then that byte is lost. In the interrupt driven approach ( used by PCL4C for incoming data ), when a byte is received by the UART, an "Interrupt Service Routine" ( ISR ) is executed immediately, suspending temporarily whatever else is executing. The ISR then moves the byte to a buffer so that your application program can later read it. Refer to the sections entitled "RS232 Signals" and "National INS8250 UART" for further information on these topics. The best way to learn about serial communications is to read a good book on the subject. Several good texts are available. Two that I like are: (1) C Programmers's Guide to Serial Communications by Joe Campbell (SAMS) (2) Mastering Serial Communications by Peter Gofton (SYBEX). PCL4P Users Manual Page 14 IBM Communications Ports There are a few things to know about how serial communications ports are used by IBM PC/XT/AT and compatible computers. The standard IBM PC/XT/AT configuration values are as follows: Port Reg Base IRQ Line Vector COM1 3F8H 4 12 COM2 2F8H 3 11 COM3 3E8H 4 12 COM4 2E8H 3 11 PCL4P assumes the above values. If necessary, the UART base address can be changed by SioUART. However, the IRQ and Service vector values can not be changed ( unless you modify the source code ). When installing new communications cards, the following guidelines are recommended: (1) Be sure to read the documentaion for the hardware you are installing. Pay special attention to UART base addresses and IRQ lines. (2) If you have a choice in base addresses and IRQ lines, always choose standard values as defined above. (3) The first port should be COM1, the second COM2, etc. (4) Use SioUART to zero all unused ports ( for example, call SioUART(COM4,0) if there is no COM4 port installed ). (5) Be carefull not to configure two ports for the same address. This is easier to do than you may believe. (6) Choose an external modem over an internal one. It is much easier to debug problems with an external modem than an internal one. (7) Always test your port as soon as it is installed. PCL4P Users Manual Page 15 RS232 Signals RS-232 is the name of the serial data interface standard used to connect computers to modems. Most IBM compatible computers are built with at least one serial port and use either DB9 ( 9 pin ) or DB25 ( 25 pin ) connectors. A summary of these pins and their function follows. For more detailed information, refer to one of the many books dealing with RS-232 interfacing. Signal Ground Pin 7 (DB25), Pin 5 (DB9) The SG line is used as the common signal ground, and must always be connected. Transmit Data Pin 2 (DB25), Pin 3 (DB9) The TX line is used to carry data from the computer to the modem. Receive Data Pin 3 (DB25), Pin 2 (DB9) The RX line is used to carry data from the modem to the computer. Data Terminal Ready Pin 20 (DB25), Pin 4 (DB9) The DTR line is used by the computer to signal the modem that it is ready. Data Set Ready Pin 6 (DB25), Pin 6 (DB9) The DSR line is used by the modem to signal the computer that it is ready. Request to Send Pin 4 (DB25), Pin 7 (DB9) The RTS line is used to "turn the line around" in half duplex modems, but is not necessary in full duplex modems. Clear to Send Pin 5 (DB25), Pin 8 (DB9) The CTS line, like the RTS line, is not necessary in full duplex modems. Data Carrier Detect Pin 8 (DB25), Pin 1 (DB9) The DCD line is used by the modem to signal the computer that a data carrier signal is present. Ring Indicator Pin 22 (DB25), Pin 9 (DB9) The RI line is asserted when a 'ring' occurs. PCL4P Users Manual Page 16 National INS8250, INS16450, and INS16550 UARTs The Personal Communications Library is based on the standard National INS8250, INS16450, and INS16550 UARTs. The 8250 was the original UART used in the IBM PC, whereas the 16450 is a faster version found on most 286 & up machines. The 16550 contains a 16 byte FIFO to further reduce communications overhead. These UARTs consists of 8 register ports as follows: Offset R/W Register 0 R/W Receiver ( read ) / Transmitter ( write ) 1 R/W Interrupt Enable ( read ) 2 R Interrupt Identification 2 W FIFO control ( INS16550 only ) 3 R/W Data Format ( Line Control ) 4 R/W RS-232 ( Modem ) Control 5 R/W Line Status 6 R/W RS-232 ( Modem ) Status 7 R/W Not used. The UART registers are based at 3F8 (COM1), 2F8 (COM2), 3E8 (COM3), and 2E8 (COM4). COM1 and COM3 share interrupt vector 12 and interrupt request line IRQ4 while COM2 and COM4 share interrupt vector 11 and interrupt request line IRQ3. This means that COM1 and COM3 cannot both be used at the same time. Similarly, COM2 and COM4 cannot both be used at the same time. Port Reg Base IRQ Line Vector COM1 3F8H 4 12 COM2 2F8H 3 11 COM3 3E8H 4 12 COM4 2E8H 3 11 Four sources of interrupts are possible with the 8250 and 16550: (1) receiver error or BREAK, (2) receiver data ready, (3) ready to transmit, and (4) RS232 input. These four sources of interrupts are summarized as follows: Source of Interrupt Action Required to Clear Receiver error or BREAK. Read Line Status register. Receiver data. Read data from data register. Transmitter Buffer Empty. Write to data register or read IID reg. RS232 input. Read Modem Status register. However, PCL4C only enables the receiving data interrupt. This means that interrupts can only be caused by incoming data. If you are not familiar with the INS8250, several good books are available. Refer to the Serial Communications chapter for recommendations. Although a knowledge of the 8250 is not necessary to use PCL4C, a general knowledge of the theory of asynchronous serial communications is recommended. PCL4P Users Manual Page 17 Register Summary REG 0 : Data Register Reading from the data register fetches the next input byte, once it is ready. Writing to the data register transmits the byte written to it over the serial line. REG 1 : Interrupt Enable The Interrupt Enable register enables each of four types of interrupts when the appropriate bit is set to a one. bit 3 : Enable interrupt on RS232 input. bit 2 : Enable interrupt on receiver error or break. bit 1 : Enable interrupt on transmitter buffer empty ( TBE ). bit 0 : Enable interrupt on received data ( RxRDY ). REG 2 : Interrupt Identification (IID) Reading the Interrupt Identification ( read only ) register once an interrupt has occurred identifies the interrupt as follows: Bit 2 Bit 1 Bit 0 Priority Interrupt 0 0 1 none none 1 1 0 0 (high) Serialization or break. 1 0 0 1 Received data. 0 1 0 2 Transmitter Buffer Empty. 0 0 0 3 (low) RS232 Input. In the INS16650, REG 2 ( write only ) is also the FIFO control register. Writing bits 6 & 7 will set the FIFO trigger level ( number of bytes received before an interrupt is generated ). Bit 7 Bit 6 Trigger Bit 7 Bit 6 Trigger 0 0 1 byte 1 1 8 bytes 0 1 4 bytes 1 1 14 bytes REG 3 : Line Control RS232 line parameters are selected by writing to this register. bit 7 : DLAB = 0 bit 6 : BREAK on(1), off(0). bits 5-3: Parity None(000),ODD(001),EVEN(011),MARK(101),SPACE(111) bit 2 : One stop bit(0), two stop bits(1). bits 1-0: Data bits = 5 (00), 6(01), 7(10), 8(11). When the Divisor Latch Access Bit ( DLAB ) is 1, registers 0 and 1 become the LS and MS bytes of the Baud Rate Divisor registers. Baud Divisor Baud Divisor Baud Divisor 300 0180 4800 0018 38400 0003 1200 0060 9600 000C 57600 0002 2400 0030 19200 0006 115200 0001 PCL4P Users Manual Page 18 REG 4 : Modem Control RTS, DTR, loopback testing, and General Purpose Outputs #1 and #2 are controlled by the Modem Control register as follows: bit 4 : Enable local loopback. bit 3 : Enable GP02. Necessary for 8250 interrupts. bit 2 : Enable GP01. bit 1 : Set / clear RTS. bit 0 : Set / clear DTR. REG 5 : Line Status Reading the Line Status register provides status information as follows ( 1 for TRUE, 0 for FALSE ) : bit 6 : Transmitter Empty. bit 5 : Transmitter Buffer Empty ( TBE ). bit 4 : BREAK detect. bit 3 : Framing error. bit 2 : Parity error. bit 1 : Overrun error. bit 0 : Data Ready. REG 6 : Modem Status Reading the Modem Status register provides the following status information ( 1 for TRUE, 0 for FALSE ) : bit 7 : DCD status. bit 6 : RI status. bit 5 : DSR status. bit 4 : CTS status. bit 3 : Delta DCD status. bit 2 : Delta RI status. bit 1 : Delta DSR status. bit 0 : Delta CTS status. The delta bits ( bits 0 through 3 ) are set whenever one of the status bits ( bits 4 through 7 ) changes ( from 0 to 1 or from 1 to 0 ) since the last time that the Modem Status register was read. Reading the Modem Status register clear the delta bits. REG 7 : Scratch Register There is no function associated with register 7. It does not exist in early versions of the 8250. PCL4P Users Manual Page 19 Example Code The following programs are provided as examples of the use of the PCL4P library. They are not part of the PCL4P library, and may be used in any way the user wishes. Makefiles ( small model ) are provided for all example code. SIMPLE SIMPLE is an extremely simple terminal emulator program. It is provided as the smallest and easiest to understand example of serial communications programming using PCL4P. To start SIMPLE, just type SIMPLE. The baud rate is set at 2400 and can be easily changed in the source code. Similiarly the port is set to COM1 and is easily changed in the source code. Note that SIMPLE does not send an initialization string to your modem. TERM TERM is a more capable terminal emulator than SIMPLE. It functions as a dumb terminal emulator but can exchange files using XMODEM ( Standard XMODEM, XMODEM-CRC, and XMODEM-1K ) and YMODEM ( batch capability ) communications protocols. TERM will also send an initialization string to your Hayes compatible modem. To start TERM, type TERM followed by the port ( 1 to 4 ) and the baud rate ( 300, 600, 1200, 2400, 4800, 9600, 19200, 38400, 57600, or 115200). For example, "TERM 4 2400". LOOPBACK LOOPBACK performs a loopback test of the selected port UART. This is useful for testing a serial port UART that is suspected of being bad. However, defective UARTS are very unusual. Start LOOPBACK by typing LOOPBACK followed by the port ( 1 to 4 ). For example "LOOPBACK 4". MODEM MODEM displays the modem status lines (DSR, CTS, DCD, and RI) and the modem control lines (DTR and RTS). Additionally, it allows the user to set or clear the modem control lines. MODEM is useful when testing RS232 cable connections. To start MODEM, type MODEM followed by the port ( 1 to 4 ). For example "MODEM 1". PCL4P Users Manual Page 20 Revision History Version 1.0 -- 14 January 1991 -- original release. Version 1.1 -- 11 March 1991 o Added SioUnGetc() function to library. o Minor documentation changes. Version 1.2 -- 1 June 1991 o Name changed to Personal Communications Library. o Minor bug fixes. Version 1.3 -- 1 July 1991 o Added NORESET option to SioReset. o Added SioDSR, SioCTS, SioDCD, and SioRI. o Added SioLoopBack function to library. o Added LOOPBACK.PAS example program. Version 2.0 -- 1 Nov 1991 o All example code released in shareware package. o Fixed bug due to Microsoft Assembler (MASM 5.0,5.1) error. o Greatly expanded documentation. ( MarshallSoft incorporated on December 23, 1991 ) Version 3.0 -- 15 Jan 1991 o Added XMODEM & YMODEM to example code. o Added SioUART function. o Added "UART undefined" error code. o Added "Bad or missing UART" error code. o Added "Port already enabled" error code. o Added "Cannot enable both COM1 & COM3 ..." error code. o Fixed several minor bugs ( using new automated testing ). Version 3.1 -- 1 March 1992 o Added SioFIFO ( INS16550 only ). o Added SioIRQ function. o Increased maximum receive buffer size to 32K bytes. o Added MODEM.C example code. PCL4P Users Manual Page 21 License MarshallSoft Computing, Inc. grants the registered user of PCL4P the right to use the PCL4P library ( in object form ) in the development of any software product without any royalties. However, the source code for the library may not be released in whole or in part. Warranty MARSHALLSOFT COMPUTING, INC. DISCLAIMS ALL WARRANTIES RELATING TO THIS SOFTWARE, WHETHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, AND ALL SUCH WARRANTIES ARE EXPRESSLY AND SPECIFICALLY DISCLAIMED. NEITHER MARSHALLSOFT COMPUTING, INC. NOR ANYONE ELSE WHO HAS BEEN INVOLVED IN THE CREATION, PRODUCTION, OR DELIVERY OF THIS SOFTWARE SHALL BE LIABLE FOR ANY INDIRECT, CONSEQUENTIAL, OR INCIDENTAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE SUCH SOFTWARE EVEN IF MARSHALLSOFT COMPUTING, INC. HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES OR CLAIMS. IN NO EVENT SHALL MARSHALLSOFT COMPUTING, INC.'S LIABILITY FOR ANY SUCH DAMAGES EVER EXCEED THE PRICE PAID FOR THE LICENSE TO USE THE SOFTWARE, REGARDLESS OF THE FORM OF THE CLAIM. THE PERSON USING THE SOFTWARE BEARS ALL RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE. Some states do not allow the exclusion of the limit of liability for consequential or incidental damages, so the above limitation may not apply to you. This agreement shall be governed by the laws of the State of Alabama and shall inure to the benefit of Marshallsoft Computing, Inc. and any successors, administrators, heirs and assigns. Any action or proceeding brought by either party against the other arising out of or related to this agreement shall be brought only in a STATE or FEDERAL COURT of competent jurisdiction located in Madison County, Alabama. The parties hereby consent to in personam jurisdiction of said courts. PCL4P Users Manual Page 22