Windows Standard

Serial Communications

Users Manual


(WSC_USR)


Version 3.0

July 12, 2000 Revised July 26, 2000




This software is provided as-is. There are no warranties, expressed or implied.



Copyright (C) 2000 All rights reserved



MarshallSoft Computing, Inc. Post Office Box 4543 Huntsville AL 35815 USA


Voice : 256-881-4630

FAX : 256-880-0925

email : info@marshallsoft.com

web : www.marshallsoft.com


MarshallSoft is a member of the Association of Shareware Professionals

MARSHALLSOFT is a registered trademark of MarshallSoft Computing.


TABLE OF CONTENTS


1 Introduction
1.1 Documentation Set
1.2 User Support
1.3 Awards
1.4 ASP Ombudsman
1.5 Ordering
2 Applications Notes
2.1 Dynamic Link Libraries
2.2 GUI and Console Mode
2.3 Using the Library
2.4 Other Languages
2.5 UARTs and Serial Ports
2.6 USB Ports
2.7 PCMCIA Modems
2.8 Threads
3 Modem I/O (MIO)
3.1 MIO Introduction
3.2 MIO Function Summary
4 XMODEM and YMODEM
4.1 XYDRIVER Introduction
4.2 XYDRIVER Function Summary
5 ASCII File Transfer
5.1 ASCII Protocol
5.2 ASCII Function Summary
6 Versions of WSC
6.1 Shareware Version
6.2 Student Version
6.3 Professional Version
7 Problems
8 Legal Issues
8.1 Registration
8.2 License
8.3 Warranty
9 Summary
9.1 WSC Function Summary

1 Introduction

The Windows Standard Serial Communications Library (WSC) is an asynchronous communications 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.

The WSC DLLs (WSC16.DLL and WSC32.DLL) can be called from any application capable of calling Windows API functions, including those written in C/C++, Delphi, Visual Basic, MS Access, MS Excel, Fortran, COBOL, PowerBuilder, FoxPro, Power Basic Console Compiler, dBase, Xbase++, etc. The library runs under Windows 95/98, NT/2000, and Windows 3.1.

We also have declaration files and example programs for a few other languages.

1.1 Documentation Set

The complete set of documentation consists of four manuals in three formats. This is the second manual (WSC_USR) in the set.

Each manual comes in three formats:

The WSC_4x Programmer’s Manual is the language specific manual. All language dependent programming issues are discussed in this manual. Other language specific manuals are as follows:

[NAME]       [DESCRIPTION]
WSC_4C    :  WSC Programmer's Manual for C/C++
WSC_4D    :  WSC Programmer's Manual for Delphi
WSC_4VB   :  WSC Programmer's Manual for Visual Basic
WSC_4PB   :  WSC Programmer's Manual for PowerBASIC
WSC_4CB   :  WSC Programmer's Manual for COBOL
WSC_4FP   :  WSC Programmer's Manual for Visual FoxPro
WSC_4DB   :  WSC Programmer's Manual for Visual dBase
WSC_4XB   :  WSC Programmer's Manual for Xbase++


The WSC User’s Manual (WSC_USR) discusses language independent serial communications programming issues. Read this manual after reading the WSC_4x Programmer’s Manual.

The WSC Reference Manual (WSC_REF) contains details on each individual WSC function.

Use Microsoft Word 97/99 or Microsoft WordPad to print the document files.

1.2 User Support

We want you to be successful in developing your applications using WSC! We are committed to providing the best library that we can. If you have any suggestions or comments, please let us know.

If you are having a problem using WSC, refer to Section 7.0 "Problems". If you still cannot resolve your problem, email us at

              support@marshallsoft.com
You can also reach us at +1-256-881-4630 between 7:00 AM and 7:00 PM CST Monday through Friday. You can also often reach us on Saturday. The latest versions of our products are available on our web site at
              http://www.marshallsoft.com

and on our anonymous FTP site at

              ftp://ftp.marshallsoft.com/pub
