Stars of Shareware: Programmierung

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

/ Stars of Shareware: Programmierung / SOURCE.mdf / programm / windows / basic / lclb42 / lcl4b.doc < prev next >

Wrap

Text File | 1994-08-16 | 82.9 KB | 2,177 lines

Lite (Personal) Communications Library For Visual Basic (LCL4B) USERS MANUAL Version 4.2(1) Aug 16, 1994 This software is provided as-is. There are no warranties, expressed or implied. Copyright (C) 1994 All rights reserved MarshallSoft Computing, Inc. Post Office Box 4543 Huntsville AL 35815 Voice 205-881-4630 FAX 205|881|4630 BBS 205-880-9748 _______ ____|__ | (R) --+ | +------------------- | ____|__ | Association of | | |_| Shareware |__| o | Professionals --+--+ | +--------------------- |___|___| MEMBER LCL4B Users Manual Page 1 C O N T E N T S Chapter Page 1.0 Introduction................................................4 1.1 User Support............................................5 1.2 ASP Ombudsman...........................................5 1.3 A Typical Application...................................6 1.4 Installation............................................7 2.0 Library Organization........................................8 2.1 Initialization & Termination............................8 2.2 Modem Control & Status..................................8 2.3 Serial I/O..............................................9 2.4 Error Detection.........................................9 2.5 General Support.........................................9 3.0 Talking to Your Modem......................................10 3.1 ModemEcho..............................................10 3.2 ModemSendTo............................................10 3.3 ModemWaitFor...........................................10 3.4 ModemQuiet.............................................10 3.5 ModemCmdState..........................................10 3.6 ModemHangup............................................10 4.0 Problems...................................................12 5.0 Serial Communications......................................13 5.1 Standard Port Addresses................................12 6.0 Example Programs...........................................13 6.1 MINIMAL.BAS............................................13 6.2 SIMPLE.BAS.............................................13 6.3 LOGIN.BAS..............................................13 7.0 Legal Issues...............................................14 7.1 Registration...........................................14 7.2 Upgrading to PCL4B.....................................14 7.3 License................................................14 7.4 Warranty...............................................15 8.0 Summary....................................................15 8.1 Revision History.......................................15 8.2 Function Summary.......................................16 8.3 Error Code Summary.....................................16 9.0 Other MarshallSoft Computing products for Basic............17 9.1 The Personal Communications Library for Basic..........17 ( CONTENTS continued next page ) LCL4B Users Manual Page 2 C O N T E N T S (continued) Chapter Page 10.0 Function Reference.........................................17 SioBaud....................................................18 SioBrkKey..................................................18 SioBrkSig..................................................19 SioCrtWrite................................................19 SioCTS.....................................................20 SioDCD.....................................................20 SioDelay...................................................21 SioDone....................................................21 SioDSR.....................................................22 SioDTR.....................................................22 SioError...................................................23 SioGetc....................................................23 SioGetDiv..................................................24 SioInfo....................................................24 SioKeyPress................................................25 SioKeyRead.................................................25 SioLine....................................................26 SioLoopBack................................................26 SioModem...................................................27 SioParms...................................................27 SioPutc....................................................28 SioRead....................................................28 SioReset...................................................29 SioRI......................................................29 SioRTS.....................................................30 SioRxBuf...................................................30 SioRxFlush.................................................31 SioRxQue...................................................31 SioTimer...................................................32 SioUnGetc..................................................32 LCL4B Users Manual Page 3 1.0 Introduction The Lite (Personal) Communications Library for Basic (LCL4B) is an asynchronous communications library for software developers using Microsoft Visual Basic for DOS. o 30 communications & support functions. o Interrupt driven receiver. o Supports 300 baud to 115,200 baud. o Supports COM1 through COM4. o Adjustable queues from 8 bytes to 32 KB. o Control-BREAK error exit. o 18 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. Why should you buy LCL4B? Consider the following: COMPLETE - LCL4B is complete since it provides absolute control of the serial ports (including the high performance INS16550). COMPACT - LCL4B is very compact at less than 6 KB. Your application doesn't carry a lot of excess code. FAST - LCL4B is fast. It will run at 115200 baud on all 80386 and up machines. SUPPORT - If you get stuck, you will talk to the programmer that wrote the code, not a person hired to answer the phone. BBS - A user support BBS is available (2400 to 9600 baud, N81) in order to provide immediate support as necessary. NEWSLETTER - One year subscription to the MSC newsletter discussing communications problems and solutions (published quarterly). PRICE - You get LCL4B for a very reasonable price ! UPGRADES - Once you purchase LCL4B, you can always update to the most recent version for a very reasonable cost. COMPATIBLE - LCL4B is call for call compatible with the MSDOS based version PCL4C. UPGRADABLE - You can upgrade from the lite product LCL4B to the standard product PCL4B for $39. If you need more than 4 ports, wish to be able to configure UART addresses & IRQs, need DigiBoard or BOCA board support, need hardware flow control or support for the 16550 UART, then you should register the standard product: The Personal Communications Library for BASIC (PCL4B) rather than the lite version (LCL4B). You can also register the lite product and then later upgrade to the standard product. Refer to sections 7.1 & 7.2. Our goal is to provide a robust serial communications library that that you and your customers can depend upon. LCL4B Users Manual Page 4 1.1 User Support We want you to be successful in developing your applications using LCL4B! 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. If you are having a problem using LCL4B, call us at 205-881-4630 between 1:30 PM and 9:30 PM CST Monday through Friday. ,or FAX us at the same telephone number at any time (24 hours). You can also call at other times and leave a message, and call back later for a reply. However, we can only answer questions with respect to using the LCL4B library. We cannot help you program your application. You may also call our User Support BBS (2400 to 9600 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 except at 2 PM Sundays for maintenanace. All files are in standard ZIP format. The BBS will contain the latest shareware version of all MarshallSoft products as well as related files such as: BUGS.ZIP ++ Bug report. NEWS.ZIP ++ Latest news regarding our products. The MarshallSoft Computing, Inc. newsletter "Comm Talk" is published quarterly. It discusses various communications problems and solutions using LCL4B as well as related information. Registered users receive a one year complimentary subscription when first registering and for each update purchased. Of course, you can always write to us. You should receive a reply within a week or so. Please don't mail hardware without first talking to us. 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. LCL4B Users Manual Page 5 1.3 A Typical Application The following code is the complete MINIMAL.BAS program. It talks on COM1 at 2400 baud. The code is as follows: +--------------------------------------------------------+ | | | ' | | ' MINIMAL.BAS: Talk on COM1 @ 2400 baud | | ' | | '$INCLUDE: 'LCL4B.INC' | | DECLARE FUNCTION Buf256Seg CDECL() | | 'Reset port | | CODE = SioRxBuf(COM1, Buf256Seg(), Size256) | | CODE = SioReset(COM1, Baud2400) | | DO | | 'Anything incoming ? | | CODE = SioGetc(COM1, 1) | | IF CODE > -1 THEN CODE = SioCrtWrite(CODE) | | 'Anything to send ? | | IF SioKeyPress() <> 0 THEN | | ANYKEY = SioKeyRead() | | 'Exit if user types Escape (ESC=27) | | IF ANYKEY = 27 THEN EXIT DO | | CODE = SioPutc(COM1,ANYKEY) | | END IF | | LOOP | | CODE = SioDone(COM1) | | END | | | +--------------------------------------------------------+ The above code can be compiled by using either the command line compiler by typing MINIMAL_.BAT or BC MINIMAL.BAS; LINK MINIMAL+BUF256,MINIMAL,,VBDRT10.LIB LCL4B_BC.LIB; or by using the project file MINIMAL.MAK from within the integrated Visual Basic environment. Be sure to start by loading the LCL4B quick library by typing VBDOS /LLCL4B.QLB when starting VBDOS. LCL4B Users Manual Page 6 1.4 Installation (1) Before installation of LCL4B, your Visual Basic for DOS compiler should already be installed on your system and tested. (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 LCL4B, we first log onto the work disk and then type: MKDIR LCL4B (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 LCL4B COPY A:*.* (5) Compile MINIMAL.BAS using either the command line compiler by typing MINIMAL_, or compile it within the integrated environment. Be sure to load the quick library LCL4B.QLB when the integrated environment is started: VBDOS /LLCL4B.QLB After compiling MINIMAL.BAS, compile SIMPLE.BAS and LOGIN.BAS. (6) The recommended way to test MINIMAL and 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. If you don't have two computers, you can use MINIMAL or SIMPLE to talk to your modem. Sending an "AT" to the modem should result in an "OK" being sent back. In order to talk to a modem, you may need to send an initialization string to your modem with ModemSendTo (see section 3.2). Refer to your modem manual for the appropriate initilization string. To test LOGIN you will need a modem. See the writeup on the example programs in section 6. LCL4B Users Manual Page 7 2.0 Library Organization The LCL4B library is organized into five categories of functions. Refer to the section 10 of this manual for details on individual functions. 2.1 Initialization & Termination There are six functions in the initialization and termination category. Together, SioParms, 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. 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. 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.2 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. There are two functions, SioRead and SioGetDiv, that can read all UART registers. 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. LCL4B Users Manual Page 8 2.3 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 "ungets" the last serial byte read. SioRxFlush clears the receive queue while SioTxFlush clears the transmit queue. SioLine can be used to test for UART errors. 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. SioRxFlush ++ Flush (clears) the receive buffer. SioRxQue ++ Returns the number of characters in the RX queue. SioLine ++ Reads the line status register. 2.4 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. SioError displays a error message corresponding to an error code returned from a LCL4B function (every LCL4B function returns a code). SioBrkSig ++ Asserts, cancels, or detects the RS232 BREAK signal. SioError ++ Displays error in text. 2.5 General Support There is one function in the general support category. SioInfo returns the version number of the library and whether transmitter interrupts are enabled. SioInfo -- Returns the library version (currently 4.2) LCL4B Users Manual Page 9 3.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. Several functions for talking to you modem are included in the MODEM_IO.BAS file. The functions are declared in the MODEM_IO.INC file, which is included in BASIC program files which use any of the modem_io functions. All MODEM_IO functions require that your modem use the standard AT command set. Refer to the program LOGIN.BAS for an example of using MODEM_IO functions. 3.1 ModemEcho Syntax: FUNCTION ModemEcho(Port,Echo) The ModemEcho functions copies bytes from serial input to the display for 'Echo' timer tics (18.2 tics per second). 3.2 ModemSendTo Syntax: FUNCTION ModemSendTo(Port,Pace,Text$) The ModemSendTo function sends the characters in the string 'Text$' to serial output. There is a delay of 'Pace' timer tics between characters. 3.3 ModemWaitFor Syntax: FUNCTION ModemWaitFor(Port,Tics,CaseFlag,Text$) The ModemWaitFor function waits for characters from serial input that match the string 'Text$'. A total of 'Tics' timer tics are allowed before timing out and returning FALSE. If the 'CaseFlag' is TRUE, then the string comparison is case sensitive. 3.4 ModemQuiet Syntax: FUNCTION ModemQuiet(Port,Tics) The ModemQuiet function waits for continuous quiet of 'Tics' timer tics before returning. Any incoming character is echoed to the display and the wait begins anew. 3.5 ModemCmdState Syntax: FUNCTION ModemCmdState(Port) The ModemCmdState sets the modem to command state, provided that your modem uses a guard time of 1 second and the standard 3 characters "+-+". Refer to you Modem manual for information on setting command state. 3.6 ModemHangup Syntax: FUNCTION ModemHangup(Port) The ModemHangup command hangs up the modem by first calling ModemCmdState and then sending the string "ATH0". LCL4B Users Manual Page 10 4.0 Problems If you cannot get your application to run properly, first compile and run the terminal emulator program SIMPLE provided on your distribution disk. Test SIMPLE by connecting two computers with a null modem cable or by commanding a Hayes AT command set compatible modem. You may need to send an initialization string to your modem. Refer to your modem manual. 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. Have you included the file LCL4B.INC in your application ? 2. Are you using COM1 to COM4 with the standard port addresses and IRQs ? Refer to the next section for a discussion of standard port addresses. 3. Have you selected too high a baud rate? You should be able to run at 9600 to 38400 baud on just about anything, and 115200 baud on 386s and up. 4. Did SioReset return a zero value ? If not, then you must call SioReset again. 5. Did you send the proper initialization string to your modem? Refer to your modem manual for the correct initialization string. 6. Did you set DTR and RTS? Most all modems require that DTR be set, and many also require that RTS be set. 7. Do you have more than one COM1 port? 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. 8. Is your modem using hardware flow control? The LCL4B library does not support flow control. If you need hardware flow control, upgrade to PCL4B. 9. Did you start the integrated environment with the LCL4B quick library? If not, you will get a "Subprogram not defined" error message. For example, start Visual Basic with "VBDOS /LLCL4B.QLB". Also, don't forget to set the COMMAND$ string when running SIMPLE or LOGIN. We recommend the following steps if you believe that you have discovered a bug in the library: (1) Create the smallest, simpliest test program possible that demonstates the problem. (2) Document your exact machine configuration and what error the test program demonstates. (3) Upload the example source to our user support BBS or mail us a disk. If the problem can be solved with an easy work-around, we will publish the work-around. If the problem requires a modification to the library, we will make the change and make the modified library available to our customers without charge. LCL4B Users Manual Page 11 5.0 Serial Communications 5.1 Standard Port Addresses The Lite (Personal) Communications Library (LCL4B) supports COM1 through COM4. The standard IBM PC/XT/AT configuration values supported are as follows: Port Reg Base IRQ Line COM1 3F8H 4 COM2 2F8H 3 COM3 3E8H 4 COM4 2E8H 3 LCL4B assumes the above values. The Lite (Personal) Communications Library can use two standard ports simultaneously: COM1 & COM2, COM1 & COM4, COM2 & COM3 ,or COM3 & COM4. The lite version of the Personal Communications Library will suffice for a wide range of serial communications projects. If you want to use more ports or non-standard UART addresses or non-standard IRQs, you will need to upgrade to the standard product PCL4B. Refer to section 7.2 "Upgrading to PCL4B". 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. (4) Be carefull not to configure two ports for the same address. This is easier to do than you may believe. (5) Choose an external modem over an internal one. It is much easier to debug problems with an external modem than an internal one. (6) Always test your port as soon as it is installed. Try several programs that use the communications ports. LCL4B Users Manual Page 12 6.0 Example Programs There are three example programs MINIMAL, SIMPLE, and LOGIN provided as described below. It is recommended that they be compiled, linked, and run as a test of the software installation. 6.1 MINIMAL.BAS MINIMAL is about the smallest possible terminal program. MINIMAL reads from the serial port and writes to the display and reads from the keyboard and writes to the serial port. The complete source code in listed in section 1.3 of this manual. 6.2 SIMPLE.BAS SIMPLE is a simple terminal emulator, with a few more features than MINIMAL. To talk to COM1 at 9600 baud, type: SIMPLE 1 9600 SIMPLE is a good starting place for an application that talks to a serial device other than a modem (use LOGIN for that). The best way to test MINIMAL and SIMPLE is to run them on two machines connected by a null modem cable. Whatever is typed on one is displayed on the other, and vice versa. If you have just one computer, you can use MINIMAL or SIMPLE to talk to a modem. Type AT, and you should receive "OK" back. 6.3 LOGIN LOGIN is similiar to SIMPLE, except that it first initializes your modem using standard AT command set commands, and then dials up the MarshallSoft Computing support BBS (at 205-880-9748) to the point of logging onto the BBS. The modem initialization string may need to be modified for your particular modem. To run LOGIN on COM2 at 2400 baud, type: LOGIN 2 2400 LCL4B Users Manual Page 13 7.0 Legal Issues 7.1 Registration If you wish to register the LCL4B library, please send $39 plus $3 S&H ($6 outside of North America) to: MarshallSoft Computing, Inc. Post Office Box 4543 Huntsville AL 35815 Multiple copies are available: $30 for 3 to 9, $25 for 10 to 19, and $20 for 20 or more. A site license is also available for $395 (includes 5 sets of printed documentation). We pay shipping. We accept American Express (account number, expiration date, exact name on your card, and complete AmEx 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 $3 COD charge). Print the file INVOICE.DOC if an invoice is needed. You can also order LCL4B 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 LCL4B is 11499. If you wish to update from an older version of LCL4B, send $15 plus $3 S&H ($6 outside of North America). Updates must be ordered directly from MarshallSoft Computing. The registered package includes: o Libs w/o shareware screens. o Laser printed Users and Reference Manuals. o Telephone, 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 LCL4B shipped by two day priority mail (packet airmail overseas). A 5.25" diskette is provided unless a 3.5" diskette is requested. 7.2 Upgrading to PCL4B You may also upgrade from LPL4B to PCL4B for $39 plus $3 S&H ($6 overseas). This will get you hardware (RTS-CTS) flow control, 16550 UART support, DigiBoard PC/4 & PC/8 support, BOCA board BB1004, BB1008, & BB2016 support, XMODEM & YMODEM code, and source code to the library. 7.3 License MarshallSoft Computing, Inc. grants the registered user of LCL4B the right to use one copy of the LCL4B library (in object form) on a single computer in the development of any software product (other than libraries such as LCL4B). The user may not use the library on more than one computer at the same time. The source code for the library (LCL4B.ASM) is copyrighted by MarshallSoft Computing and may not be released in whole or in part. Products developed using LCL4B may be distributed without any royalty. LCL4B Users Manual Page 14 7.4 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. 8.0 Summary 8.1 Revision History Version 4.2 -- 1 August, 1994. The initial release of LCL4B uses version 4.2.0 of the assembler language communications library, which is part of PCL4C (C/C++) and PCL4P (Pascal). LCL4B Users Manual Page 15 8.2 Function Summary +-------------+----------+----------+----------+----------+ | Function | Arg1 | Arg2 | Arg3 | Arg4 | +-------------+----------+----------+----------+----------+ | SioBaud | Port | BaudCode | | | | SioBrkKey | | | | | | SioBrkSig | Port | Cmd | | | | SioCTS | Port | | | | | SioDCD | Port | | | | | SioDelay | Tics | | | | | SioDone | Port | | | | | SioDSR | Port | | | | | SioDTR | Port | Cmd | | | | SioError | Code | | | | | SioGetc | Port | | | | | SioGetDiv | Port | | | | | SioInfo | Cmd | | | | | SioKeyPress | | | | | | SioKeyRead | | | | | | SioLoopBack | Port | | | | | SioModem | Port | Mask | | | | SioParms | Port | Parity | StopBits |WordLength| | SioPorts | NbrPorts | FirstDBP |StatusReg | | | SioPutc | Port | Ch | | | | SioRead | Port | Register | | | | SioReset | Port | BaudCode | | | | SioRI | Port | | | | | SioRTS | Port | Cmd | | | | SioRxBuf | Port | BufSeg | SizeCode | | | SioRxFlush | Port | | | | | SioRxQue | Port | | | | | SioTimer | Port | | | | | SioUnGetc | Port | Ch | | | +-------------+----------+----------+----------+----------+ 8.3 Error Code Summary +------+--------------------------------------------------------+ | Code | Description | +------+--------------------------------------------------------+ | 0 | No error. | | -1 | Timeout waiting for I/O. | | |2 | Port not enabled. Call SioReset first. | | |3 | No buffer available. Call SioRxBuf first. | | |4 | No such port. Expect 0 to MaxPort. (COM1 = 0) | | |5 | Expected 'S', 'C', or 'R' as 2nd argument. | | |6 | Expected 'A', 'C', or 'D' as 2nd argument. | | |7 | Bad parity code specified. Expected 0 to 7. | | |8 | Bad stop bits code specified. Expected 0 or 1. | | -9 | Bad wordlength code specified. Expect 0 to MaxPort. | | -10 | Bad buffer size code specified. Expected 0 to 11. | | |11 | Bad baud rate code. Expected 0 to 9. | | |13 | UART undefined. | | |14 | Missing or bad UART. (no UART hardware ?) | | |15 | Port already enabled. | | |16 | Interrupt already in use. | +-+----+--------------------------------------------------------+ LCL4B Users Manual Page 16 9.0 Other MarshallSoft Computing Products 9.1 The Personal Communications Library for Basic The Personal Communications Library for the Basic (PCL4B) is a DOS based asynchronous communications library designed for experienced software developers programming in C. Microsoft Visual Basic for DOS is supported. An IBM PC/XT/AT or compatible is required. The PCL features: o 38 communications and support functions. o Supports hardware (RTS/CTS) flow control. o Supports the high performance 16550 UART. o Use any UART address with any of IRQ2 to IRQ7. o Supports the Digiboard PC/4 and PC/8. o Supports the BOCA BB1004, BB1008, and BB2016 boards. o Interrupt driven transmitter (optionally) & receiver. o Supports 300 baud to 115,200 baud. o Supports COM1 through COM16. 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 (16 with multiport boards) to run concurrently. o Complete modem control & status. o Written in assembly language for small size & high speed. o Terminal program featuring XMODEM, YMODEM, & YMODEM-G. o SCRIPT compiler & interpreter. The Personal Communications Library for Basic (PCL4B) is available for $65 plus $3 S&H ($6 S&H overseas). LCL4B can be upgraded to PCL4B for $39 plus $3 S&H ($6 overseas). 10.0 Function Reference The remainder of this manual is a detailed function reference. Note that each library function returns a value. Negative values are always errors. Errors can be printed by calling SioError with the error code as its argument. Many of these function are used in the three example programs detailed in section 6. LCL4B Users Manual Page 17 +-------------+------------------------------------------------------------+ | SioBaud | Sets the baud rate of the selected port. | +-------------+------------------------------------------------------------+ Syntax FUNCTION SioBaud(Port,BaudCode) REM Port: Port selected (COM1 - COM4) REM BaudCode: Baud code Remarks The SioBaud function sets the baud rate without resetting the port. It is used to change the baud rate after calling SioReset. Code Rate Name Code Rate Name 0 300 Baud300 5 9600 Baud9600 1 600 Baud600 6 19200 Baud19200 2 1200 Baud1200 7 38400 Baud38400 3 2400 Baud2400 8 57600 Baud57600 4 4800 Baud4800 9 115200 Baud115200 Returns -4 : No such port. Expect 0 to MaxPort. -11 : Bad baud rate code. See above code values. See Also SioReset +-------------+------------+-------------------+---------------------------+ | SioBrkKey | Return non|zero if the Control|BREAK key was pressed. | +-------------+------------+-------------------+---------------------------+ Syntax FUNCTION SioBrkKey() Remarks The SioBrkKey function returns a TRUE value (non- zero) if the Control-BREAK key was pressed, else it returns a zero. Use SioBrkKey as a safety exit from a polling loop. Don't mix this function up with SioBrkSig. Returns -1 : Control-BREAK was pressed. 0 : Control-BREAK was NOT pressed. See Also SioBrkSig LCL4B Users Manual Page 18 +-------------+------------------------------------------------------------+ | SioBrkSig | Asserts, cancels, or detects BREAK signal. | +-------------+------------------------------------------------------------+ Syntax FUNCTION SioBrkSig(Port,Cmd) REM Port: Port selected (COM1 thru COM4) REM Cmd: ASSERT, CANCEL, or DETECT Remarks The SioBrkSig function controls the BREAK bit in the line status register. The legal commands are: ASSERT_BREAK ('A') to assert BREAK CANCEL_BREAK ('C') to cancel BREAK DETECT_BREAK ('D') to detect BREAK ASSERT_BREAK, CANCEL_BREAK, and DETECT_BREAK are defined in LCL4B.INC. See TERM.BAS for an example of the use of SioBrkSig. Returns -2 : Port not enabled. Call SioReset first. -4 : No such port. Expect 0 to MaxPort. -6 : Illegal command. Expected 'A', 'C', or 'D'. >0 : BREAK signal detected (DETECT command only) See Also SioBrkKey +-------------+------------------------------------------------------------+ | SioCrtWrite | Write character to the screen. | +-------------+------------------------------------------------------------+ Syntax FUNCTION SioCrtWrite(Ch) REM Ch: character to write Remarks The SioCrtWrite function uses the BIOS to write a single character to the screen at the current cursor location. SioCrtWrite calls the BIOS directly without any intermediate buffering or processing. It is usually faster than a call to the C library. Returns zero See Also SioKeyPress and SioKeyRead LCL4B Users Manual Page 19 +-------------+------------------------------------------------------------+ | SioCTS | Reads the Clear to Send (CTS) modem status bit. | +-------------+------------------------------------------------------------+ Syntax FUNCTION SioCTS(Port) REM Port: Port selected (COM1 thru COM4) Remarks The SioCTS function is used to read the Clear to Send (CTS) modem status bit. The CTS line is used by some error correcting modems to implement hardware flow control. CTS is dropped by the modem to signal the computer not to send data and is raised to signal the computer to continue. Refer to the User's Manual for a discussion of flow control. Returns -2 : Port not enabled. Call SioReset first. -4 : No such port. Expect 0 to MaxPort. 0 : CTS is clear. >0 : CTS is set. See Also SioFlow, SioDSR, SioRI, SioDCD, and SioModem. +-------------+------------------------------------------------------------+ | SioDCD | Reads the Data Carrier Detect (DCD) modem staus bit. | +-------------+------------------------------------------------------------+ Syntax FUNCTION SioDCD(Port) REM Port: Port selected (COM1 thru COM4) Remarks The SioDCD function is used to read the Data Carrier Detect (DCD) modem status bit. Also see SioModem. Returns -2 : Port not enabled. Call SioReset first. -4 : No such port. Expect 0 to MaxPort. 0 : DCD is clear. >0 : DCD is set. See Also SioDSR, SioCTS, SioRI, and SioModem. LCL4B Users Manual Page 20 +-------------+------------------------------------------------------------+ | SioDelay | Delays one or more timer tics. | +-------------+------------------------------------------------------------+ Syntax FUNCTION SioDelay(Tics) REM Tics: # Timer tics (18.2 tics per second) Remarks The SioDelay function is used to delay one or more timer tics, where each timer tic is approximately 55 milliseconds (18.2 tics to the second). Returns zero See Also SioTimer +-------------+------------------------------------------------------------+ | SioDone | Terminates further serial processing. | +-------------+------------------------------------------------------------+ Syntax FUNCTION SioDone(Port) REM Port: Port selected (COM1 thru COM4) Remarks The SioDone function terminates further serial processing. SioDone MUST be called before exiting your application so that interrupts can be restored to their original state. Failure to do this can crash the operating system. If you forget to call SioDone before exiting, be sure to re-boot your computer. You can call SioDone even if SioReset has not been called, so it is good practice to always call SioDone before exiting your application. Also note that SioDone dereferences the transmit and receive buffers set up by SioRxQue and SioTxQue. Returns -2 : Port not enabled. Call SioReset first. -4 : No such port. Expect 0 to MaxPort. See Also SioReset. LCL4B Users Manual Page 21 +-------------+------------------------------------------------------------+ | SioDSR | Reads the Data Set Ready (DSR) modem status bit. | +-------------+------------------------------------------------------------+ Syntax FUNCTION SioDSR(Port) REM Port: Port selected (COM1 thru COM4) Remarks The SioDSR function is used to read the Data Set Ready (DSR) modem status bit. Returns -2 : Port not enabled. Call SioReset first. -4 : No such port. Expect 0 to MaxPort. 0 : DSR is clear. >0 : DSR is set See Also SioCTS, SioRI, SioDCD, and SioModem +-------------+------------------------------------------------------------+ | SioDTR | Set, clear, or read Data Terminal Ready (DTR) status bit. | +-------------+------------------------------------------------------------+ Syntax FUNCTION SioDTR(Port,Cmd) REM Port: Port selected (COM1 thru COM4) REM Cmd: DTR command (SET, CLEAR, or READ) Remarks The SioDTR function controls the Data Terminal Ready (DTR) bit in the modem control register. Commands (defined in LCL4B.INC) are: SET_LINE ('S') to set DTR (ON) CLEAR_LINE ('C') to clear DTR (OFF) READ_LINE ('R') to read DTR Most all modem require that DTR be set, and many require that RTS be set. Returns -2 : Port not enabled. Call SioReset first. -4 : No such port. Expect 0 to MaxPort. -5 : Not one of 'S', 'C', or 'R'. 0 : DTR is OFF (READ_LINE Command). >0 : DTR is ON (READ_LINE Command). See Also SioRTS. LCL4B Users Manual Page 22 +-------------+------------------------------------------------------------+ | SioError | Displays error in text. | +-------------+------------------------------------------------------------+ Syntax FUNCTION SioError(Code) REM Code: Error code returned from a LCL4B function. Remarks The SioError function displays the error in text corresponding to the error code. During development of a communications application, it is a good idea to always test return codes, and print out their descriptions with SioError. Returns zero +------------+-------------------------------------------------------------+ | SioGetc | Reads the next character from the serial line. | +------------+-------------------------------------------------------------+ Syntax FUNCTION SioGetc(Port,Tics) REM Port: COM1 to COM4 REM Tics: Time in tics before timing out. Remarks The SioGetc function reads a byte from the selected serial port. The function will return immediately if no serial byte is ready. Returns -2 : Port not enabled. Call SioReset first. -4 : No such port. Expect 0 to MaxPort. -1 : If timed out. >0 : Character read. See Also SioUnGetc and SioPutc. LCL4B Users Manual Page 23 +---------------+----------------------------------------------------------+ | SioGetDiv | Reads the baud rate divisor. | +---------------+----------------------------------------------------------+ Syntax FUNCTION SioGetDiv(int Port) REM Port: Port selected (COM1 thru COM16) Remarks The SioGetDiv function reads the baud rate divisor. The baud rate can then be determined by the divisor: Baud Divisor Baud Divisor Baud Divisor 300 0180 4800 0018 38400 0003 1200 0060 9600 000C 57600 0002 2400 0030 19200 0006 115200 0001 The remaining registers can be read by the SioRead function. Returns -2 : Port not enabled. Call SioReset first. -4 : No such port. Expect 0 to MaxPort. >0 : Baud rate divisor. See Also SioParms and SioRead. +-------------+------------------------------------------------------------+ | SioInfo | Returns LCL4B library information. | +-------------+------------------------------------------------------------+ Syntax FUNCTION SioInfo(Cmd) REM Cmd: Command (VERSION) Remarks The SioInfo function returns an integer code corresponding to either the library version number. Other information may be made available in future releases. Returns Version ('V') hex byte XY where version is denoted as X.Y LCL4B Users Manual Page 24 +-------------+------------------------------------------------------------+ | SioKeyPress | Detects if keyboard has been pressed. | +-------------+------------------------------------------------------------+ Syntax FUNCTION SioKeyPress() Remarks The SioKeyPress function uses the BIOS to test the keyboard for a key press (including control characters). SioKeyPress calls the BIOS directly without any intermediate buffering or processing. It is usually faster than using the C library. Returns zero See Also SioCrtWrite and SioKeyRead. +-------------+------------------------------------------------------------+ | SioKeyRead | Reads the keyboard. | +-------------+------------------------------------------------------------+ Syntax int SioKeyRead() Remarks The SioKeyRead function uses the BIOS to read the keyboard. It will wait until a character is typed. SioKeyRead calls the BIOS directly without any intermediate buffering or processing. It is usually faster than using the C library. Returns Character typed (including control codes). See Also SioCrtWrite and SioKeyRead. LCL4B Users Manual Page 25 +-------------+------------------------------------------------------------+ | SioLine | Reads the line status register. | +-------------+------------------------------------------------------------+ Syntax FUNCTION SioLine(Port) REM Port: Port selected (COM1 thru COM4) Remarks The SioLine function reads the line status register. The individual bit masks are as follows: 0x40 = Transmitter empty. 0x20 = Transmitter buffer empty. 0x10 = Break detected. 0x08 = Framming error. 0x04 = Parity error. 0x02 = Overrun error. 0x01 = Data ready. The above are documented in the file LCL4B.INC. Returns -2 : Port not enabled. Call SioReset first. -4 : No such port. Expect 0 to MaxPort. >0 : Line status (rightmost byte of word). See Also SioModem. +-------------+------------------------------------------------------------+ | SioLoopback | Does a UART loopback test. | +-------------+------------------------------------------------------------+ Syntax FUNCTION SioLoopBack(Port) REM Port: Port selected (COM1 thru COM4) Remarks SioLoopBack makes use of the built in loopback test capability of the INS8250 family UART. Normally SioLoopBack will never need to be called except if you suspect that your UART is bad. Many UARTs must be reset after running a loopback test. Returns 0 : Loopback test is successfull. -2 : Port not enabled. Call SioReset first. -4 : No such port. Expect 0 to MaxPort. -12 : Loopback test fails. LCL4B Users Manual Page 26 +-------------+------------------------------------------------------------+ | SioModem | Reads the modem status register. | +-------------+------------------------------------------------------------+ Syntax FUNCTION SioModem(Port, Mask) REM Port: Port selected (COM1 thru COM4) REM Mask: Modem function mask Remarks The SioModem function reads the modem register. The bit definitions for the function mask are as follows: Bit Name Function Bit Name Function 7 DCD Data Carrier Detect 3 DeltaDCD DCD has changed 6 RI Ring Indicator 2 DeltaRI RI has changed 5 DSR Data Set Ready 1 DeltaDSR DSR has changed 4 CTS Clear To Send 0 DeltaCTS CTS has changed Bits 4 through 7 represent the absolute state of their respective RS-232 inputs. Bits 0 through 3 represent a change in the state of their respective RS-232 inputs since last read. Returns -2 : Port not enabled. Call SioReset first. -4 : No such port. Expect 0 to MaxPort. >0 : Modem status (rightmost byte of word). See Also SioCTS, SioDCD, SioDSR and SioRI. +-------------+------------------------------------------------------------+ | SioParms | Sets parity, stop bits, and word length. | +-------------+------------------------------------------------------------+ Syntax FUNCTION SioParms(Port,ParityCode,StopBitsCode, WordLengthCode) REM Port: Port selected (COM1 - COM4) REM ParityCode: parity code [0,1,2] REM StopBitsCode: stop bits code [0,1] REM WordLengthCode: word length code [0,1,2,3] Remarks The SioParms function sets the parity, stop bits, and word length. If the default parity (none), stop bits (1), or word length (8) is not acceptable, then they can be changed by calling SioParms. SioParms can be called either before or after calling SioReset. See file LCL4B.INC. (8 = default) Value Description LCL4B.INC Name ParityCode: *0 no parity NoParity 1 odd parity OddParity 3 even parity EvenParity StopBitsCode: *0 1 stop bit OneStopBit 1 2 stop bits TwoStopBits WordLengthCode: 0 5 data bits WordLength5 1 6 data bits WordLength6 2 7 data bits WordLength7 *3 8 data bits WordLength8 Returns -4 : No such port. Expect 0 to MaxPort. -7 : Bad parity code selected. Expecting 0 to 2. |8 : Bad stop bits code. Expecting 0 or 1. -9 : Bad word length code. Expecting 0 to 3. See Also SioReset. LCL4B Users Manual Page 27 +-------------+------------------------------------------------------------+ | SioPutc | Transmit a character over a serial line. | +-------------+------------------------------------------------------------+ Syntax FUNCTION SioPutc(Port,Ch) REM Port: Port selected (COM1 thru COM4) REM Ch: Character to send Remarks The SioPutc function transmits one character over the selected serial line. Returns -2 : Port not enabled. Call SioReset first. -4 : No such port. Expect 0 to MaxPort. See Also SioGetc and SioFlow. +-------------+------------------------------------------------------------+ | SioRead | Reads any UART register. | +-------------+------------------------------------------------------------+ Syntax FUNCTION SioRead(Port,Reg) REM Port: Port selected (COM1 thru COM4) REM Reg: UART register (0 to 7) Remarks The SioReset function directly reads the contents of any of the 7 UART registers. This function is useful when debugging application programs and as a method for verifying UART contents. Refer to the LCL4B Users Manual for a discussion of the 7 UART registers. The line status register (register 5) can also be read with SioLine while the modem status register (register 6) can also be read with SioModem. Refer to the LCL4B User's Manual for a discussion of the UART registers. Returns -3 : No buffer available. Call SioRxBuf first. -4 : No such port. Expect 0 to MaxPort. See Also SioLine, SioModem, and SioGetDiv. LCL4B Users Manual Page 28 +-------------+------------------------------------------------------------+ | SioReset | Initialize a serial port for processing. | +-------------+------------------------------------------------------------+ Syntax FUNCTION SioReset(Port,BaudCode) REM Port: Port selected (COM1 thru COM4) REM BaudCode: baud code or -1 Remarks The SioReset function initializes the selected serial port. SioReset should be called after calling SioParm and SioRxBuf but before making any other calls to LCL4B. SioReset uses the parity, stop bits, and word length value previously set if SioParm was called, otherwise the default values (see SioParm) are used. Recall that COM1 and COM3 share the same interrupt vector and therefore cannot operate simultaneously. Similiarly, COM2 and COM4 cannot operate simultaneously. Any other combination of two ports can be used. By specifing NORESET (-1) for the baud rate code, the port will NOT be reset. This is used to "take over" a port from a host communications program that allows a "DOS gateway". External protocols can be implemented this way. See SioBaud for a list of the baud rate codes, or see "LCL4B.INC". Returns -3 : No buffer available. Call SioRxBuf first. -4 : No such port. Expect 0 to MaxPort. -11 : Bad baud rate code selected. Expecting 0 to 9. |14 : Bad or missing UART. You may not have hardware present. |15 : Port already enabled. SioReset has already been called. -16 : Interrupt already in use. See Also SioBaud, SioParms, SioRxBuf, SioDone. +-------------+------------------------------------------------------------+ | SioRI | Reads the Ring Indicator (RI) modem status bit. | +-------------+------------------------------------------------------------+ Syntax FUNCTION SioRI(Port) REM Port: Port selected (COM1 thru COM4) Remarks The SioRI function is used to read the Ring Indicator (RI) modem status bit. Also see SioModem. Returns -2 : Port not enabled. Call SioReset first. -4 : No such port. Expect 0 to MaxPort. 0 : RI is clear. >0 : RI is set (RING has occurred). See Also SioDSR, SioCTS, SioDCD, and SioModem. LCL4B Users Manual Page 29 +-------------+------------------------------------------------------------+ | SioRTS | Sets, clears, or reads the Request to Send (RTS) line. | +-------------+------------------------------------------------------------+ Syntax FUNCTION SioRTS(Port,Cmd) REM Port: COM1 to COM4 REM Cmd: RTS command (SET, CLEAR, or READ) Remarks The SioRTS function controls the Request to Send (RTS bit in the modem control register. The RTS line is used by some error correcting modems to implement hardware flow control. RTS is dropped by the computer to signal the modem not to send data, and is raised to signal the modem to continue. Refer to the User's Manual for a discussion of flow control. Commands (defined in LCL4B.INC) are: SET_LINE ('S') ++ set RTS (ON) CLEAR_LINE ('C') ++ clear RTS (OFF) READ_LINE ('R') ++ read RTS Returns -2 : Port not enabled. Call SioReset first. -4 : No such port. Expect 0 to MaxPort. -5 : Command is not one of 'S', 'C', or 'R'. 0 : RTS is OFF (READ_LINE Command). >0 : RTS is ON (READ_LINE Command). See Also SioFlow and SioDTR. +-------------+------------------------------------------------------------+ | SioRxBuf | Sets up receive buffer. | +-------------+------------------------------------------------------------+ Syntax FUNCTION SioRxBuf(Port,Buffer,SizeCode) REM Port: Port selected (COM1 thru COM4) REM BufSeg: Receive buffer segment word REM SizeCode: Buffer size code Remarks The SioRxBuf function passes the segment address and size of the receive buffer to LCL4B. Recall that LCL4B requires a receive buffer for each port in simultaneous operation since the receive function is interrupt driven. It must be called before any incoming characters can be received. SioRxBuf must be called before SioReset. Buffer size codes are listed in "LCL4BC.INC". Size Code Buffer Size LCL4B.INC Name 4 128 bytes Size128 5 256 bytes Size256 6 512 bytes Size512 7 1024 bytes Size1024 or Size1K 8 2048 bytes Size2048 or Size2K 9 4096 bytes Size4096 or Size4K 10 8192 bytes Size8192 or Size8K 11 16384 bytes Size16384 or Size16K 12 32768 bytes Size32768 or Size32K Returns -4 : No such port. Expect 0 to MaxPort. -10 : Bad buffer size code. Expecting 0 to 11. See Also SioReset. LCL4B Users Manual Page 30 +------------+-------------------------------------------------------------+ | SioRxFlush | Flushes (clears) the receive buffer. | +------------+-------------------------------------------------------------+ Syntax FUNCTION SioRxFlush(Port) REM Port: Port selected (COM1 thru COM4) Remarks The SioRxFlush function will delete any characters in the receive buffer for the specified port. After execution, the receive buffer will be empty. Call SioRxBuf after resetting a port in order to delete any spurious characters. Returns -2 : Port not enabled. Call SioReset first. -4 : No such port. Expect 0 to MaxPort. See Also SioRxQue. +-------------+------------------------------------------------------------+ | SioRxQue | Returns the number of bytes in the receive queue. | +-------------+------------------------------------------------------------+ Syntax FUNCTION SioRxQue(Port) REM Port: Port selected (COM1 thru COM4) Remarks The SioRxQue function will return the number of characters in the receive queue at the time of the call. It can be used to implement XON/XOFF flow control. Returns -2 : Port not enabled. Call SioReset first. -4 : No such port. Expect 0 to MaxPort. See Also SioRxFlush. LCL4B Users Manual Page 31 +------------+-------------------------------------------------------------+ | SioTimer | Returns the number of system clock tics since midnight. | +------------+-------------------------------------------------------------+ Syntax FUNCTION SioTimer&() Remarks The SioTimer function will return the number of system clock tics since midnight, at 18.2065 tics per second. This function is usefull for timing various functions. Also see SioDelay. Returns System clock tics since midnight. See Also SioDelay. +------------+-----+-------------------------------------------------------+ | SioUnGetc | "Un|gets" the last character read with SioGetc(). | +------------+-----+-------------------------------------------------------+ Syntax FUNCTION SioUnGetc(Port,Ch) REM Port: Port selected (COM1 thru COM4) REM Ch: Character to unget Remarks The SioUnGetc function returns ("pushes") the character back into the serial input buffer. The character pushed will be the next character returned by SioGetc. Only one character can be pushed back. This function works just like the "ungetc" function in the C language. Returns -2 : Port not enabled. Call SioReset first. -4 : No such port. Expect 0 to MaxPort. See Also SioReset. LCL4B Users Manual Page 32