


                  Windows Standard Serial Communications

                            Library for C/C++

                                 (WSC4C)


                              USERS MANUAL



                               Version 2.4

                               May 17, 1999




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




                         Copyright (C) 1996-1999
                           All rights reserved



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

                           Voice : 256-881-4630
                             FAX : 256-880-0925
                           email : info@marshallsoft.com
                             web : www.marshallsoft.com


                               _______
                          ____|__     |                (R)
                       --+       |    +-------------------
                         |   ____|__  |  Association of
                         |  |       |_|  Shareware
                         |__|   o   |    Professionals
                       --+--+   |   +---------------------
                            |___|___|    MEMBER









     WSC4C 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 Awards..................................................4
           1.4 Installation............................................5
           1.5 Uninstalling............................................5
           1.6 Limitations on COM Ports................................5
       2.0 Library Overview............................................6
           2.1 Dynamic Link Libraries..................................6
           2.2 Console Mode............................................6
           2.3 Using the Library.......................................6
           2.4 Static Libraries........................................7
           2.5 Large Memory Model in Win16.............................7
           2.6 Win32 STDCALL and DECLSPEC..............................7
           2.7 Using Threads...........................................7
       3.0 Compiling Programs..........................................8
           3.1 Using a Makefile........................................8
           3.2 Using an IDE............................................9
           3.3 Compiling WSC..........................................11
           3.4 Compiling Example Programs.............................11
       4.0 Modem I/O..................................................12
           4.1 MIO Introduction.......................................12
           4.2 MIO Function Summary...................................12
       5.0 XMODEM & YMODEM ...........................................13
           5.1 XYDRIVER Introduction..................................13
           5.2 XYDRIVER Function Summary..............................13
       6.0 ASCII File Transfer........................................14
       7.0 Problems...................................................15
       8.0 Example Programs...........................................16
       9.0 Legal Issues...............................................18
           9.1 Registration...........................................18
           9.2 Academic Discount......................................18
           9.3 License................................................19
           9.4 Warranty...............................................19
      10.0 Summary....................................................20
           10.1 Revision History......................................20
           10.2 WSC Function Summary..................................21
           10.3 Further Reading.......................................22
      11.0 Other MarshallSoft Computing Products......................22
           11.1 Personal Communications Library for C/C++.............22
           11.2 Serial Libraries for Other Languages..................22
           11.3 Internet Libraries....................................22











     WSC4C Users Manual                                        Page 2

      1.0 Introduction

      The Windows Standard Serial Communications Library for C/C++ (WSC4C)
      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 WSC4C 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,
      etc. The library runs under NT, Windows 95/98, and Windows 3.1.

      Registered users can statically link WSC with their application
      rather than using the DLLs.

      Using WSC is very straight-forward. For example, to write "HELLO" to
      the serial port COM1:

           SioReset(COM1,512,512)     /* open COM1 with 512 KB buffers */
           SioPuts(COM1,"HELLO\r",6)  /* write "HELLO" to COM1 */
           SioDone(COM1)              /* close COM1 */

      Several C/C++ example programs with full source code are included.
      Refer to Chapter 8 for more details on each of the example programs.

             SIMPLE : A simple terminal emulator.
           SELFTEST : Performs COM port functionality testing.
              MODEM : Same as SIMPLE but controls flow control, modem
                      lines, etc.
               TERM : Terminal emulator with XMODEM, YMODEM, and ANSI
                      terminal emulator support.
                BCB : Borland C++ Builder (32-bit C++) example.
            MFC_PGM : Microsoft Foundation Class (MFC) example program.
            CONSOLE : A WIN32 console mode program similar to SIMPLE.
             FINDER : Finds a modem connected to one of your serial ports.
           ECHOPORT : Multi-threaded console mode program echoes all input.
              EVENT : Blocking version of SIMPLE. Uses SioEvent.
          XMS & XMR : Console mode XMODEM programs.
              RS485 : RS485 version of CONSOLE.

      WSC4C contains over 25 functions. All functions return a negative
      number if an error condition is detected.  For more details, consult
      the WSC4C Reference Manual (WSC4C_R.TXT). Also see the RS232/485
      Serial Communications Users Manual (ASYNC.TXT).

      Our goal is to provide a robust serial communications library that
      you and your customers can depend upon. Contact us if you have any
      questions.

      The shareware and registered versions are identical except that the
      shareware version displays the "shareware" screen when first
      starting, after 20 minutes of run time, and every 10 minutes after
      that. The registered version also includes source code.


     WSC4C Users Manual                                        Page 3

      1.1 User Support

      We want you to be successful in developing your applications using
      WSC4C! We depend upon our customers to let us know what they need in
      a communications library. If you have any suggestions or comments,
      please let us know.

      If you are having a problem using WSC4C, email us at

         support@marshallsoft.com

      You can also reach us at 256-881-4630 between 7:00 AM and 7:00 PM CST
      Monday through Friday. You can also often get us on the weekend.

      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/marshallsoft

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

      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, their highest rating.

      WSC4C is also one of the most popular downloads in the software tools
      section of many web download sites.











     WSC4C Users Manual                                        Page 4

      1.4 Installation

      Installation consists of copying WSC4C24.ZIP (WSC4C.ZIP for
      registered users) to a work directory, unzipping the files, running
      the INSTALL program, and compiling and running one of the example
      application programs such as SIMPLE.

      Unzip the files by typing

         PKUNZIP WSC4C24.ZIP

      Run the INSTALL batch file, which will copy the correct LIBs and DLLs
      for your compiler.

      INSTALL1 -- For all WIN16 Windows compilers (doesn't copy WIN32
      DLL's).

      INSTALLU -- For WIN32 compilers supporting the "declspec" keyword,
      which includes MS Visual C/C++ 4.0 and above, Borland C/C++ 5.0 and
      above, Borland C++ Builder (all versions), and Watcom 11.0 and above.
      This is the preferred choice if possible.

      INSTALLM ++ Native Microsoft.
      INSTALLB ++ Native Borland.
      INSTALLW ++ Native Watcom.

      INSTALL.BAT also copies the proper DLL to your Windows directory,
      usually C:\WINDOWS or C:\WINNT.

      The WIN32 choices ("INSTALLU", etc) also copies WSC16.LIB and WSC16.DLL.

           WSC32.DLL & WSC32.LIB
           MIO32.DLL & MIO32.LIB
         XYDRV32.DLL & XYDRV32.LIB
         ASDRV32.DLL & ASDRV32.LIB

      You are now ready to compile and run a test program. Refer to Section
      3.4 "Compiling Example Programs".

      1.5 Uninstalling

      Uninstalling WSC4C is very easy. WSC4C does NOT modify the
      registry. First, delete the WSC4C project directory created when
      installing WSC4C. Second, delete WSC16.DLL and WSC32.DLL from your
      Windows directory, typically C:\WINDOWS for Windows 95/98 or
      C:\WINNT for Windows NT. Thats it!

      Running the UINSTALL.BAT batch file will also delete WSC16.DLL and
      WSC32.DLL as described above.

      1.6 Limitations on COM Ports

      The 32-bit version of WSC4C (WSC32.DLL) can use any port from COM1 to
      COM20, provided that the port is known to Windows 95/98/NT and there
      is physical hardware present. More ports can easily be added by
      recompiling WSC32.C.


     WSC4C Users Manual                                        Page 5

      2.0 Library Overview

      2.1 Dynamic Link Libraries

      WSC4C includes both Win16 [WSC16] and a Win32 [WSC32] 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.

      2.2 Console Mode

      WSC4C functions can be called from WIN32 console mode programs. A
      "console mode" program is a Windows 95/98/NT 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 WSC4C has been tested on multiple computers running Windows 3.1,
      Windows 95/98, and Windows NT 4.0.

      WSC4C has also been tested with Microsoft C/C++ 7.0 (from the
      Windows SDK), Microsoft Visual C/C++, Borland C/C++ (including C
      Builder), Turbo C/C++, and Watcom C/C++.

      Please examine the WSC.H file. Note that COM1 is defined as port
      zero, not port one.  The user must assume the responsibility for
      passing the correct information when calling WSC4C functions.

      The INSTALL.BAT batch command file will copy the correct LIBs and
      DLLs. Refer to section 1.4 "Installation".

      WSC32U.DLL : For Microsoft Visual C/C++ 5.0, Borland C/C++ 5.0,
                   Watcom C/C++ 11.0, and later compilers.
      WSC32B.DLL : Borland C/C++ 4.5 compilers.
      WSC32W.DLL : Watcom 10.5 and 10.6 compilers.

      2.4 Static Libraries

      The registered user can easily compile WSC16.C (or WSC32.C) into his
      application, so that the WSC DLL's are not needed. The makefiles
      STATIC16._?_ and STATIC32._?_ compile WSC to create versions of
      SIMPLE which don't require the use of WSC16.DLL or WSC32.DLL.

      Static libraries require the source code for WSC, which is included
      in the registration package.








     WSC4C Users Manual                                        Page 6

      2.5 Large Memory Model in Win16

      WSC16.DLL can be used from Win16 programs written in any memory
      model. Two examples are included in this archive for compiling
      SIMPLE.C for the large memory model.

      SIMPLE16._ML   Large memory model makefile for Microsoft
      SIMPLE16._BL   Large memory model makefile for Borland.

      2.6 Win32 STDCALL and DECLSPEC

      WSC32 is compiled using the _stdcall and _declspec keywords. This
      means that WSC4C uses the same calling conventions and file naming
      conventions as the Win32 API. In particular, function names are NOT
      decorated. There is no leading underscore nor trailing "@size" added
      to function names.

      Microsoft Visual C/C++ users can look at the WSC32 function names
      using the dumpbin.exe executable:

         dumpbin /exports wsc32.dll

      Some older compilers do not support the "declspec" keyword. For this
      reason, we have provided two WSC.H prototype files:

         wsc32.h1 : For compilers NOT supporting "declspec".
         wsc32.h2 : For compilers which do support "declspec" (default).

      Versions of WSC for older compilers are also included. The proper
      versions are copied when running the INSTALL.BAT batch file. Refer to
      Section 1.4 "Installation" for more details.

      2.7 Using Threads

      WSC4C is thread safe. Refer to the ECHOPORT example program, which
      demonstrates the use of multiple threads. ECHOPORT also demonstrates
      the use of the WIN32 Sleep() function.





















     WSC4C Users Manual                                        Page 7

      3.0 Compiling Programs

      WSC4C has been tested using Microsoft, Borland, and Watcom C/C++
      compilers. Before compiling, be sure that you have run INSTALL.BAT.

      The example programs can be compiled by using either the provided
      makefiles or creating a project file for the "Integrated Development
      Environments", or IDEs. Separate makefiles are provide for Win16 and
      Win32 programs.

      3.1 Using a MAKEFILE

      Makefiles originated on UNIX systems. They are the standard way that
      C/C++ programs are constructed in command line environments. Windows
      programs can be constructed with makefiles from the DOS prompt using
      command line Windows compilers.

      Makefiles are provided for Microsoft, Borland, and Watcom command
      line compilers. Makefiles have file extensions of "_M_" and "MAK" for
      Microsoft, "_B_" for Borland, and "_W_" for WATCOM. Thus,
      SIMPLE16._W_ is the Watcom Win16 makefile for SIMPLE and SIMPLE32._M_
      is the Microsoft Win32 makefile.

      Turbo C/C++ for Windows and Borland C++ Builder (BCB) do not support
      command line makefiles. The IDE must be used instead.

      The big advantage of makefiles over using an IDE is that all compiler
      switches and options can be completely specified within the makefile.
      A secondary advantage is that makefiles can be started from a batch
      file, completely automating the software build process. For this
      reason, makefiles are preferred over IDEs.



























     WSC4C Users Manual                                        Page 8

      3.2 Using an IDE

      All windows compilers have an "Integrated Development Environment"
      (IDE) for building application programs in the Windows environment.
      Since there is no standard format for IDE project files, file names
      must be entered into the IDE from the keyboard.  Each example program
      has a project text file (e.g. SIMPLE.PRJ) which contains the list of
      filenames that must be entered into the IDE.

      However, creating a project file within the IDE is very easy. Each
      application has a project file (SIMPLE.PRJ, TERM.PRJ, SELFTEST.PRJ,
      MODEM.PRJ). Each project file contains the filenames that must be
      entered into the IDE.

      For each IDE, you will have to enter these filenames into the IDE.
      This is usually done with the INS key except for the Microsoft
      Developer, which uses menu commands. Be careful to enter all
      filenames as listed in the ".PRJ" file.

      All of the example application programs have been built using IDE's
      from Microsoft, Borland, and Watcom. However, there are differences
      between IDE versions from the same compiler manufacturer.

      All of the IDEs use the concept of a file hierarchy. For example, the
      SIMPLE file hierarchy in the IDE should look like:

         SIMPLE.EXE
         +++ WSC16.LIB
         +++ ABOUT.C
         +++ LINE.C
         +++ PAINT.C
         +++ SIMPLE.C
         +++ SIOERROR.C
         +++ SIMPLE.DEF
         +++ SIMPLE.RC

      Replace WSC16.LIB above with WSC32.LIB for 32 bit applications. The
      order of the files is not significant.

      NOTE: Win32 Borland users must create the proper WSC32.LIB from
      WSC32.DLL by running the "implib" program in the compilers \BIN
      directory.

         implib wsc32.lib wsc32.dll

      Note the WSC32.LIB is also created in the Borland makefiles.

      3.2.1 Microsoft IDE

      To create a new project, choose "Project", then "New". Select Win16
      [Win32] as the target. A dialog box will then pop up into which the
      project file names are entered.






     WSC4C Users Manual                                        Page 9

      3.2.2 Microsoft Developer Studio

      To open an existing project, choose "File", then "Open Workspace",
      and then select "Makefiles" from the list of file types. See the
      MS Developer generated makefile SIMPLE.MAK.

      To create a new project, choose "File", then "New", then "Project
      Workspace". Select "Application" for "Type:" and a project name for
      "Name:". Choose Win16 or Win32 for platform. Then select "Create".

      Select "Insert", then "Files into Project". Add all filenames as
      listed in the ".PRJ" file corresponding to the project you are
      building. Lastly, select "Rebuild All".

      3.2.3 Borland IDE

      To create a new project, first turn off LINKER case sensitivities:
      Choose "Options", "Projects", "Linker", "General". Turn off the "case
      sensitive link" and "case sensitive exports and imports" boxes.

      Next, choose "Project", then "New Project". Use the INS (Insert) key
      to pop up a dialog box into which the project file names are entered.

      Select "GUI" for the "Target Model:" Only "Runtime" and "Dynamic"
      should be checked for "Standard Libraries:"

      NOTE1: If, after linking in the IDE, you get unresolved external
      references to the communications library functions in which each
      function name is all upper case, then you have NOT turned off case
      sensitivity as described above.

      NOTE2: If you get errors compiling the windows header file
      "WINDOWS.H", turn on "Borland Extensions" in "Options", "Project",
      "Compiler", "Source".

      3.2.4 Turbo C IDE

      Follow the same directions as above, except that the "Target Model:"
      can be any listed.

      3.2.5 Borland C++ Builder

      To create a new project, Choose "File" / "Open Project" on the menu
      bar. Load BCB_PRJ.MAK. Then, choose "Build All" from "Project" to
      create the executable.

      3.3.6 Watcom IDE

      To create a new project, choose "File", then "New Project". Enter
      the project name and then choose Win16 [Win32] as the target. Use the
      INS (Insert) key to pop up a dialog box into which the project file
      names are entered.

      Select "Options" from the main window, then "C Compiler Switches",
      then "10". Memory Models and Processor Switches". Check "80386 Stack
      based calling [-3s]", then check "32-bit Flat model [-mf]".


     WSC4C Users Manual                                        Page 10

      3.3 Compiling WSC

      WSC16.DLL and WSC32.DLL have been compiled using Microsoft Visual
      C/C++, and are callable from applications written using Microsoft,
      Borland, or Watcom compilers. If you recompile WSC32.C using Borland
      or Watcom compilers, then the resulting WSC32.DLL can only be used by
      applications compiled with the same compiler, unless the "_stdcall"
      and "_declspec" keywords are specified.

      Before compiling, be sure to run the installation batch file
      INSTALL.BAT, as explained in section 1.4 "Installation".

      For Microsoft C, type:

          NMAKE -f WSC16._M_
          NMAKE -f WSC32._M_

      For Borland C, type:

          MAKE -f WSC16._B_
          MAKE -f WSC32._B_

      For Watcom C, type:

          WMAKE -f WSC16._W_
          WMAKE -f WSC32._W_

      3.4 Compiling Example Programs

      There are makefiles provided for each of the example programs.
      For example, to compile SIMPLE:

      For Microsoft C, type:

          NMAKE -f SIMPLE16._M_
          NMAKE -f SIMPLE32._M_

      For Borland C, type:

          MAKE -f SIMPLE16._B_
          MAKE -f SIMPLE32._B_

      For Watcom C, type:

          WMAKE -f SIMPLE16._W_
          WMAKE -f SIMPLE32._W_

      There is also a Microsoft Developer Studio generated makefile for
      SIMPLE. See SIMPLE.MAK.









     WSC4C Users Manual                                        Page 11

      4.0 MODEM I/O (MIO)

      4.1 MIO Introduction

      The file MIO.H contains prototypes for using the Modem I/O DLL. These
      functions ease communicating with modems using AT commands. The TERM
      program contains an example of using the MIO functions.

      The Windows "operating system" is what is called "cooperative
      multitasking". The executing Windows task must voluntarily "give up"
      control before another Windows task (or Windows itself) can execute.
      The MIO functions are broken down into parts called states, and
      control is returned to Windows between executing each state.

      The MIO string buffer is set at 128 bytes.

      For example:

      (1) Send the string to the MIO driver by executing:

      Code = mioSendTo(Port,100,"!ATDT1,256,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. 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.

      (3) Once mioDriver returns MIO_IDLE, call mioResult to get the
      result of the mioSendTo call.

      4.2 MIO Function Summary

       mioDriver : Drives the execution of mioSendTo, mioWaitFor, or
                   mioQuiet once they have been started.
        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.

      Refer to the WSC Reference Manual for more information.




     WSC4C Users Manual                                        Page 12

      5.0 XMODEM & YMODEM

      5.1 XYDRIVER Introduction

      The XMODEM & YMODEM functions are implemented in XYDRV as a DLL
      (Dynamic Link Library), and are state driven like the Modem I/O
      functions described in the previous section. The TERM program
      provides an example of using XYDRIVER. Also see the console mode
      example programs XMS and XMR.

      A timer is normally set up [ SetTimer(hMainWnd,1,125,NULL) ] which in
      turn calls xyDriver in the message loop in MainWndProc.

           WM_TIMER: Code = xyDriver(Port);
                     ...
                     break;

      Files can be sent and received using XMODEM, XMODEM/CRC, XMODEM/1K,
      and YMODEM. The basic procedure used to run XMODEM or 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 the TERM program for examples of calling the XYDRV
      functions.

      5.2 XYDRIVER Function Summary

             xyAbort : Abort driver at any time.
           xyAcquire : Acquire a port.
             xyDebug : Set the debug level.
            xyDriver : Executes the next state or states.
        xyGetMessage : Get the next debug message.
      xyGetParameter : Get a driver parameter.
       xyGetFileName : Get name of file being sent or received.
           xyRelease : Release a port.
           xyStartRx : Start a receive.
           xyStartTx : Start a transmit.

      Refer to the WSC Reference Manual for more information.













     WSC4C Users Manual                                        Page 13

      6.0 ASCII File Transfer

      6.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 XYDRVIVER code.

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

            Port = The connected port (COM1, COM2, etc).
       RxQueSize = The size of the Rx Queue as passed to SioReset().
           xFlag = 1 if this module will perform XON/XOFF flow control.
                   Set to FALSE if flow control is being performed by the
                   WSC code (you called SioFlow()).

      (2) To send an ASCII file, call

      ascStartTx(FileName,CharPace,TermChar,EchoFlag), where
         FileName = The path & name of the file to send.
         CharPace = The delay in milliseconds between characters.
         TermChar = The termination character to send after the file
                    has been sent. If none, use 0x00.
         EchoFlag = 1 if screen echo is desired.

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

      (3) To receive an ASCII file, call

      ascStartRx(FileName,TermChar,FirstWait,CharWait,EchoFlag), where
         FileName = The path & name of the file to send.
         TermChar = The termination character. If none, use 0x00.
        FirstWait = The maximum number of seconds to wait for the
                    first incoming character.
         CharWait = The maximum number of seconds after which it is
                    assumed that the other side has completed sending.
                    If unsure, set this to 3 seconds.
         EchoFlag = 1 if screen echo is desired.

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

      6.2 ASCII Function Summary

             ascAbort : Abort driver at any time.
            ascDriver : Executes the next state or states.
        ascGetMessage : Get the next debug message.
      ascGetParameter : Get a driver parameter.
       ascGetFileName : Get name of file being sent or received.
              ascInit : Initialize the driver.
           ascStartRx : Start a receive.
           ascStartTx : Start a transmit.





     WSC4C Users Manual                                        Page 14

      7.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 WSC.H in your application? If WSC.H
      does not exist, then you have not run INSTALL.BAT.

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

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

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

      9. If you do not have the WSC.H file, you have not run INSTALL.BAT.

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






     WSC4C Users Manual                                        Page 15

      8.0 Example Programs

      8.1 SIMPLE

      SIMPLE is a very simple communications program using WSC4C.
      Everything typed on the keyboard is sent to the serial port, and
      everything 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.

      8.2 SELFTEST

      SELFTEST performs a serial port I/O functionality test using a
      loopback adapter. Refer to LOOPBACK.TXT for an explanation of how to
      make a loopback adapter (without tools!).

      8.3 MODEM

      MODEM is similar 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, and transmit buffer full).

      8.4 TERM

      TERM is a simple ANSI terminal emulator suitable for calling up a BBS
      and downloading or uploading files using XMODEM or YMODEM. The TERM
      program uses MIO16.DLL (or MIO32.DLL) for modem control commands, and
      XYDRV16.DLL (or XYDRV32.DLL) for XMODEM & YMODEM file transfer.

      Selecting "Dial" from the menu bar will result in a pop-up dialog
      requesting the phone number to dial. Once entered, the number is
      dialed, and 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" on the menu bar.

      Once logged on, files can be uploaded or downloaded by selecting
      "Send" or "Receive" from the menu bar. To abort a file transfer,
      choose "BREAK" from the menu bar then type a series of Ctrl-X (^X)
      characters from the keyboard.

      TERM uses ANSI.C, which provides ANSI terminal emulator support.













     WSC4C Users Manual                                        Page 16

      8.5 BCB_PGM

      BCB_PGM is a Borland C++ Builder example program similar to SIMPLE.
      BCB_PRJ.MAK is the makefile necessary for building BCB_PGM.EXE.

      8.6 MFC_PGM

      MFC_PGM is a Microsoft Foundation Class C++ program similar to SIMPLE.
      MFCPGM16.MAK is the Win16 makefile and MFCPGN32.MAK is the Win32
      makefile.

      8.7 CONSOLE

      The CONSOLE program is a WIN32 console mode program similar to
      SIMPLE. It also demonstrates how to acquire and manipulate the
      standard input handle so that a "KeyPress" function can be
      implemented.

      CONSOLE takes the port and baud rate as arguments. For example, to
      start CONSOLE on COM1 at 38,400 baud:

         CONSOLE 1 38400

      8.8 FINDER

      The FINDER program is a WIN32 console mode program that searches for
      a connected modem. Your modem must be connected to one of COM1
      through COM4, and the modem must be turned on. FINDER takes no
      arguments.

      8.9 ECHOPORT

      The ECHOPORT console mode program demonstrates the use of threads.
      Connect COM1 and/or COM2 to another computer or serial device using a
      NULL modem cable. ECHOPORT will echo back to the remote anything it
      receives on the serial port. ECHOPORT takes no arguments.

      8.10 EVENT

      The EVENT console mode program demonstrates the use of SioEvent in
      efficiently waiting for serial input. No polling or timer is
      required. EVENT operates like SIMPLE.

      8.11 XMS and XMR

      XMS (XMODEM Send) and XMR (XMODEM Receive) are console mode programs
      that send and receive files using the XMODEM protocol.

      8.12 RS485

      The RS485 example program operates like SIMPLE, except that it
      assumes an RS485 port. RTS is set before transmitting data, and
      cleared after the last bit of the last byte has been sent.





     WSC4C Users Manual                                        Page 17

      9.0 Legal Issues

      9.1 Registration

      WSC4C may be registered for $85 plus $7 S&H ($12 outside of North
      America).

      To order, contact us as shown on the title page of this manual. All
      prices are guaranteed for one year from the release date.

      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,
      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 $5 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 (address to which the credit card bill is mailed).
      Credit card orders can be called in, emailed, faxed or submitted
      using our secure server at www.marshallsoft.com. Print the file
      INVOICE.TXT if a "Pro Forma" invoice is needed. Note that all
      ordering information collected, including email addresses, is kept
      strictly confidential.

      If you wish to update from an older version of WSC4C, send $30 plus
      $7 S&H ($12 S&H outside of North America). The registered package
      includes:
           o  Win16 & Win32 WSC4C Libraries w/o shareware screens.
           o  Win16 & Win32 source code for WSC, MIO, and XYDRIVER.
           o  Printed Users Manual & Reference Manual.
           o  Telephone and email support for one year.

      The registered user will receive the latest version of WSC4C shipped
      by US second day priority mail (packet airmail overseas).  A 3.5"
      HD diskette is provided.

      9.2 Academic Discount

      We offer an "academic price" of 40% off the normal price for prepaid
      email orders to faculty and 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.


     WSC4C Users Manual                                        Page 18

      9.3 License

      MarshallSoft Computing, Inc. grants the registered user of WSC4C the
      right to use one copy of the WSC4C library (in object form) on a
      single computer in the development of any software product (other
      than libraries such as WSC4C). The user may not use the library on
      more than one computer at the same time.  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.
      The registered DLLs may be distributed (without royalty) in object
      form only, as part of the user's application, provided that the
      application is NOT a compiler, interpreter, or other software
      development program.

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














     WSC4C Users Manual                                        Page 19

      10.0 Summary

      10.1 Revision History

      Version 1.0: September 6, 1996.

          o  The initial release of WSC4C.

      Version 2.0: January 25, 1997.

          o  Includes Win32 libraries [Microsoft, Borland, Watcom].
          o  Added XMODEM & YMODEM DLL (XYDRIVER.DLL).
          o  Added TERM example program.

      Version 2.1: June 2, 1997.

          o  Added ANSI terminal emulator support.
          o  Added "expires" option to SioInfo(). [SHAREWARE ONLY].
          o  Added SioRead function.
          o  Added Borland C Builder example program.

      Version 2.2: October 1, 1997.

          o  Fixed problem in XYDRV.C (renamed from XYDRIVER.C)
          o  Added xyGetFileName function to XYDRV.
          o  WSC4C supports up to 16 ports.
          o  WSC4C runs under Windows NT.
          o  Added Microsoft Foundation Class (MFC) Example.
          o  Added ASCII protocol.

      Version 2.3: July 15, 1998.

          o  Multiple changes to XYDRV for added capability.
          o  SioTimer() function added to WSC16 and WSC32.
          o  FINDER example modem search program added.
          o  CONSOLE example console mode program added.
          o  ECHOPORT example multi-thread program added.
          o  SioBaud & SioParms can be called before SioReset.
          o  WSC32.C modified so that the number of supported ports
             can be easily increased.

      Version 2.4: May 17, 1999.

          o  SioEvent function added (WIN32 only).
          o  New xyDriver code.
          o  New XMODEM example programs (XMS and XMR).
          o  New RS485 example program.
          o  Specify default DTR & RTS behavior with SioReset.










     WSC4C Users Manual                                        Page 20

      10.2 WSC Function Summary

      Refer to the WSC4C Reference Manual (WSC4C_R.TXT) for detailed
      information on the communications and support functions.

      Refer to the RS232/485 Serial Communications Users Manual
      (ASYNC.TXT) for technical information on UARTs, modems, and other
      RS232 issues.

      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.  |
      | 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). |
      | SioEvent    |  Wait for specified event.                          |
      | 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.                  |
      | SioRead     |  Reads any UART register.                           |
      | 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).  |
      | SioRxClear  |  Clears the receive buffer.                         |
      | SioRxQue    |  Returns the number of characters in the RX queue.  |
      | SioStatus   |  Returns the serial port line status.               |
      | SioTimer    |  Returns the system times in milliseconds.          |
      | SioTxClear  |  Clears the transmit buffer.                        |
      | SioTxQue    |  Returns the number of characters in the TX queue.  |
      | SioUnGetc   |  "Ungets" (puts back) a specified character.        |
      | SioWinError |  Returns Win32 error message as text.               |
      +-------------+-----------------------------------------------------+


















     WSC4C Users Manual                                        Page 21

      10.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 Programmer's Guide to Serial Communications by Joe Campbell
      (SAMS) (2) Mastering Serial Communications by Peter Gofton (SYBEX).

      11.0 Other MarshallSoft Computing Products

      Several shareware products are available from MarshallSoft Computing.

      11.1 The Personal Communications Library for C/C++

      The Personal Communications Library for C/C++" (PCL4C) is a DOS based
      serial communications library supporting real and protected mode DOS.
      PCL4C supports ports COM1 through COM20 to 115200, 4+ ports
      concurrently, many dumb multiport boards, 16550, 16650, and 16750
      UARTs. PCL4C is interrupt driven, supporting RTS/CTS flow control,
      any UART address and IRQ, all memory models. PCL4C can be used with
      Watcom C/C++, Borland/Turbo C/C++, MIX Power C, and Microsoft C/C++.

      11.2 Serial Libraries for Other Languages

      We have DOS and Windows communications libraries for C/C++, Turbo
      Pascal, Visual Basic, and PowerBASIC. All PCL libraries support the
      8250, 16450, 16550, 16650, and 16750 UARTs. Check our WEB site.

        PCL4C : C/C++, DOS (includes 16-bit protected mode).
        PCL4P : Turbo Pascal, DOS (includes 16-bit protected mode).
       PCL4VB : Visual Basic, DOS (VBDOS). Also supports Quick Basic.
       PCL4PB : PowerBASIC, DOS.

        WSC4C : C/C++, Win 3.1/95/98/NT. Uses Windows API.
       WSC4VB : Visual Basic, Win 3.1/95/98/NT. Uses Windows API.
        WSC4D : Borland Delphi, Win 3.1/95/98/NT. Uses Windows API.
       WSC4PB : PowerBASIIC Console Compiler, Win 95/98/NT. Uses Win API.

       11.3 Internet Libraries

        WIL4C : C/C++, Win 3.1/95/98/NT. The "Winsock Interface Library"
                supports TCP,SMTP,POP3,TELNET,FTP, etc.
        SEE4C : C/C++, Win 3.1/95/98/NT. Email from your C/C++ application
                using the "SMTP/POP3 Email Engine for C/C++" (SEE4C),
                including MIME attachments. Also versions for Delphi
                (SEE4D), Visual Basic (SEE4VB), PowerBASIC (SEE4PB), COBOL
                (SEE4CB), Fortran (SEE4F), and Visual dBase (SEE4DB).
        FCE4C : C/C++, Win 3.1/95/98/NT. Upload & download files using FTP.









     WSC4C Users Manual                                        Page 22