The MarshallSoft Computing newsletter "Comm Talk" is published quarterly on our web site. It discusses various communications problems and solutions using our products as well as related information.

1.3 Awards

WSC4C has been rated 4 stars by Ziff Davis on the web at http://www.hotfiles.com. The Visual Basic version (which uses the same DLLs) has been rated 5 stars which is their highest rating. WSC4C is also one of the most popular downloads in the software tools section of many web download sites.

1.4 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 157-F Love Ave., Greenwood, IN 26142 USA, FAX 317-888-2195, or send email to omb@asp-shareware.org.


1.5 Ordering

The professional version of WSC may be registered for $95 (US dollars) for email delivery.

The fastest and easiest way to order is on our web site at

              http://www.marshallsoft.com/order.htm
You can also order by completing INVOICE.TXT (contained within the WSC zip file) and emailing (orders@marshallsoft.com), mailing (see our address at top), or faxing (+1-256-880-0925) it to us. Multiple copy discounts (3 or more) and site licenses are available. Please call for details. We accept American Express, VISA, MasterCard, Discover, checks in US dollars drawn on a US bank, International Postal Money Orders, and purchase orders (POs) within the USA from recognized US schools and companies listed in Dun & Bradstreet. 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- not the bank’s). Please include card holder's signature on faxed orders. Print the file INVOICE.TXT if a "Pro Forma" invoice is needed. The registered package includes:

1.5.2 Academic Discount

We offer an "academic price" of 30% off the normal price for prepaid email orders to faculty and full time students currently enrolled in any accredited high school, college, or university. To qualify for the discount, your school must have a web site and you must have an email address at your school.

When ordering, ask for the "academic discount", or enter "student at" (or "faculty at") and your schools web site address (URL) in the comments field of the order form on our web site order page . Your order will be sent to your email address at your school.

This offer is not retroactive and cannot be used with any other discount. Products bought with academic pricing can not be used for any commercial purpose.

1.5.3 Disk Only

When ordering WSC, a 3.5" HD disk can be purchased for $5 for delivery to the, US, Canada, and Mexico. For all other destinations, the disk is $8.

See INVOICE.TXT or http://www.marshallsoft.com/order.htm

1.5.4 Disk and Printed Manuals

Printed manuals (see Section 1.1 "Documentation Set") are the same as in the WSC shareware distribution. Printed manuals can be purchased for $20 for delivery to the US, Canada, and Mexico. For all other destinations, printed manuals are $25. Printed manuals also comes with a 3.5" HD disk.

See INVOICE.TXT or http://www.marshallsoft.com/order.htm

2 Application Notes

2.1 Dynamic Link Libraries

