


                  Windows Standard Serial Communications

                            Library for C/C++

                                 (WSC4C)


                              USERS MANUAL



                                Version 2.1

                                June 2, 1997




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




                         Copyright (C) 1996-1997
                           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









     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 Determining UART Address & IRQ Settings.................5
           1.4 Installation............................................6
       2.0 Library Overview............................................7
           2.1 Dynamic Link Libraries..................................7
           2.2 Using the Library.......................................7
           2.3 Compiling Programs......................................7
           2.4 Using a Makefile........................................7
           2.5 Using an IDE............................................8
           2.6 Compiling WSC..........................................10
           2.7 Compiling Example Programs.............................10
       3.0 Talking to Your Modem......................................11
           3.1 Modem Standards........................................11
           3.2 Flow Control...........................................12
           3.3 Modem Initialization...................................13
       4.0 Modem I/O..................................................14
           4.1 MIO Introduction.......................................14
           4.2 MIO Function Summary...................................14
       5.0 XMODEM & YMODEM ...........................................13
           5.1 XYDRIVER Introduction..................................15
           5.2 XYDRIVER Function Summary..............................15
       6.0 Problems...................................................16
       7.0 Serial Communications......................................17
           7.1 Communications Basics..................................17
           7.2 RS232 Signals..........................................18
       8.0 Example Programs...........................................19
           8.1 SIMPLE.................................................19
           8.2 SELFTEST...............................................19
           8.3 MODEM..................................................19
           8.4 TERM...................................................19
           8.5 BCB_PGM................................................19
       9.0 Legal Issues...............................................20
           9.1 Registration...........................................21
           9.2 License................................................21
           9.3 Warranty...............................................21
      10.0 Summary....................................................22
           10.1 Revision History......................................22
           10.2 WSC Function Summary..................................22
           10.3 Further Reading.......................................23
      11.0 Other MarshallSoft Computing Products for C/C++............23
           11.1 Personal Communications Library for Windows...........23
           11.2 Personal Communications Library for C/C++.............23
           11.3 Libraries for Other Languages.........................23








     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.

      Both Win16 and Win32 library DLLs are included. The Win16 DLL is used
      with 16-bit applications running Windows 3.X or Windows 95, while the
      Win32 DLL is used with 32-bit applications running Windows 95 or
      Windows NT.

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

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

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

      The shareware and registered versions are identical except for two
      differences: (1) the shareware version displays the "shareware"
      screen, and (2) the shareware version will "time out" after 20
      minutes, limiting execution to a maximum of twenty minutes each time
      a program is run. Of course, the registered version does not display
      the shareware screen nor time out after twenty minutes.

      We apologize for the inconvenience of the shareware screen and
      time-outs, but it is necessary to encourage registration by some who
      would use the library (sometimes for years) without registering.




     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.  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 WSC4C, call us at 205-881-4630
      between 1:30 PM and 9:30 PM CST Monday through Friday. You can also
      call at other times and leave a message, and call back later for a
      reply.

      However, we can only answer questions with respect to using the WSC4C
      library.  We cannot help you program your application.

      If you are on the Internet, 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

      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 reply within 24 hours.

      The BBS is available 24 hours per day except at 2 PM Sundays for
      maintenace. All files are in standard ZIP format. The BBS will
      contain the latest shareware version of all MarshallSoft products as
      well as related files such as:

           BUGS.ZIP:  Bug report.
           NEWS.ZIP:  Latest news regarding our products.

      The MarshallSoft Computing, Inc. newsletter "Comm Talk" is published
      quarterly.  It discusses various communications problems and
      solutions using WSC4C 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.


     WSC4C 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   0x3F8    4
            COM2   0x2F8    3
            COM3   0x3E8    4
            COM4   0x2E8    3

































     WSC4C Users Manual                                        Page 5

      1.4 Installation

      (1) Before installation of WSC4C, your Windows C/C++ 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 your WSC project directory, copy the WSC archive, then
      unzip the archive. For example:

                MKDIR   WSC
                PKUNZIP WSC4C21.ZIP WSC

      (5) Use the provided install batch file (INSTALL) to install the
      library. The format is:

                INSTALL <compiler>

      where <compiler> must be "MS" for Microsoft,  "BC"  for  Borland,  or
      "WC" for Watcom. INSTALL performs the following copy operations:

      Microsoft:
        COPY WSC32M.LIB WSC32.LIB
        COPY WSC32M.DLL WSC32.DLL
        COPY MIO32M.LIB MIO32.LIB
        COPY MIO32M.DLL MIO32.DLL
        COPY XYDRIV3M.LIB XYDRIV32.LIB
        COPY XYDRIV3M.DLL XYDRIV32.DLL

      Borland:
        COPY WSC32B.LIB WSC32.LIB
        COPY WSC32B.DLL WSC32.DLL
        COPY MIO32B.LIB MIO32.LIB
        COPY MIO32B.DLL MIO32.DLL
        COPY XYDRIV3B.LIB XYDRIV32.LIB
        COPY XYDRIV3B.DLL XYDRIV32.DLL


      Watcom:
        COPY WSC32W.LIB WSC32.LIB
        COPY WSC32W.DLL WSC32.DLL
        COPY MIO32W.LIB MIO32.LIB
        COPY MIO32W.DLL MIO32.DLL
        COPY XYDRIV3W.LIB XYDRIV32.LIB
        COPY XYDRIV3W.DLL XYDRIV32.DLL









     WSC4C Users Manual                                        Page 6

      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.

      Since WSC4C is a DLL, only one copy of the WSC4C code and 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.

      2.2 Using the Library

      The WSC4C has been tested on a Gateway 2000 (25 MHz 80386-DX, Windows
      3.1), a Gateway 2000 (66 MHz 80486-DX2, Windows 3.1), a Mid-West
      Micro (150 MHz Pentium, Windows 95), and a Toshiba Satellite (100 MHz
      Pentium, Windows 95).

      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.

      We recommend that you experiment with the example programs.

      2.3 Compiling Programs

      The example programs can be compiled by using either the provided
      makefiles or creating a project file for the IDE. Separate makefiles
      are provide for Win16 and Win32.

      2.4 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 running DOS using command
      line Windows compilers.

      Makefiles are provided for Microsoft, Borland, and WATCOM command
      line compilers. Makefiles have file extensions of "_M_" 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 do not support command
      line makefiles.


     WSC4C Users Manual                                        Page 7

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

      We do not distribute IDE files in our package because (1) they are
      very large, (2) they are not always upwardly compatible with previous
      versions of a particular IDE, (3) there is no standard project file
      format between compiler manufactures, and (4) they often must be
      modified to provide the correct path names.

      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 IDEs
      from Microsoft, Borland, and Watcom. However, there are differences
      between IDE version 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.

      2.5.1 Microsoft IDE

      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 8

      2.5.2 Microsoft Developer

      Choose "File", then "New", then "Project Workspace". Select
      "Application" for "Type:" and your 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".

      2.5.3 Borland IDE

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

      2.5.4 Turbo C IDE

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

      2.5.5 Borland C Builder

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

      2.5.6 Watcom IDE

      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 9

      2.6 Compiling WSC

      Precompiled DLL's are provided on disk for all the supported
      libraries. Registered users can recompile WSC16.C and WSC32.C in
      order to create WSC16.DLL and WSC32.DLL. Makefiles are provided for
      each compiler.

      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_

      2.7 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_

















     WSC4C Users Manual                                        Page 10

      3.0 Talking to Your Modem

      A modem is used to extend the distance over which you may
      communicate. Without a modem, your RS232 cable is limited to a
      maximum of approximately 50 feet.  But with a modem, you can
      communicate literally around the world.

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




















     WSC4C Users Manual                                        Page 11

      3.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).  Similarly, 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.

      WSC4C supports both hardware and software flow control.  Refer to the
      SioFlow function in the WSC4C Reference Manual.

      NOTE: When hardware flow control is enabled (by calling SioFlow), no
      serial I/O can occur until both DSR and CTS are set by the modem.















     WSC4C Users Manual                                        Page 12

      3.3 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. 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 most 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 displays 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 modem, you should
      first reset it to factory settings by sending:

           AT&F

      NOTE: Use AT&F1 for US Robotics modems.

      Refer to the TERM program (function mioSendTo is in the file MIO.C)
      for an example of sending an initialization string to a modem.







     WSC4C Users Manual                                        Page 13

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

      For example:

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

      5.0 XMODEM & YMODEM

      5.1 XYDRIVER Introduction

      The XMODEM & YMODEM functions are implemented in XYDRIVER 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.

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



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

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

      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. See SIMPLE.C for an example.

      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.

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












     WSC4C Users Manual                                        Page 16

      7.0 Serial Communications

      7.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/WSC4C), 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.



     WSC4C Users Manual                                        Page 17

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


     WSC4C Users Manual                                        Page 18

      8.0 Example Programs

      8.1 SIMPLE

      SIMPLE is a very simple communications program using WSC4C.
      Everything that is 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.  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.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
      (such as ours) and downloading or uploading files using XMODEM or
      YMODEM. The TERM program uses MIO.DLL for modem control commands, and
      the XYDRIVER.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.

      8.5 BCB_PGM

      BCB_PGM is a Borland C Builder example program similar to SIMPLE.





     WSC4C Users Manual                                        Page 19

      9.0 Legal Issues

      9.1 Registration


      WSC4C may be registered for $75 plus $5 S&H ($10 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 (the address to which the credit card bill is
      mailed).

      Print the file INVOICE.TXT if a "Pro Forma" invoice is needed.

      If you wish to update from an older version of WSC4C, send $25 plus
      $5 S&H ($10 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, BBS, 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.


















     WSC4C Users Manual                                        Page 20

      9.2 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
      more than one computer at the same time.  The source code for the
      library (WSC16.C, WSC32.C, MIO.C, and XYDRIVER.C) is copyrighted by
      MarshallSoft Computing and may not be released in whole or in part.
      Products developed using WSC4C may be distributed without royalty.

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


















     WSC4C Users Manual                                        Page 21

      10.0 Summary

      10.1 Revision History

      Version 1.0: 9 September, 1996.

          o  The initial release of WSC4C.

      Version 2.0: 25 January, 1997.

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

      Version 2.1: 2 June, 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.

      10.2 WSC Function Summary

      Refer to the WSC4C Reference Manual (WSC4C_R.TXT) 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.  |
      |  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). |
      |  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.               |
      |  SioTxClear |  Clears the transmit buffer.                        |
      |  SioTxQue   |  Returns the number of characters in the TX queue.  |
      |  SioUnGetc  |  "Ungets" (puts back) a specified character.        |
      +-------------+-----------------------------------------------------+





     WSC4C Users Manual                                        Page 22

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

      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.

      11.0 Other MarshallSoft Computing Products

      Several shareware products are available from MarshallSoft Computing.

      11.1 The Personal Communications Library for Windows (C/C++)

      The Personal Communications Library for Windows (PCL4W) is a Windows
      based [Win16] asynchronous communications library designed for
      software developers programming in C/C++.  Unlike WSC4C, PCL4W
      interfaces to the serial port hardware directly.  PCL4W also supports
      multiport boards such as those made by DigiBoard and BOCA.

      The Personal Communications Library for Windows (PCL4W) is available
      for $75 plus $5 S&H ($10 S&H overseas).

      11.2 The Personal Communications Library for C/C++ / DOS

      PCL4C is similar to PCL4W except that it is designed for DOS.
      Includes support for both 16-bit and 32-bit protected mode.

      11.3 Libraries for Other Languages

      We have communications libraries for C/C++, Turbo Pascal, Visual
      Basic, and PowerBASIC. Check our BBS or WEB site.

       PCL4C  : C/C++, DOS [include 16-bit & 32-bit protected mode].
       PCL4P  : Turbo Pascal, DOS [includes 16-bit 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, Win NT. Uses Windows API.
       WSC4VB : Visual Basic, Win 3.1, Win 95, Win NT. Uses Windows API.
        WSC4D : Borland DELPHI, Win 3.1, Win 95, Win NT. Uses Windows API.








     WSC4C Users Manual                                        Page 23

