CD Shareware Magazine 1996 December

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

/ CD Shareware Magazine 1996 December / CD_shareware_12-96.iso / WIN / Programa / WSC4VB10.ZIP / WSC4VB_U.DOC < prev next >

Wrap

Text File | 1996-08-26 | 44.8 KB | 1,361 lines

Windows Standard Communications Library for Visual Basic (WSC4VB) USERS MANUAL Version 1.0 August 25, 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 WSC4VB 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 Installation............................................6 2.0 [reserved chapter] 3.0 Library Overview............................................7 3.1 Dynamic Link Libraries..................................7 3.2 Using the Library.......................................7 3.3 Compiling WSC...........................................7 4.0 Talking to Your Modem.......................................8 4.1 Modem Standards.........................................8 4.2 Flow Control............................................9 4.3 Modem I/O Functions....................................10 4.4 Modem Initialization...................................12 5.0 Problems...................................................13 6.0 Serial Communications......................................14 6.1 Communications Basics..................................14 6.2 RS232 Signals..........................................14 7.0 Example Programs...........................................16 7.1 SIMPLE.................................................16 7.2 LOGIN..................................................16 7.3 SELFTEST...............................................16 7.4 RS232..................................................16 8.0 Legal Issues...............................................17 8.1 Registration...........................................17 8.2 License................................................18 8.3 Warranty...............................................18 9.0 Summary....................................................19 9.1 Revision History.......................................19 9.2 Function Summary.......................................19 9.3 Further Reading........................................20 10.0 Other MarshallSoft Computing products for Visual Basic.....20 10.1 The Personal Communications Library for VB / WIN......20 10.2 The Personal Communications Library for VB / DOS......20 10.3 Libraries for Other Languages.........................20 WSC4VB Users Manual Page 2 1.0 Introduction The Windows Standard Communications Library for Visual Basic (WSC4VB) is an asynchronous communications (16-bit) dynamic link library (DLL) which uses the standard Windows serial communications API. Since it uses the Windows API, programs using the WSC library are fully compatible with other Window applications which also use the Windows serial communications API. Using WSC is very straight-forward. For example, to write "HELLO" to the serial port COM1: SioReset(COM1,128,128) 'open COM1 SioPuts(COM1,"HELLO",5) 'write "HELLO" to COM1 SioDone(COM1) 'close COM1 Three Visual Basic example programs with full source code are included. Refer to chapter 7 for more details on each of the example programs. SIMPLE : A simple terminal emulator. LOGIN : Same as SIMPLE but can also dial a modem and log onto a BBS. SELFTEST : Performs COM port functionality testing. WSC4VB contains over 25 functions. All functions return a negative number if an error condition is detected. For more details, consult the WSC4VB Reference Manual WSC4VB uses the same function names and arguments as PCL4W (our Windows Communications Library that does NOT use the Windows API) except for a few functions. Our goal is to provide a robust serial communications library that that you and your customers can depend upon. Contact us if you have any questions. WSC4VB Users Manual Page 3 1.1 User Support We want you to be successful in developing your applications using WSC4VB! We depend upon 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 WSC4VB, call us at 205-881-4630 between 1:30PM and 9:30PM 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 WSC4VB library. We cannot help you program your application. 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 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. If you are on the Internet, you can email us at info@marshallsoft.com. You can also get the latest versions of our products from our anonymous ftp site: FTP: ftp.marshallsoft.com PATH: marshallsoft The MarshallSoft Computing, Inc. newsletter "Comm Talk" is published quarterly. It discusses various communications problems and solutions using WSC4VB as well as related information. The latest copy of our newsletter can be found on our User Support BBS (in file area "Newsletters"), our anonymous ftp site (directory /marshallsoft) as well as our web site. 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. WSC4VB Users Manual Page 4 1.3 Determining UART Address & IRQ Settings You will not normally need to know the port addresses or IRQ assignments made by Windows. But this information is maintained by Windows, and is available if you need it. 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)" ). 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 WSC4VB Users Manual Page 5 1.4 Installation This shareware product may be evaluated for 500 executions (calls to SioReset). WSC4C must be installed using the TRIALS manager before it can be executed. To install WSC4C: (1) Before installation of WSC4VB, your (16-bit) Visual Basic compiler should already be installed on your system and tested. Examine the file "FILES.LST" for a list of the distribution files. (2) Make a backup copy of your distribution disk. Put your original distribution disk in a safe place. (3) Exit Windows into DOS, or start a DOS window: (4) Create a work directory. For example, to create C:\WSC4VB, type: C: CD \ MKDIR WSC4VB CD WSC4VB (5) Unzip all distribution files to your working directory. PKUNZIP WSC4VB10.ZIP If this is a "Commercial" registered version, skip to step 10. The shareware archive must include: WSC10.TMD -- The WSC installation data file. Required for both shareware installation and "personal" registration. TRIALS.EXE -- The TRIALS executable used to install WSC4VB. (6) TRIALS will open WSC10.TMD in order to install WSC. Type: TRIALS -i WSC10 (7) Once installed, WSC4VB cannot be reinstalled unless you reformat your hard drive. TRIALS does not modify disk formatting or employ other marginal procedures. TRIALS creates a configuration file which it uses to keep track of the number of executions. Do not modify or move this file or you will not be able to execute WSC4VB programs. WSC4VB must be installed on each computer on which WSC4VB programs will run. (9) The installation can be tested by typing: TRIALS -L (10) Copy WSC.DLL, WTMLIB.DLL [Shareware version only], and MODEM_IO.DLL from your work directory to the Visual Basic compiler directory. Start Visual Basic and compile SIMPLE.MAK. (11) The recommended way to test SIMPLE is to run it on two computers connected by a null modem cable. Whatever is typed on one computer should be displayed on the other. If you don't have two computers, you can use SIMPLE to talk to your modem. Sending an "AT" to the modem should result in an "OK" being sent back. See Section 7.1 "SIMPLE" for more information. (12) Compile and link LOGIN. Use LOGIN to call a local BBS. See Section 7.2 "LOGIN" for more information. (13) Compile and link SELFTEST. Use SELFTEST to test one of your serial ports. See Section 7.3 "SELFTEST" for more information. WSC4VB Users Manual Page 6 3.0 Library Overview 3.1 Dynamic Link Libraries WSC4VB is provided as a dynamic link library (DLL). A DLL is characterized by the fact that it need not be loaded until required by an application program and that only one copy of the DLL is necessary regardless of the number of application programs that use it. Contrast this to the traditional static library which is bound to each and every application that uses it at link time. Since WSC4VB is a DLL, only one copy of the WSC4VB code & data is loaded into memory regardless of the number of applications programs that use it. For example, more than one instance of the test program SIMPLE can be started. All copies of SIMPLE can run concurrently as long as each uses a different COM port. 3.2 Using the Library The WSC4VB has been tested on a Gateway 2000 25 MHZ 80386-DX, a Gateway 2000 66MHZ 80486-DX2 (all running Windows 3.1), and a Mid-West Micro 150MHZ Pentium running Windows 95. WSC4VB has also been tested with both Microsoft Visual Basic 3.0 and Microsoft Visual Basic 4.0 (16-bit version). Please examine the WSC4VB.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 WSC4VB functions. We recommend that you experiment with the four example programs. 3.3 Compiling WSC Registered users (commercial version only) can compile WSC in order to create WSC.DLL. The Microsoft C or Borland C windows compiler is required. Makefiles are provided for each compiler. For Microsoft C, type: NMAKE WSC4C._M_ For Borland C, type: MAKER -fWSC4C._B_ WSC4VB Users Manual Page 7 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. 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 : to 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. WSC4VB Users Manual Page 8 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. WSC4VB supports both hardware and software flow control. Refer to the SioFlow function in the WSC4VB Reference Manual. WSC4VB Users Manual Page 9 4.3 MODEM I/O (MIO) 4.3.1 MIO Introduction The file MODEM_IO.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 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. 4.3.2 MIO Functions 4.3.2.1 mioDriver Syntax: int mioDriver(int Port) 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. WSC4VB Users Manual Page 10 4.3.2.2 mioBreak Forces the MIO driver to the IDLE state, abandoning any work in progress. 4.3.2.3 mioSendTo Syntax: int mioSendTo(int Port, long Pace, char *String) 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: int mioWaitFor(int Port, long Wait, int Case, char *String) 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 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. 4.3.2.5 mioQuiet Syntax: int mioQuiet(int Port,long Wait) The mioQuiet function waits for continuous quiet [no incoming serial data] of 'Wait' milliseconds before returning. Any incoming character while mioQuiet is 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 MODEM_IO.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 a 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 a specified duration. mioBreak : Breaks further modem I/O activity. WSC4VB Users Manual Page 11 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) should 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 150 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 Refer to the LOGIN program (function SendToModem is in the file MODEM_IO.BAS) for an example of sending an initialization string to a Hayes compatible modem. WSC4VB Users Manual Page 12 5.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. Once SIMPLE runs, compile and run the SELFTEST program. This program will test your serial ports' functionality. If your application does not run but SIMPLE and SELFTEST run 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 WSC4VB.BAS in your application ? 2. Is your receive buffer large enough ? Use a receive buffer size that is twice the size of the largest expected incoming block. 3. Have you selected too high a baud rate? Windows can multitask many tasks at once. You may have to lower your baud rate (or get 16550 UARTS). 4. Did SioReset return a zero value ? If not, then you must call SioReset again. See SIMPLE.BAS for an example. 5. Did you send the proper initialization string to your modem ? Did you set DTR and RTS ? (you should). 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. 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 demonstrates the problem. (2) Document your exact machine configuration and what error the test program demonstrates. (3) Upload the example source to our user support BBS, email it 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. WSC4VB Users Manual Page 13 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 use the polled method. In this approach, the CPU is typically in a loop asking the UART over and over again if it has a byte ready. If its does, the polling code returns the byte. But, if the next byte comes in before the polling code is executing again, then that byte is lost. In the interrupt driven approach (used by Windows/WSC4VB), when a byte is received by the UART, an "Interrupt Service Routine" (ISR) is executed immediately, suspending temporarily whatever else is executing. The ISR then moves the byte to a buffer so that your application program can later read it. Transmitted bytes are queued up awaiting transmission. When a byte is moved from the UART transmitter holding register to the UART transmitter shift register, an interrupt is generated and the next byte is taken from the library transmitter buffer by the ISR and written to the UART holding register. Up to 16 bytes can be taken from the transmitter buffer while processing one transmitter interrupt if an 16550 UART is used. The 16550 UART is strongly recommended for computers doing serial communications under Windows. Additional information on serial port hardware can be found in the User's manual for our companion product PCLVBW. WSC4VB Users Manual Page 14 6.2 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. RTS is controlled by the computer and read by the serial device (modem). 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. CTS is controlled by the serial device (modem) and read by the computer. 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. WSC4VB Users Manual Page 15 7.0 Example Programs 7.1 SIMPLE SIMPLE is a very simple communications programming using WSC4VB. 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. The easiest way to test SIMPLE is to connect to a modem. Typing "AT" should result in an "OK" being displayed. A null-modem cable can also be used to connect two computers together with their serial ports. Run SIMPLE on both machines. Whatever is typed on one machine will be displayed on the other. 7.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". 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 LINE.BAS to call up a local BBS. 7.3 SELFTEST SELFTEST performs a serial port I/O functionality test. Either a pair of ports on the same computer (using a null modem cable) or a single port (using a loopback adapter) can be tested. Refer to LOOPBACK.DOC for an explanation of how to make a loopback adapter (without tools!). 7.4 RS232 RS232 is similiar to SELFTEST, but with enhanced capability. It can set flow control (hardware, software, or none), DTR line (set or clear), RTS line (set or clear), display the transmit & receive queue sizes, detect a break signal, detect changes in DSR and CTS, as well as check for various line errors (parity error, framing error, data overrun, receive queue overflow, transmit buffer full). WSC4VB Users Manual Page 16 8.0 Legal Issues 8.1 Registration Two types of registration are provided, (1) Personal and (2) Commercial. (1) Personal Registration is for personal (non-commercial) use of WSC4VB. The registration fee is $39.95. To register, type (from the DOS prompt in the work directory containing WSC10.TMD) : TRIALS -k WSC10 The TRIALS program will prompt you for your name, then display three control codes. You then contact us by phone, mail, email or BBS. We will need to know the exact (case sensitive) name typed into TRIALS as well as the exact control codes displayed. After receiving payment, you will be issued an authorization code which you enter into the TRIALS program, which will generate C:\WSC10.KEY. You can re-run TRIALS to generate the key file once you have the authorization code. However, you must run TRIALS on the same machine the second time in order to get the same control codes. Once WSC10.KEY is created, it can be copied to any machine on which you will use WSC. Personal registration does not include printed manuals or disks. Printed manuals (they are on the distribution archive) can be ordered for $10 per set plus $5 S&H (or $10 S&H outside of North America). (2) Commercial Registration costs $74.95 and includes complete source code, printed manuals, no shareware screen of any kind displayed, and no key file required. A registered archive will be mailed along with printed manuals. To order, contact us as shown on the title page of this manual. Multiple copy discounts (3 or more) and site licenses are available. Please call for details. We accept American Express, VISA, MasterCard, checks in US dollars drawn on a US bank, International Postal Money Orders, 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). For credit card orders, be sure to include the account number, the expiration date, the exact name on the card, and the complete card billing address (the address to which the credit card bill is mailed). WSC4VB Users Manual Page 17 8.1 Registration (continued) Print the file WSC4VB.INV if an invoice is needed. If you wish to update from an older version of WSC4VB, send $25 plus $5 S&H ($10 S&H outside of North America). The commercial registered package includes: o WSC4VB Library w/o shareware screens. o C/C++ source code for WSC and MODEM_IO. o Laser printed Users Manual & Reference Manual. o Telephone, BBS, and email support for one year. The registered user will receive the latest version of WSC4VB shipped by US second day priority mail (packet airmail overseas). A 3.5" diskette is provided unless a 5.25" diskette is requested. All prices are guaranteed for one year from the release date as printed on the title page. 8.2 License MarshallSoft Computing, Inc. grants the registered user of WSC4VB the right to use one copy of the WSC4VB library (in object form) on a single computer in the development of any software product (other than libraries such as WSC4VB). The user may not use the library on more than one computer at the same time. The source code for the library (WSC.C) is copyrighted by MarshallSoft Computing and may not be released in whole or in part. Products developed using WSC4VB 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. WSC4VB Users Manual Page 18 9.0 Summary 9.1 Revision History Version 1.0: 25 August, 1996. - The initial release of WSC4VB. 9.2 Function Summary Refer to the WSC4VB Reference Manual (WSC4VB_R.DOC) 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. | | SioFlow | Enables / disables hardware flow control. | | SioGetc | Reads the next character from the serial line. | | SioGets | Receives a string of characters. | | SioInfo | Returns information such as library version. | | SioParms | Sets parity, stop bits, and word length. | | SioPutc | Transmit a character over a serial line. | | SioPuts | TRansmits a string of characters. | | 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. | | SioRxClear | Clears the receive buffer. | | SioRxQue | Returns the number of characters in the receive queue. | | SioStatus | Returns the serial port line status. | | SioTxClear | Clears the transmit buffer. | | SioTxQue | Returns the number of characters in the transmit queue. | | SioUnGetc | "Un-gets" (puts back) a specified character. | +--------------+-----+-----------------------------------------------------+ WSC4VB Users Manual Page 19 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). You may also want to get a copy of one of our communications products which talks to the hardware directly. They include more hardware specific documentation. 10.0 Other MarshallSoft Computing Products The following shareware libraries are also available from MarshallSoft Computing. 10.1 The Personal Communications Library for Visual BASIC / WIN The Personal Communications Library for Visual BASIC / WIN (PCLVBW) is a DOS based asynchronous communications library designed for experienced software developers programming in Visual Basic / Windows. Unlike WSC4VB, PCLVBW interfaces to the serial port hardware directly. PCLVBW also supports multiport boards such as those made by DigiBoard and BOCA. The Personal Communications Library for Visual BASIC (PCLVBW) is available for $75 plus $5 S&H ($10 S&H overseas). 10.2 The Personal Communications Library for Visual Basic / DOS PCL4VB is similiar to PCLVBW except that it is designed for Visual BASIC applications running under DOS. (Microsoft replaced QuickBasic with Visual Basic / DOS). 10.3 Libraries for Other Languages We have communications libraries for C/C++, Turbo Pascal, Visual Basic , and PowerBASIC. PCL4C : C/C++, DOS [include ptotected mode]. PCL4P : Turbo Pascal, DOS [includes protected mode]. PCL4VB : Visual Basic, DOS. PCL4PB : Power Basic, DOS. PCL4W : C/C++, Windows 3.1 & Win 95, talks to hardware directly. PCLVBW : Visual Basic, Win 3.1 & Win 95, talks to hardware directly. WSC4C : C/C++, Win 3.1 & Win 95, uses Windows API. WSC4VB : Visual Basic, Win 3.1 & Win 95, uses Windows API. WSC4D : Borland DELPHI [Sept 96], Win 3.1 & Win 95, uses Windows API. WSC4VB Users Manual Page 20