WSC includes both Win16 [WSC16.DLL] and Win32 [WSC32.DLL] dynamic link libraries (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 a static library which is bound at link time to each and every application that uses it.

2.2 GUI and Console Mode

WSC functions can be called from WIN32 console mode programs as well as GUI programs. A "console mode" program is a Windows 95/98/NT/2000 WIN32 command line program running in a command window. Although console mode programs look like DOS programs, they are WIN32 programs which have access to the entire Windows address space.

2.3 Using the Library

The best way to get familiar with WSC is to try out one of the example programs. The example programs are described in the WSC_4x Programmer's Manual:

[NAME]       [DESCRIPTION]
WSC_4C    :  WSC Programmer's Manual for C/C++
WSC_4D    :  WSC Programmer's Manual for Delphi
WSC_4VB   :  WSC Programmer's Manual for Visual Basic
WSC_4PB   :  WSC Programmer's Manual for PowerBASIC
WSC_4CB   :  WSC Programmer's Manual for COBOL
WSC_4FP   :  WSC Programmer's Manual for Visual FoxPro
WSC_4DB   :  WSC Programmer's Manual for Visual dBase
WSC_4XB   :  WSC Programmer's Manual for Xbase++


2.4 Using WSC with Other Languages

The Windows Standard Serial Communications DLL’s can also be used with any application written in any language capable of calling the Windows (3.1, 95/98/2000, NT) API. WSC16.DLL is required for all Win16 (Windows 3.1) applications, and WSC32.DLL is required for all Win32 (Windows 95/98/2000/NT) applications.

Declaration files have been defined by the following languages:

[LANGUAGE]              [FILE]
C/C++                   WSC.H
Visual Basic            WSC16.BAS and WSC32.BAS
VBA (Excel, Access,…)   WSC32.BAS
PowerBASIC              WSC32.PBI
Borland Delphi          WSC16.PAS and WSC32.PAS
Fujitsu COBOL           WSC32.CBI
ABSOFT FORTRAN          WSC32.INC
Visual FoxPro           WSC32.FOX
Visual dBase            WSC16.CC and WSC32.CC
Alaska Xbase++          WSC32.CH
Additional declaration files will be added. Give us a call if you need a declaration not listed above. If you have interfaced WSC to an unusual language, email us the declaration file!

2.5 UARTs and Serial Ports

Bytes are moved from the UARTs FIFO buffer to the receive memory buffer by the Windows Interrupt Service Routine (ISR), asynchronous to your code. Similarly, the Windows ISR moves bytes from your transmit queue to the UARTs transmit FIFO buffer. Refer to the ASYNC User's Manual (ASYNC.DOC, ASYNC.TXT or ASYNC.HTM) for more information regarding UARTs and serial ports.

2.6 USB Ports

WSC will work with most USB ports which have a "USB to Serial Port" converter cable installed, including the Windows drivers which comes with the cable. The USB port must appear as a serial port to the Windows API, and hence to WSC. The driver that comes with the "USB to Serial Port" converter should appear as a serial port driver to Windows itself. The driver converts from serial port data (including all RS232 signals) to USB data, which is converted back to serial data by the adapter attached to the USB port. We have tested the "USB to Serial CONVERTER Cable" by D-Link (www.dlink.com) and found it to work well with WSC.

2.7 PCMCIA Modems

WSC will work with most PCMCIA modems (card modems for laptops). The PCMCIA drivers that come with the modem card must be properly installed. The PCMCIA modem must appear as a normal serial port modem to Windows. The PCMCIA modem should come with several drivers, including a serial port driver and a modem driver. We have tested the "Venus K56Flex V.90" PCMCIA card and found it to work properly with WSC.

2.8 Threads

WSC is thread safe. Note that in Windows 2000 (but not in Windows 95/98), calling
      SioEvent(Port, EV_RXCHAR)
blocks the outgoing serial stream as well as the incoming serial stream.

3 Modem I/O (MIO)

3.1 MIO Introduction

The Modem I/O functions ease communicating with modems using AT commands.

The MIO functions are broken down into parts called states, and control is returned to Windows between executing each state. This allows other code to run while waiting for MIO functions to complete.

For example (C/C++ Example):

  1. Send the string to the MIO driver by executing:

Code = mioSendTo(Port,100,"!ATDT1,800,555,1212")

The '!' characters are converted to carriage returns. The text string is copied into the driver's data area.

  1. 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. Any other return value indicates that it is still processing and the returned value is a character from the modem that can be displayed if wanted.

  1. Once mioDriver returns MIO_IDLE, call mioResult to get the result of the mioSendTo call.

3.2 MIO Function Summary

Refer to the WSC Reference Manual (WSC_REF) for more information on individual MIO functions.


4 XMODEM and YMODEM

4.1 XYDRIVER Introduction

The XMODEM and YMODEM functions are implemented as DLL's (Dynamic Link Libraries), in XYDRV16.DLL and XYDRV32.DLL, and are state driven like the Modem I/O functions described in the previous section.

Files can be sent and received using XMODEM, XMODEM/CRC, XMODEM/1K, and YMODEM. The basic procedure used to run XMODEM and YMODEM is as follows:

  1. Call xyAcquire() immediately after calling SioReset().
  2. To receive a file, call xyStartRx(), then call xyDriver() repeatedly until XY_IDLE is returned.
  3. To send a file, call xyStartTx(), then call xyDriver() repeatedly until XY_IDLE is returned.
  4. Call xyRelease() immediately before calling SioDone().

Refer to XMODEM.TXT for more information on the internal operation of the XMODEM protocol, and to YMODEM.TXT for more information on the internal operation of the YMODEM protocol. Also see the TERM example program.

4.2 XYDRIVER Function Summary

Refer to the WSC Reference Manual (WSC_REF) for more information on individual XYDRIVER functions (XYDRV16 and XYDRV32 DLL’s).

5 ASCII File Transfer

5.1 ASCII Protocol

The "ASCII Protocol" is not a defined protocol, but rather it is a loose set of conventions developed over a period of years by BBS operators. Because XON/OFF flow control is used, only ASCII text can be transferred. The ASCII protocol is implemented as a DLL and is state driven like the MIO and XYDRIVER code.

  1. Call ascInit(Port,RxQueSize,xFlag) to do initialization, where

  1. To send an ASCII file, call

ascStartTx(FileName,CharPace,TermChar,EchoFlag), where

Then call ascDriver() until it returns IDLE (1).

  1. To receive an ASCII file, call

ascStartRx(FileName,TermChar,FirstWait,CharWait,EchoFlag), where

Then call ascDriver() until it returns IDLE (1).

5.2 ASCII Function Summary

6 Versions of WSC

The Windows Standard Serial Communications (WSC) library is available in three versions. All three versions have identical functionality.

6.1 Shareware Version

The shareware version can be differentiated from the other two versions by:

  1. The shareware reminder screen is displayed at startup.

  2. The shareware version may not be used for commercial purposes.

6.2 Student Version

The student version can be differentiated from the other two versions by:

  1. There is no shareware reminder screen.

  2. The Student version may not be used for commercial purposes.

6.3 Professional Version

The professional version can be differentiated from the other two versions by:

  1. There is no shareware reminder screen.

  2. Source for WSC, MIO, and XYDRIVER is provided.

  1. Your compiled DLLs may be distributed with your compiled applications. However the source code to the DLLs may NOT be distributed.

  2. The Professional version may be used for commercial purposes.

The professional version may be distributed with your application as specified by the software license. See Section 1.5 "Ordering" for details on ordering and Section 8.2 for the license information.

7 Problems

  1. 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.

  1. 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.

  2. Are your receive and transmit buffers large enough? Use a buffer size that is twice the size of the largest expected 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.

  5. Did you send the proper initialization string to your modem? Did you set DTR and RTS? (you should).

  6. Are you trying to link a 32-bit DLL to a 16-bit program (or vice versa)? Keep Win16 & Win32 development separate.

  7. If you are using the registered version of WSC and you are still getting the shareware screen, make sure you have deleted all copies of the WSC shareware DLL's in the Windows search path.

We recommend the following steps if you believe that you have discovered a bug in the library:

  1. Create the smallest, simplest test program possible that demonstrates the problem.
  2. Document your exact machine configuration and what error the test program demonstrates.
  3. Email us the example source.

If the problem is an error in the library and 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.


8 Legal Issues

8.1 Registration

See Section 1.5 "Ordering" for information on ordering.

8.2 License

MarshallSoft Computing, Inc. grants the registered user of WSC the right to use one copy of the WSC DLL's on a single computer in the development of any software product. The user may not use the library on more than one computer at the same time.

The "student" ($66 USD) registered DLL's may not be distributed under any circumstances, nor may they be used for any commercial purpose.

The "professional" ($95 USD) registered DLL's may be distributed (without royalty) in object form only, as part of the user's compiled application. The registered DLL's may NOT be distributed as part of any software development system (compiler or interpreter) without our express written permission. The source code for the library (WSC16.C, WSC32.C, MIO.C, and XYDRV.C) is copyrighted by MarshallSoft Computing and may not be released in whole or in part.

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.

9 Summary

9.1 WSC Function Summary

Refer to the WSC Reference Manual (WSC_REF) for detailed information on the WSC functions. A one line summary of each function follows.

There are 28 functions in the WSC library.