Visual Basic 4 Power Pack

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

/ Visual Basic 4 Power Pack / Visual_Basic4_Power_Pack.bin / vb4files / pclvbw11 / pclvbw_u.doc < prev next >

Wrap

Text File | 1996-11-20 | 69.3 KB | 2,109 lines

Personal Communications Library For Visual BASIC (Windows) (PCLVBW) USERS MANUAL Version 1.1 July 1, 1996 This software is provided as-is. There are no warranties, expressed or implied. Copyright (C) 1996 All rights reserved MarshallSoft Computing, Inc. Post Office Box 4543 Huntsville AL 35815 Voice : 205-881-4630 FAX : 205|880|0925 BBS : 205-880-9748 email : info@marshallsoft.com web : www.marshallsoft.com _______ ____|__ | (R) --+ | +------------------- | ____|__ | Association of | | |_| Shareware |__| o | Professionals --+--+ | +--------------------- |___|___| MEMBER PCLVBW Users Manual Page 1 C O N T E N T S Chapter Page 1.0 Introduction................................................3 1.1 User Support............................................4 1.2 ASP Ombudsman...........................................4 1.3 Determining UART Address & IRQ Settings.................5 1.4 Disabling Windows Ports.................................5 1.5 Installation............................................6 2.0 Library Organization........................................7 2.1 Configuration...........................................7 2.2 Initialization & Termination............................7 2.3 Modem Control & Status..................................8 2.4 Serial I/O..............................................8 2.5 Error Detection.........................................9 2.6 General Support.........................................9 3.0 Library Overview...........................................10 3.1 Using the Library......................................10 3.2 Example Programs.......................................10 3.2.1 SIMPLE...........................................10 3.2.2 LOGIN............................................10 3.2.3 SELFTEST.........................................10 3.3 Door Programs..........................................11 3.4 BBS Programs...........................................11 3.5 Library Versions.......................................11 3.6 Compiling & Linking....................................11 4.0 Talking to Your Modem......................................12 4.1 Modem Standards........................................12 4.2 Flow Control...........................................13 4.3 Modem I/O (MIO)........................................14 4.3.1 MIO Introduction.................................14 4.3.2 MIO Functions....................................15 4.3.2.1 mioDriver................................15 4.3.2.2 mioBreak.................................15 4.3.2.3 mioSendTo................................15 4.3.2.4 mioWaitFor...............................15 4.3.2.5 mioQuiet.................................16 4.4.3 MIO Summary......................................16 4.4 Modem Initialization...................................17 5.0 Problems...................................................18 6.0 Serial Communications......................................19 6.1 Communications Basics..................................19 6.2 Standard Port Addresses................................20 6.3 Running 3 or 4 Ports Concurrently......................21 6.4 Using Multiport Cards..................................22 6.4.1 The DigiBoard....................................22 6.4.2 The BOCA Board...................................22 6.5 Transmitter Interrupts.................................23 6.6 RS232 Signals..........................................24 6.7 National 8250, 6450, and 16550 UARTs...................25 6.8 Register Summary.......................................26 7.0 [reserved section number] 8.0 Legal Issues...............................................28 8.1 Registration...........................................28 8.2 License................................................28 8.3 Warranty...............................................28 9.0 Summary....................................................30 9.1 Revision History.......................................30 9.2 Function Summary.......................................30 9.3 Further Reading........................................31 10.0 Other MarshallSoft Computing Products .....................31 10.1 Windows Standard Communications.......................31 PCLVBW Users Manual Page 2 1.0 Introduction The Personal Communications Library for Visual BASIC / Windows (PCLVBW) is an asynchronous communications library designed for experienced software developers programming in Windows using Visual BASIC. PCLVBW controls the serial port hardware directly. It does not use the Windows serial communications API functions. This allows up to 20 ports with a maximum baud rate of 115,200 baud. The PCL features: o 36 communications and support functions. o Supports the high performance 16550 UART. o Use IRQ2 to IRQ15 with any UART address. o Supports the PC/4 and PC/8 DigiBoard. o Supports the BOCA BB1004, BB1008, and BB2016 boards. o Supports hardware (RTS/CTS) flow control. o Interrupt driven receiver & (optionally) transmitter. o Supports 300 baud to 115,200 baud. o Supports COM1 through COM8 (through COM20 with multiport boards) o Adjustable receive queues from 8 bytes to 32 KB. o Control-BREAK error exit. o 18 communications error conditions trapped. o Allows 4 ports to run concurrently (more with multiport boards). o Complete modem control & status. o Written in assembly language for small size & high speed. o Does NOT use the Windows communications driver. Why should you buy PCLVBW ? Several good reasons are: COMPLETE - PCLVBW is complete since it provides absolute control of the serial ports (including the high performance 16550). COMPACT - PCLVBW is very compact at less than 8 KB. Your application doesn't carry a lot of excess code. FAST - PCLVBW is fast since it runs at 38400 baud on even slow 286 PCs and at 115200 baud on most everything else. SUPPORT - If you get stuck, you talk to the programmer that wrote the code, not a person hired to answer the phone. BBS - A BBS is available (2400 to 14,400 baud, N81) in order to provide immediate support as necessary. NEWSLETTER - Our newsletter discusses "COMM TALK" is published quarterly (available online) which discusses communications problems and solutions. PRICE - You get PCLVBW for a very reasonable price! UPGRADES - Once you buy PCLVBW, you can always update to the most recent version very inexpensively ($25 plus shipping). Be sure to read the README.DOC file. It contains last release notes and other last minutes changes and/or additions. PCLVBW Users Manual Page 3 1.1 User Support We want you to be successful in developing your applications using PCLVBW! We depend on our customers to let us know what they need in a communications library. This means we are committed to providing the best communications library that we can. If you have any suggestions or comments, please let us know! We provide customer support for registered customers by voice, FAX, BBS, email, and US mail. We provide limited support for unregistered users by voice, email, and BBS only. If you are having a problem using PCLVBW, call us at 205-881-4630 between 1:30 PM and 9:30 PM (CST) Monday through Friday. You can also call at other times and leave a message, and call back later for a reply. Registered users (ONLY) can also FAX us at 205-880-0925 at any time (24 hours). However, we can only answer questions with respect to using the PCLVBW library. We cannot help you program your application, but we'll be glad to discuss it with you. You may also call our User Support BBS (2400 to 14400 baud, no parity, 8 data bits, 1 stop bit) at 205-880-9748 and leave a message (address it to the SYSOP). We will usually have a reply ready for you within 24 hours. The BBS is available 24 hours per day. All files are in standard ZIP format. The BBS will contain the latest shareware version of all MarshallSoft Computing products as well as related files such as: BUGS.ZIP - Bug report. PRODUCTS.ZIP - List of all shareware products. The MarshallSoft Computing, Inc. newsletter "Comm Talk" is published quarterly. It discusses various communications problems and solutions using PCLVBW as well as related information. The latest copy of our newsletter can be found on our support BBS, anonymous FTP site, or on our Web site. BBS : 205-880-9748 (look in file area "Newsletters") Anon FTP : ftp.marshallsoft.com (directory /marshallsoft) Web site : www.marshallsoft.com 1.2 ASP Ombudsman MarshallSoft Computing, Inc. is a member of the Association of Shareware Professionals (ASP). ASP wants to make sure that the shareware principle works for you. If you are unable to resolve a shareware-related problem with an ASP member by contacting the member directly, ASP may be able to help. The ASP Ombudsman can help you resolve a dispute or problem with an ASP member, but does not provide technical support for members' products. Please write to the ASP Ombudsman at 545 Grover Road, Muskegon, MI USA 49442-9427, Fax 616-788-2765, or send a CompuServe message via CompuServe Mail to ASP Ombudsman 70007,3536. PCLVBW Users Manual Page 4 1.3 Determining UART Address & IRQ Settings Both Windows 3.X and Windows 95 maintain a list of serial port settings. On Windows 3.X systems, choose the "Ports" icon in the "Control Panel" in the "Main Group". Select "Settings", and then "Advanced" to view the COM port UART address and IRQ settings. In Windows 95, choose "My Computer" icon ("or whatever your computer icon is named), select the "Control Panel" folder and then the "System" icon. Click on the "Device Manager" tab. Click "Computer" and then click "Properties". Click the "View Resources" tab. To view reserved resources, click the resource type at the top of the dialog box (i.e., "Interrupt request (IRQ)" or "Input/output (I/O)" ). 1.4 Disabling Windows Ports The Windows operating system virtualizes all serial ports that it controls. This means that Windows intercepts reads and writes to hardware ports, resulting in significant slowdown. And, when Windows virtualizes a port, the UART FIFO control register (FCR) can not be modified. Since PCLVBW also controls the hardware directly, it is best (although not absolutely necessary) to disable Windows control of the serial ports and the IRQs that will be used by PCLVBW applications. The four standard COM ports which Windows typically controls are: Port Address IRQ COM1 &H3F8 4 COM2 &H2F8 3 COM3 &H3E8 4 COM4 &H2E8 3 Since COM1 and COM3 share an IRQ, if either is to be used by PCLVBW then both should be disabled from Windows control. Similarly for COM2 and COM4. To begin, exit from Windows completely. To disable the serial ports, edit the [386Enh] section of the WINDOWS.INI file in the WINDOWS directory. For example, to disable COM1 and COM3, add the following to the [386 Ehn] section: COM1Base=0 COM1Irq=-1 COM3Base=0 COM3Irq=-1 Restart Windows after modifying SYSTEM.INI. This procedure does not apply to multiport boards or any other serial ports unknown to Windows. 16550 UARTS are really necessary when running under Windows, particularly at baud rate above 19200. The Microsoft Diagnostics (MSD) program can be run which will report the type of UARTs installed on your machine. If a 16550 port MUST be shared with Windows, and you want the FIFO enabled, look for statements such as COM1FIFO=0 in the [386Ehn] section of SYSTEM.INI and delete it. However, the Windows communications driver may have trouble with the FIFO, which is why there is a statement to disable it. This problem does not occur with PCLVBW. PCLVBW Users Manual Page 5 1.5 Installation (1) Before installation of PCLVBW, your Visual BASIC compiler should already be installed on your system and tested. It is recommended that you disable Windows's control of the serial ports that you will be using. Refer to section 1.3 "Disabling Windows Ports". (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 PCLVBW, we first log onto the work disk and then type: MKDIR PCLVBW (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 PCLVBW COPY A:*.* (5) Copy the DLL (dynamic link libraries) PCLVBW.DLL, PCLVBWN.DLL, and MIO.DLL and the icon file MSC.ICO, to the directory from which Visual Basic is running. This is the directory reported by selecting FILES, and then PROPERTIES on the Windows menu bar after clicking (once) on the Visual Basic icon. (6) Start Visual Basic, and load the SIMPLE example program by opening project SIMPLE.MAK. It can then be run by choosing RUN on the Visual Basic menu bar. If Visual Basic cannot load the DLLs, it means that they have not been copied into the Visual Basic directory as outlined in (5) above. (7) Also load and compile LOGIN. (8) The easiest 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. SIMPLE can also be tested by connecting your port to a modem. (9) LOGIN can be tested by connecting to a modem. Select MODEM/START/HANDSHAKE on the dial menu bar to send an AT to the connected modem. An "OK" is expected in return. Selecting MODEM/START/DIAL will dial the MarshallSoft Computing BBS. (10) Load and compile SELFTEST. SELFTEST performs a UART loopback test using either a loopback adapter or null modem cable. See section 3.2 "Example Programs" for more information. PCLVBW Users Manual Page 6 2.0 Library Organization The PCLVBW library is organized into six categories of functions. Refer to the PCL Reference Manual (PCLVBW.REF) for details on individual functions. 2.1 Configuration There are three functions in the configuration category. SioPorts sets the number of PC and DigiBoard (or BOCA board) ports. SioUART is used to change the UART base address for a communications port to a non-standard address, while SioIRQ is used to assign a nonstandard IRQ line to a port. (See chapter 6 Serial Communications for more details on standard UART addresses and IRQ lines). The configuration functions SioPorts, SioUART and SioIRQ must be called before calling any other library functions. Be very careful in using these functions. Remember that your serial hardware must support the UART and IRQ that you specify. Always test any new configuration immediately. SioPorts - Sets number of PC and DigiBoard (or BOCA board) ports. SioUART | Sets the UART base address. SioIRQ - Assigns an IRQ line to a port. THE IRQ GOLDEN RULE: You may open (via SioReset) only one port per IRQ (except for the DigiBoard and BOCA board). Be sure to read section 1.3 "Disabling Windows Ports" since it is best not to share ports with Windows. 2.2 Initialization & Termination There are eight functions in the initialization and termination category. Together, SioParms, SioFIFO, SioRxBuf, SioTxBuf, 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. SioFlow can be called to enable hardware flow control. Before exiting from your application, SioDone must be called. Failure to call SioDone can crash your system later. SioRxBuf - Sets up receive buffer. SioTxBuf | Sets up transmitter buffer. SioFIFO | Sets the interrupt level for the 16550. 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. SioFlow - Enables / disables flow control. PCLVBW Users Manual Page 7 2.3 Modem Control & Status There are nine 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. SioGetDiv reads the baud rate divisor register so the baud rate can be determined. 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. SioRead | Reads the contents of the 7 UART registers. SioGetDiv - Reads the baud rate divisor registers. 2.4 Serial I/O There are eleven 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 read and write single bytes from the serial line. SioUnGetc "ungets" the last serial byte read. SioRxClear clears the receive queue while SioTxClear clears the transmit queue. SioLine can be used to test for UART errors. SioTxFlush completes transmission of all bytes in the transmit buffer before returning. SioRxQue returns the number of bytes in the receive queue while SioTxQue returns the number of bytes in the transmit queue. 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. SioRxClear | Clears the receive buffer. SioRxQue | Returns the number of characters in the RX queue. SioTxClear | Clears the transmit buffer. SioTxFlush | Flushes the transmit buffer. SioTxQue | Returns the number of characters in the TX queue. SioLine - Reads the line status register. PCLVBW Users Manual Page 8 2.5 Error Detection There are two 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. 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. SioBrkSig - Asserts, cancels, or detects the RS232 BREAK signal. SioLoopBack - Performs a UART loopback test. 2.6 General Support There is just one functions in the general support category. SioInfo returns a host of information, such as the PCLVBW library version, the number of transmitter and receiver interrupts, etc. SioInfo - Returns the library version, and various other info. PCLVBW Users Manual Page 9 3.0 Library Organization 3.1 Using the Library Please examine the PCLVBW.BAS 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 PCLVBW functions. If there are any conflicts between PCLVBW definitions and those in other libraries, the PCLVBW definitions can be changed in the PCLVBW.BI file and any file that uses the definition. There is no change necessary for the library code itself. The PCLVBW libraries contain no references to any runtime libraries. Only Windows API functions are called. 3.2 Example Programs 3.2.1 SIMPLE SIMPLE is a very simple communications programming using PCLVBW. Everything that is typed on the keyboard is sent to the serial port, and everthing incoming from the serial port is displayed on the screen. Load SIMPLE.MAK from Visual Basic. Select "Change" from the menu bar to change the port, baud rate, parity, data bits, or stop bits. Select "OnLine" from the "Line" menu item to go online. Test SIMPLE by connecting the port it controls to a modem and issuing AT commands, or connect to another computer using a null modem cable. 3.2.2 LOGIN LOGIN is the same program as SIMPLE but with the addition of "Modem" on the menu bar. Under "Modem", select "Start", then "Handshake" in order to send an "AT" to the connected modem, or "Dial" to send a dial string to the modem (which dials our user support BBS). Once the dial sequence is sent, the program will wait for up to 60 seconds for the "CONNECT" string from the modem. This wait can be terminated at any time by choosing "BREAK" under "Modem". LOGIN serves as an example of the use of the MIO.BAS (modem I/O) functions. Refer to section 4.3 "Modem I/O" for more information on MIO functions. To test LOGIN, you need a AT command set compatible modem and a BBS to call up. LOGIN will dial our BBS at 205-880-9748, or edit the dial string in LOGLINE.BAS to call up a local BBS. 3.2.3 SELFTEST SELFTEST performs a serial port I/O functionality test. A single port can be tested if a loopback adapter is connected to the end of the serial cable. Refer to LOOPBACK.DOC for an explanation of how to make a loopback adapter. Two ports on a single machine connected by a null-modem adapter can also be tested by connecting them together with a null modem cable. PCLVBW Users Manual Page 10 3.3 Door Programs In order to write a door program which "takes over" a serial port without resetting the port or changing the baud rate, call SioReset() with NORESET as the second argument rather than the baud rate. Call SioGetDiv() to get the baud rate divisor if the baud rate must be determined. Be sure to call SioDone() before returning to the invoking program. 3.4 BBS Programs If you are designing a BBS program (also known as HOST programs), consider using 16550 UARTS. You should also choose a multiport card such as the DigiBoard or BOCA board if you wish to run more than 4 ports simultaneously. If you are using an error correcting modem, then you should be sure to set flow control and fix your baud rate at the highest possible transfer rates. For 14,400 modems, this means 19200 or 38400. You may need a 16550 UART in order to run at the higher speed. If you are using an older multi-speed modem (say 1200, 2400, 4800, 9600) that doesn't use flow control, you should change your baud rate to match the baud rate as reported by the modem with the CONNECT message if necessary. 3.5 Library Versions Two versions of the PCL library are provided. PCLVBW.DLL is the dynamic link library (DLL) with transmitter interrupts enabled. This is the version normally used. PCLVBWN.DLL is the version of our library in which transmitter interrupts are NOT enabled. Any application in which most serial I/O activity is input may benefit from using this version of the library. A typical example would be a data logging application. To use PCLVBWN: RENAME PCLVBW.DLL PCLVBWY.DLL COPY PCLVBWN.DLL PCLVBW.DLL Copy the new PCLVBW.DLL to the Visual Basic compiler directory. 3.6 Compiling and Linking Registered users may wish to recreate PCLVBW.DLL. The Microsoft assembler (MASM) and the Microsoft C compiler are required. Type NMAKE PCL4W.MAK RENAME PCL4W.DLL PCLVBW.DLL Similiarly, MIO.DLL can be recreated. PCLVBW Users Manual Page 11 4.0 Talking to Your Modem A modem is used to extend the distance over which you may communicate. Without a modem, your RS232 cable is limited to a maximum of approximately 50 feet. But with a modem, you can communicate literally around the world. Also refer to Section 4.3 "MODEM I/O functions" for details on MODEM I/O functions. These functions faciliate communications with modems. 4.1 Modem Standards Two modems can communicate over a telephone line only if they are both using the same signaling frequencies and modulation, which are determined by the the modem standards used. Modem standards can be divided into three sets: (1) speed, (2) data compression used, and (3) error control. The Bell standards (103 & 212A) are those of AT&T. The CCITT (The International Consultative Committee for Telephone and Telegraph) standards are designated as "V. ". Speed Bell 103 - 300 baud Bell 212A | 1200 baud V.21 | 300 baud V.22bis | 1200 & 2400 baud V.32 | 4800 & 9600 baud V.32bis | 4800, 7200, 9600, 12000, and 14400 baud V.34 - 28800 baud. Data Compression MNP 5 - Microcom Networking Protocol (proprietary). V.42bis - International data compression standard. Error Control MNP 2,3,4 - Three level error correction (public domain). V.42 - International error correction standard. Most of the newer high speed modems use several of the above standards. However, not all combinations of modem makes communicate easily with each other, especially at high speeds (19200 and up). PCLVBW Users Manual Page 12 4.2 Flow Control With modems using data compression, the modem to modem connection will run at various speeds depending on the quality of the line. The computer to modem connection will be at a fixed baud rate. Therefore, a protocol (flow control) is necessary to synchronize the data flow between a modem and the computer to which it is connected. Refer to your modem manual for information on flow control protocols supported. Two flow control protocols are used by most all modems which require flow control. Software flow control is called "XON/XOFF" (other software flow control character pairs are defined but operate the same as XON/XOFF) and hardware flow control is called "RTS/CTS". Most modems which require flow control enable hardware flow control by default. In XON/XOFF (software) flow control, the computer suspends transmitting data if it receives a XOFF character (13 hex) from the modem, and continues transmitting when it receives a XON character (11 hex). Similiarly, the computer can signal the modem not to send any more data by transmitting a XOFF to it, and can tell the modem to continue transmission be sending a XON. In RTS/CTS (hardware) flow control, the RTS line is used by the computer to signal the modem , while the CTS line is used by the modem to signal the computer. The RTS line is set OFF by the computer to tell the modem to suspend transmission, and set to ON to tell the modem to continue transmission. The CTS line is set to OFF by the modem to tell the computer to stop transmitting, and set to ON to tell the computer to continue transmitting. Given the choice, always choose hardware flow control over software flow control so that all data transmission is transparent. If hardware flow control is not the default (which it almost always is), you should modify your modem initialization string to turn hardware flow control on. You will not need to use flow control when exchanging data between computers connected by a null modem cable (no modems) as long as each packet is acknowledged (as in XMODEM and YMODEM) and the buffer size is at least as large as the packet size. PCLVBW Users Manual Page 13 4.3 MODEM I/O (MIO) 4.3.1 MIO Introduction The file MIO.BAS contains declarations for using the Modem I/O DLL. These functions ease communicating with modems using AT commands. The LOGIN example program code has examples of using the MIO functions. The Windows "operating system" is what is called "cooperative multitasking". This means that the executing Windows task must voluntarily "give up" control before another Windows task (or Windows itself) can execute. The difficulty is how to wait for a number of seconds while still relinquishing control periodically before the wait is up. One solution is by making functions that need to wait (such as the MIO functions) into "state" machines. A function is broken down into parts called states, and control is returned to Windows between executing each state. For example, to send the string "ATDT1,205,880,9748" to the modem with one tenth second delay between transmitted characters, the following sequence is used: (1) Send the string to the MIO driver by executing: Code = mioSendTo(Port,100,"!ATDT1,205,880,9748") The '!' characters are converted to carriage returns. The text string is copied into the driver's data area. (2) Call mioDriver (typically based on a Visual BASIC timer) until MIO_IDLE is returned. Each time mioDriver is called, it will send another character to the modem provided the required delay (since the previous character was sent) has passed. If the delay has not passed, the driver simply returns MIO_RUNNING, but without actually sending a character to the modem. Once all characters have been sent, mioDriver will return MIO_IDLE, indicating it is done and is ready to accept another function. mioDriver will return MIO_RUNNING if it is still processing. Anything else received indicates that it is still processing and the returned value is a character from the modem that can be displayed if wanted. (3) Once mioDriver returns MIO_IDLE, call mioResult to get the result of the mioSendTo call. The above is rather straight forward in practice. See the LOGIN application for an example of its use. PCLVBW Users Manual Page 14 4.3.2 MIO Functions 4.3.2.1 mioDriver Syntax: mioDriver(ByVal Port As Integer) As Integer mioDriver executes the next state of any previously started MIO function such as mioSendTo, mioWaitFor, and mioQuiet. It returns: MIO_IDLE : if the driver is ready for the next mioSendTo, mioWaitFor, or mioQuiet. MIO_RUNNING : if the driver is not idle. <otherwise> : if the driver is not idle, and the returned character was received from the modem. 4.3.2.2 mioBreak Forces the MIO driver to the IDLE state, abandoning any work in progress. 4.3.2.3 mioSendTo Syntax: FUNCTION mioSendTo(ByVal Port As Integer, ByVal Pace As Long, ByVal Text As STRING) As Integer The mioSendTo function sends the characters in the string 'Text' to serial output. There is a delay of 'Pace' milliseconds between characters. 4.3.2.4 mioWaitFor Syntax: FUNCTION mioWaitFor(ByVal Port As Integer, ByVal Wait As Long, ByVal Case As Integer, ByVal Text As String) As Integer The mioWaitFor function waits for characters from serial input that match the string 'Text'. A total of 'Wait' milliseconds are allowed before timing out and returning FALSE (0). If the 'Case' flag is TRUE, then the string comparison is NOT case sensitive. For example, to wait up to one minute for "CONNECT", "NO CARRIER", or "BUSY" from the modem after dialing a number (on COM1): Code = mioWaitFor(COM1,60000,1,"CONNECT|NO CARRIER|BUSY") The function mioDriver() must be called until MIO_IDLE is returned. Then mioResult() is called to get the result of the mioWaitFor. A value of 0 indicates that neither "CONNECT", "BUSY", nor "NO CARRIER" was received. A A non-zero value indicates that one of the three sub-strings was received. A ASC("0") is returned if "CONNECT" was seen, ASC("1") is returned if "NO CARRIER" was seen, and ASC("2") is returned if "BUSY" was seen. PCLVBW Users Manual Page 15 4.3.2.5 mioQuiet Syntax: FUNCTION mioQuiet(Port,Wait As Long) The mioQuiet function waits for continuous quiet [no incoming serial data] of 'Wait' milliseconds before returning. Any incoming character while mioQuiet us running is flushed. 4.3.3 MIO Summary mioDriver : Allows the execution of mioSendTo, mioWaitFor, or mioQuiet once they have been started. Returns MIO_IDLE (defined in MIO.BAS) if ready not running, MIO_RUNNING if running, and anything else is a character from the modem that can be displayed if wanted. mioBreak : Forces the MIO driver to IDLE state. mioSendTo : Sends string (including control chars) to the modem. mioWaitFor : Waits for a particular string from the modem, passing all else through. mioQuiet : Waits for continuous quiet of specified duration. mioBreak : Breaks further modem I/O activity. PCLVBW Users Manual Page 16 4.4 Modem Initialization 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 AT command set compatible modems, the following string (followed by a carriage return) may work: AT E1 S7=60 S11=60 V1 X1 Q0 S0=0 Refer to your Modem 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 a tenth of a second (100 milliseconds) 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 Your modem may require additional initialization than presented above. Refer to your modem manual for details. It you have a comm program such as ProComm or Telix that is known to initialize your modem correctly, then you may wish to use the same initialization string. PCLVBW Users Manual Page 17 5.0 Problems If you cannot get your application to run properly, first compile and run the example programs SIMPLE and LOGIN. Both SIMPLE and LOGIN can be used to call up any BBS. If your application does not run but SIMPLE 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. Are you connected to a device that requires flow control? Be sure to turn on flow control with SioFlow if connected to a modem or other serial device that uses flow control. 2. Loosing data at high baud rates? Turn on port FIFOs with SioFIFO if 16550 UARTS are being used. Also disable Windows control of the serial ports you are using. See section 1.3 "Disabling Windows Ports". 3. Is your receive buffer large enough? In general, your receive buffer should be twice as large as the largest incoming block of data. 4. If you are running two COM ports simultaneously, are you using separate transmit and receive buffers? (you should). 5. Did SioReset return a zero value? If not, then you must call SioReset again. 6. Did you send the proper initialization string to your modem? See section 4.4 "Modem Initialization". 7. Did you set DTR and RTS? Most serial devices require that DTR be set before they will respond. 8. 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 COM1 on the motherboard. 9. Are you passing the proper segment of the receive (or transmit) buffer? See SIMPLE or LOGIN for an example. Registered users can call 205-881-4630 from 1:30 PM to 9:30 PM CST Monday through Friday for help. PCLVBW Users Manual Page 18 6.0 Serial Communications 6.1 Communications Basics The heart of serial communications is the UART (Universal Asynchronous Receiver Transmitter). The IBM PC/XT/AT and compatibles use the 8250, 16450, or the 16550 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 8250/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 it 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 PCLVBW for incoming data), when a byte is received by the UART, an interrupt is generated and the "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 Section 6.6 and 6.7 entitled "RS232 Signals" and "National 8250, 16450, and 16550 UARTs" for further information on these topics. PCLVBW Users Manual Page 19 6.2 Standard Port Addresses 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. IRQ Vector COM1 3F8H 4 12 COM2 2F8H 3 11 COM3 3E8H 4 12 COM4 2E8H 3 11 (Refer to your DigiBoard manual for DigiBoard addresses, or your BOCA board manual for BOCA port addresses). PCLVBW assumes the above values. If necessary, the UART base address can be changed by SioUART, and IRQ lines can be re-assigned by SioIRQ. Remember that each port to be used concurrently must have a unique IRQ line. Refer to the PCLVBW Reference Manual for specific details. When installing new communications cards, the following guidelines are recommended: (1) Be sure to read the documentation for the hardware you are installing. Pay special attention to UART base addresses and IRQ lines, particularly if trying to set up a non-standard configuration. (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. Do NOT skip over any port. (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) Select hardware flow control (RTS/CTS) if flow control is required and hardware flow control is not the default. (8) Always test your port as soon as it is installed. Try several programs that use the communications ports. PCLVBW Users Manual Page 20 6.3 Running 3 or 4 Ports Concurrently PCLVBW supports up to 4 serial ports running concurrently (more if you have a DigiBoard or BOCA board). One free interrupt for each port is required. Refer to the next section if you have a DigiBoard or BOCA board. Interrupts IRQ4 and IRQ3 are dedicated to the communications ports in a standard IBM PC/XT/AT configuration. IRQ4 is shared between COM1 and COM3 while IRQ3 is shared between COM2 and COM4. This means that you can run two ports simultaneously provided that they don't share an interrupt. Suppose that you wish to run 3 ports simultaneously. To begin, you must have 3 serial UARTs installed on your computer. Assume, for purposes of this discussion, that COM1 is installed on your motherboard, and that you have purchased a new 2 port serial communications board. You should be able to configure the first serial board port as COM2, which uses IRQ3. Refer to the manual that came with your serial board. In order to run the third serial port concurrently with the first two, an unused interrupt must be found. If your serial card can use only IRQ3 and IRQ4, then there is no way to run a third line since IRQ4 and IRQ3 are used for COM1 and COM2. However, many serial cards can use other IRQs, typically IRQ2 through IRQ5. Since IRQ5 is normally used for a second printer port, it is a good candidate for COM3. To use IRQ5 for the third serial port, first set your serial card to use IRQ5 for COM3 (refer to your serial card manual) and then add the following line to your applications code before calling SioReset: SioIRQ(COM3,IRQ5); Don't forget to disable any device that might use IRQ5, such as a second printer port or a music card. Unfortunately, there is no easy way to determine that you have no conflicts until you actually attempt to use the IRQ. If there are conflicts, your system will probably hang and you will have to reboot. To run a fourth serial port, another free IRQ must be found. On some systems, IRQ7 can be used. To use IRQ7 for the fourth serial port, first set your serial card to use IRQ7 for COM4 and then add: SioIRQ(COM4,IRQ7); To summarize, your serial card must be able to generate the correct IRQ, which is not already being used. Refer to the entry for the SioIRQ function in the PCLVBW Reference Manual. PCLVBW Users Manual Page 21 6.4 Using Multiport Cards The PCLVBW library supports the dumb Digiboard (PC/4 & PC/8) and the dumb BOCA board (BB1004, BB1008, and BB2016). 6.4.1 The DigiBoard In order to use the DigiBoard, you must configure PCLVBW using the SioPorts(), SioUART(), and SioIRQ() functions. Your PCs ports must be partitioned into "standard" PC ports and dumb card ports. Remember that standard PC ports cannot share IRQs like the DigiBoard (or BOCA board) can. If you are using IRQ4 and IRQ3 for standard PC ports COM1 and COM2, then you cannot use either for DigiBoard ports (try IRQ5 or IRQ7). Suppose that COM1 through COM2 are standard PC ports (using IRQ4 and IRQ3) and you have installed a PC/8 DigiBoard that you wish to use for COM3 through COM10 using interrupt line IRQ5. You choose to use the recommended DigiBoard UART addresses starting at 0x100: DEFINT A-Z RC = SioPorts(8,COM1,&H140,DIGIBOARD) 'COM1 = 1st BOCA port Address = &H100 '1st BOCA UART address FOR Port=COM1 TO COM8 'look at each port RC = SioUART(Port,Address) 'set the UART address Address = Address + 8 'compute next address RC = SioIRQ(Port,IRQ5) 'set the BOCA IRQ NEXT I The DigiBoard uses 0x140 for the status address for odd interrupts and 0x141 for even interrupts. Digiboard may be contacted at 6400 Flying Cloud Drive, Eden Prairie, MN 55344. Telephone 612-943-9020 or FAX 612-943-5398. 6.4.2 The BOCA Board As with the DigiBoard, you must configure PCLVBW before using the BOCA board. For example, to configure the BOCA BB2016 to use COM1 to COM16, with base addresses starting at 0x100 and IRQ5: DEFINT A-Z RC = SioPorts(16,COM1,&H107,BOCABOARD) 'COM1 = 1st BOCA port Address = &H100 '1st BOCA UART address FOR Port=COM1 TO COM16 'look at each port RC = SioUART(Port,Address) 'set the UART address Address = Address + 8 'compute next address RC = SioIRQ(Port,IRQ5) 'set the BOCA IRQ NEXT I BOCA may be contacted at BOCA Research, Inc., 6413 Congress Avenue, Suite 130, Boca Raton, FL 33487. Phone 407-241-8088, FAX 407-997-0918. PCLVBW Users Manual Page 22 6.5 Transmitter Interrupts Transmitter interrupts are supported by the library. Separate libraries are provided, one with transmitter interrupts enabled and one without. When transmitter interrupts are NOT enabled, the following logic occurs everytime you call SioPutc(): 1. Wait for transmit buffer to become empty. The transmit buffer may not be empty if the previous transmit is not completed (the UART breaks down the byte & sends 1 bit at a time). 2. When the transmit buffer is empty, the byte from the SioPutc() call is loaded into the transmit buffer and control is returned to the caller. Note that you can not write to the UART any faster than the UART baud rate. When transmitter interrupts are enabled, the byte from SioPutc() is put into a previously prepared (by SioTxQue) transmitter queue. The interrupt service routine fetches bytes from this queue as soon as the previous byte has been sent. While you can now call SioPutc() faster than the baud rate, bytes are still transmitted at the given baud rate. Transmitter interrupts are generally preferrable in Windows , although not necessary. Transmitter interrupts are better not enabled if an application will be doing little or no serial transmission. An application can determine at runtime if the PCLVBW library has transmitter interrupts enabled by calling SioInfo(ASC("I")). A non-zero return value indicates that transmitter interrupts are enabled. A transmit buffer must be set up using SioTxBuf if transmitter interrupts are enabled, otherwise a transmit buffer is not required. See the programs SIMPLE and LOGIN for an example. The default library (PCLVBW.DLL) has transmitter interrupts enabled. PCLVBW1.DLL is the library with transmitter interrupts disabled. PCLVBW Users Manual Page 23 6.6 RS-232 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. DTR should be set high when talking to a modem. 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, and for hardware flow control in most modems that require flow control. Clear to Send Pin 5 (DB25), Pin 8 (DB9) The CTS line is used to "turn the line around" in half duplex modems, and for hardware flow control in most modems that require flow control. 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. PCLVBW Users Manual Page 24 6.7 National 8250, 16450, and 16550 UARTs The Personal Communications Library is based on the standard National 8250, 16450, and 16550 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 (16550 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. For the standard PC ports (not DigiBoard or BOCA ports), the UART registers are based at 3F8h (COM1), 2F8h (COM2), 3E8h (COM3), and 2E8h (COM4). COM1 and COM3 share interrupt request line IRQ4 while COM2 and COM4 share request line IRQ3. This means that COM1 and COM3 can't be used concurrently. Similarly for COM2 and COM4. If you have a DigiBoard (or BOCA board) installed, you will have 4 or more additional ports using 16450 or 16550 UARTS. The default DigiBoard and BOCA board ports are located at 100h, 108h, 110h, etc. Refer to your DigiBoard (or BOCA board) manual. 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, PCLVBW only enables the receiving data interrupt. This means that interrupts can only be caused by incoming data. If you are not familiar with the 8250, several good books are available. Refer to Section 6.0 Serial Communications for recommendations. Although a knowledge of the 8250 is not necessary to use PCLVBW, a general knowledge of the theory of asynchronous serial communications is recommended. PCLVBW Users Manual Page 25 6.8 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 0 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 PCLVBW Users Manual Page 26 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. PCLVBW Users Manual Page 27 8.0 Legal Issues 8.1 Registration If you wish to register the PCLVBW library, please send $75 plus $5 S&H ($10 outside of North America) to: MarshallSoft Computing, Inc. Post Office Box 4543 Huntsville AL 35815 Multiple copies are available: The first copy is $75. Copies 2 through 5 are $60 each. Copies 6 through 10 are $45 each. Copies 11 and up are $30 each. A site license is also available for $495 (includes 5 sets of printed documentation). We pay shipping on multiple copy orders. We accept American Express, VISA, and Mastercard (account number, expiration date, exact name on your card, and complete billing address required), checks in US dollars drawn on a US bank, purchase orders (POs) from recognized US schools and companies listed in Dun & Bradstreet, and COD (street address and phone number required) within the USA (plus a $4.50 COD charge). You can also order PCLVBW from The Public Software Library (PSL) with your MC, Visa, AmEx, or Discover card by calling 800-242-4PSL (from overseas: 713-524-6394) or by FAX at 713-524-6398 or by CompuServe at [71355,470]. THESE NUMBERS ARE FOR ORDERING ONLY. The product number for PCLVBW is 11499. (Specify VisualBASIC/Windows when you call). Please have your shipping address and credit card billing address ready. If you wish to update from an older version of PCLVBW, send $20 plus $5 S&H ($10 outside of North America). Updates must be ordered directly from MarshallSoft Computing. The registered package includes: o Assembler source code for the communications library. o C source code for the modem I/O library. o Printed Users and Reference Manuals. o Telephone, email, FAX, and BBS support for one year. Print the file INVOICE.DOC if an invoice is needed. The registered user will receive the latest version of PCLVBW shipped by two day priority mail (packet airmail overseas). A 3.5" diskette is provided unless a 5.25" diskette is requested. PCLVBW Users Manual Page 28 8.2 License MarshallSoft Computing, Inc. grants the registered user of PCLVBW the right to use one copy of the PCLVBW library (in object form) on a single computer in the development of any software product (other than libraries such as PCLVBW). The user may not use the library on more than one computer at the same time. The source code for the library (PCLVBW.ASM) is copyrighted by MarshallSoft Computing and may not be released in whole or in part. Products developed using PCLVBW can include the object form of the library and may be distributed without any royalty. 8.3 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. PCLVBW Users Manual Page 29 9.0 Summary 9.1 Revision History Version 1.0 - 10 February 1996 This is the first release of the Visual BASIC / Windows version of our library. It uses the common assembler language library used in all of our Windows and DOS communications library products. Version 1.1 - 1 July, 1996 o Added SELFTEST example program. o Minor code & documentation changes. 9.2 Function Summary Refer to the PCLVBW Reference Manual (PCLVBW.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. 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. 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. SioFIFO Sets the interrupt level for the 16550. SioFlow Enables / disables hardware flow control. SioGetc Reads the next character from the serial line. SioGetDiv Reads the baud rate divisor registers. SioKeyPress Detects if keyboard has been pressed. SioKeyRead Reads the keyboard. SioInfo Returns library version number & memory model. SioIRQ Assigns an IRQ line to a port. SioLine Reads the line status register. SioLoopBack Performs a UART loopback test. SioModem Reads the modem status register. SioParms Sets parity, stop bits, and word length. SioPorts Sets # ports, 1st DigiBoard / BOCA port & status reg. SioPutc Transmit a character over a serial line. SioRead Reads any of 7 UART ports. 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. SioRxClear Clears the receive buffer. SioRxQue Returns the number of characters in the receive queue. SioTxBuf Sets up transmit buffer. SioTxClear Clears the transmit buffer. SioTxFlush Flushes the transmit buffer. SioTxQue Returns the number of characters in the transmit queue. SioUART Sets the UART base address. SioUnGetc "Un-gets" (puts back) a specified character. PCLVBW Users Manual Page 30 9.3 Further Reading 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). 10.0 Other MarshallSoft Computing Products MarshallSoft Computing also makes communication libraries for Visual BASIC / DOS (PCL4VB), Power BASIC (PCL4PB), C/DOS (PCL4C), C/Windows (PCL4W), Pascal/DOS (PCL4P), Delphi (PCL4D). 10.1 Windows Standard Communications The Windows Standard Communications for Visual Basic library (WSC4VB) provides most of the functions of PCLVBW but uses the Windows API rather than accessing the serial port hardware directly. The primary advantage is that WSC4VB can co-exist with other applications that may wish to use the same serial ports. WSC4VB will be released July 15, 1996. Download WSC4VB10.ZIP from our BBS or FTP site. PCLVBW Users Manual Page 31