home *** CD-ROM | disk | FTP | other *** search
/ Chip 1999 August / Chip_1999-08_cd.bin / sharewar / wscmclib / WSC4VB_U.TXT < prev    next >
Text File  |  1999-06-02  |  43KB  |  1,142 lines
  1.  
  2.  
  3.  
  4.                   Windows Standard Serial Communications
  5.  
  6.                           Library for Visual Basic
  7.  
  8.                                  (WSC4VB)
  9.  
  10.  
  11.                                USERS MANUAL
  12.  
  13.  
  14.  
  15.                                 Version 2.4
  16.  
  17.                                 June 1, 1999
  18.  
  19.  
  20.  
  21.  
  22.                      This software is provided as-is.
  23.               There are no warranties, expressed or implied.
  24.  
  25.  
  26.  
  27.  
  28.                            Copyright (C) 1999
  29.                            All rights reserved
  30.  
  31.  
  32.  
  33.  
  34.                            MarshallSoft Computing, Inc.
  35.                            Post Office Box 4543
  36.                            Huntsville AL 35815
  37.  
  38.                            Voice : 256-881-4630
  39.                              FAX : 256-880-0925
  40.                            email : info@marshallsoft.com
  41.                              web : www.marshallsoft.com
  42.  
  43.  
  44.                                _______
  45.                           ____|__     |                (R)
  46.                        --+       |    +-------------------
  47.                          |   ____|__  |  Association of
  48.                          |  |       |_|  Shareware
  49.                          |__|   o   |    Professionals
  50.                        --+--+   |   +---------------------
  51.                             |___|___|    MEMBER
  52.  
  53.  
  54.  
  55.  
  56.       MARSHALLSOFT is a registered trademark of MarshallSoft Computing.
  57.  
  58.  
  59.  
  60.      WSC4VB Users Manual                                       Page 1
  61.  
  62.                             C O N T E N T S
  63.  
  64.  
  65.       Chapter                                                   Page
  66.  
  67.        1.0 Introduction................................................3
  68.            1.1 User Support............................................4
  69.            1.2 ASP Ombudsman...........................................4
  70.            1.3 Awards..................................................4
  71.            1.4 Installation............................................5
  72.            1.5 Uninstalling............................................5
  73.            1.6 Limitations on COM Ports................................5
  74.        2.0 Library Overview............................................6
  75.            2.1 Dynamic Link Libraries..................................6
  76.            2.2 Using the Library.......................................6
  77.            2.3 Win32 STDCALL and DECLSPEC..............................6
  78.            2.4 Using Threads...........................................6
  79.            2.5 WSC Class...............................................6
  80.        3.0 Compiling Programs..........................................7
  81.            3.1 Compiling WSC...........................................7
  82.            3.2 Compiling Example Programs..............................7
  83.            3.3 EXCEL, ACCESS, and WORD.................................7
  84.            3.4 PowerBuilder and FoxPro.................................7
  85.        4.0 Modem I/O...................................................8
  86.            4.1 MIO Introduction........................................8
  87.            4.2 MIO Function Summary....................................8
  88.        5.0 XMODEM & YMODEM ............................................9
  89.            5.1 XYDRIVER Introduction...................................9
  90.            5.2 XYDRIVER Function Summary...............................9
  91.        6.0 ASCII File Transfer........................................10
  92.        7.0 Problems...................................................11
  93.        8.0 Example Programs...........................................12
  94.            8.1 EASY...................................................12
  95.            8.2 SELFTEST...............................................12
  96.            8.3 MODEM..................................................12
  97.            8.4 TERM...................................................13
  98.            8.5 FINDER.................................................13
  99.            8.6 ATOK...................................................13
  100.        9.0 Legal Issues...............................................14
  101.            9.1 Registration...........................................14
  102.            9.2 Academic Discount......................................14
  103.            9.3 License................................................15
  104.            9.4 Warranty...............................................15
  105.       10.0 Summary....................................................16
  106.            10.1 Revision History......................................16
  107.            10.2 WSC Function Summary..................................17
  108.            10.3 Further Reading.......................................18
  109.       11.0 Other MarshallSoft Computing Products for Visual Basic.....18
  110.            11.1 Personal Communications Library for Visual Basic......18
  111.            11.2 Personal Protocol Library for Visual Basic............18
  112.            11.3 Serial Libraries for Other Languages..................18
  113.            11.4 Internet Libraries....................................19
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.      WSC4VB Users Manual                                       Page 2
  121.  
  122.       1.0 Introduction
  123.  
  124.       The Windows Standard Serial Communications Library for Visual Basic
  125.       (WSC4VB) is an asynchronous communications dynamic link library
  126.       (DLL) which uses the standard Windows serial communications API.
  127.       Since it uses the Windows API, programs using the WSC library are
  128.       fully compatible with other Window applications which also use the
  129.       Windows serial communications API.
  130.  
  131.       The WSC4VB dynamic link library (WSC32.DLL) can be called from any
  132.       WIN32 application capable of calling Windows API functions,
  133.       including those written in Delphi, Visual Basic, MS Access, MS Excel,
  134.       Fortran, COBOL, PowerBuilder, FoxPro, Power Basic Console Compiler,
  135.       dBase, etc. The library works under NT 4.0 and Windows 95/98, as well
  136.       as Windows 3.1 (Win16 only).
  137.  
  138.       Using WSC is very straight-forward. For example, to write "HELLO" to
  139.       the serial port COM1:
  140.  
  141.            Dim Text As String * 5
  142.            Dim Code As Long
  143.            Text = "HELLO"
  144.  
  145.            Code = SioReset(COM1,512,512)  'open COM1 with 512 KB buffers
  146.            Code = SioPuts(COM1,Text,6)    'write "HELLO" to COM1
  147.            Code = SioDone(COM1)           'close COM1
  148.  
  149.       Several Visual Basic example programs with full source code are included.
  150.       Refer to Chapter 8 for more details on each of the example programs.
  151.  
  152.            EASY     : A simple terminal emulator program.
  153.            SELFTEST : Performs COM port functionality testing.
  154.            MODEM    : Same as EASY but controls flow control, modem
  155.                       lines, etc.
  156.            TERM     : Terminal emulator with XMODEM, YMODEM, and ANSI
  157.                       terminal emulator support.
  158.            FINDER   : Finds a modem connected to one of the serial ports.
  159.            ATOK     : Similar to EASY but uses WSC class (WscClass.cls).
  160.  
  161.       WSC4VB contains over 25 functions. All functions return a negative
  162.       number if an error condition is detected.  For more details, consult
  163.       the WSC4VB Reference Manual (WSC4VB_R.TXT) and the RS232/485
  164.       Serial Communications Users Manual (ASYNC.TXT).
  165.  
  166.       Our goal is to provide a robust serial communications library that
  167.       you and your customers can depend upon. Contact us if you have any
  168.       questions.
  169.  
  170.       The shareware and registered versions are identical except that the
  171.       shareware version displays the "shareware" screen when first
  172.       starting, after 20 minutes of run time, and every 10 minutes after
  173.       that. The registered version also includes source code.
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.      WSC4VB Users Manual                                       Page 3
  181.  
  182.       1.1 User Support
  183.  
  184.       We want you to be successful in developing your applications using
  185.       WSC4VB! We depend upon our customers to let us know what they need in
  186.       a communications library. If you have any suggestions or comments,
  187.       please let us know.
  188.  
  189.       If you are having a problem using WSC4VB, email us at
  190.  
  191.          support@marshallsoft.com
  192.  
  193.       You can also reach us at 256-881-4630 between 7:00 AM and 7:00 PM CST
  194.       Monday through Friday. You can also often get us on the weekend.
  195.  
  196.       The latest versions of our products are available on our web site at
  197.  
  198.          http://www.marshallsoft.com
  199.  
  200.       and on our anonymous FTP site at
  201.  
  202.          ftp://ftp.marshallsoft.com/marshallsoft
  203.  
  204.       The MarshallSoft Computing newsletter "Comm Talk" is published
  205.       quarterly on our web site.  It discusses various communications
  206.       problems and solutions using our products as well as related
  207.       information.
  208.  
  209.       1.2 ASP Ombudsman
  210.  
  211.       MarshallSoft Computing, Inc. is a member of the Association of
  212.       Shareware Professionals (ASP).  ASP wants to make sure that the
  213.       shareware principle works for you.  If you are unable to resolve a
  214.       shareware-related problem with an ASP member by contacting the member
  215.       directly, ASP may be able to help. The ASP Ombudsman can help you
  216.       resolve a dispute or problem with an ASP member, but does not provide
  217.       technical support for members' products. Please write to the ASP
  218.       Ombudsman at 157-F Love Ave., Greenwood, IN 26142 USA, FAX
  219.       317-888-2195, or send email to omb@asp-shareware.org.
  220.  
  221.       1.3 Awards
  222.  
  223.       WSC4VB has been rated 5 stars by ZDNET, which is their highest
  224.       rating.
  225.  
  226.       Our other "Windows Standard Serial Communications Libraries" (for
  227.       C/C++ and Delphi) are one of the more popular downloads in the
  228.       shareware libaries category.
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.      WSC4VB Users Manual                                       Page 4
  241.  
  242.       1.4 Installation
  243.  
  244.       (1) Before installation of WSC4VB, your Visual Basic compiler should
  245.       already be installed on your system and tested. Note that Visual
  246.       Basic 4.0 (or up) is required in order to create Win32 programs.
  247.  
  248.       (2) Create your WSC project directory, copy the WSC archive, then
  249.       unzip the archive. For example:
  250.  
  251.            MKDIR   WSC
  252.            PKUNZIP WSC4VB24.ZIP WSC    'registered users unzip WSC4VB.ZIP
  253.  
  254.       Note:  PKZIP for Windows and WINZIP can also be used to unzip.
  255.  
  256.       (3) Run the install program INSTALL.BAT which will copy the correct
  257.       files for your installation (Visual Basic 3.0 or Visual Basic 4.0+).
  258.  
  259.       If you are using Visual Basic 3 or 16-bit VB 4, then type:
  260.  
  261.            INSTALL 16               'for Windows 95/98/NT or Windows 3.1
  262.  
  263.       If you are using 32-bit Visual Basic 4 (or above), then type:
  264.  
  265.            INSTALL 32               'for Windows 95/98/NT
  266.  
  267.       The install program creates WSC4VB.BAS from either WSC16.BAS or
  268.       WSC32.BAS, and copies the proper DLLs. This way, the source code for
  269.       the example programs is identical for both Visual Basic 3 (Win16) and
  270.       Visual Basic 4 / Visual Basic 5 (Win32).
  271.  
  272.       INSTALL will copy all DLLs to the C:\WINDOWS directory (or C:\WINNT
  273.       if running Windows NT), where Visual Basic can find them.
  274.  
  275.       1.5 Uninstalling
  276.  
  277.       Uninstalling WSC4VB is very easy. WSC4VB does NOT modify the
  278.       registry. First, delete the WSC4VB project directory created when
  279.       installing WSC4VB. Second, delete WSC16.DLL and WSC32.DLL from your
  280.       Windows directory, typically C:\WINDOWS for Windows 95/98 or
  281.       C:\WINNT for Windows NT. Thats it!
  282.  
  283.       Running the UINSTALL.BAT batch file will also delete WSC16.DLL and
  284.       WSC32.DLL as described above.
  285.  
  286.       1.6 Limitations on COM Ports
  287.  
  288.       The 32-bit version of WSC4VB (WSC32.DLL) can use any port from COM1
  289.       to COM20, provided that the port is known to Windows 95/98/NT and
  290.       there is physical hardware present. More ports can easily be added by
  291.       recompiling WSC32.C.
  292.  
  293.       The UART FIFO level can only be set from the Windows Control Panel.
  294.       The recommended receive side trigger level is 8 or 14 for 16550
  295.       UARTs. For more information on UARTS, see the RS232/485 Serial
  296.       Communications Users Manual (ASYNC.TXT).
  297.  
  298.  
  299.  
  300.      WSC4VB Users Manual                                       Page 5
  301.  
  302.       2.0 Library Overview
  303.  
  304.       2.1 Dynamic Link Libraries
  305.  
  306.       WSC4VB uses a Win32 dynamic link library (WSC32.DLL). A DLL is
  307.       characterized by the fact that it need not be loaded until required
  308.       by an application program and that only one copy of the DLL is
  309.       necessary regardless of the number of application programs that use
  310.       it. Contrast this to the traditional static library which is bound to
  311.       each and every application that uses it at link time.
  312.  
  313.       An important advantage that DLLs have over other "popular" library
  314.       formats such as VBX or OCX is that DLLs are callable by all Windows
  315.       applications. Since DLLs are the building blocks of the Windows
  316.       Operations System, they will not be replaced by a "newer technology".
  317.  
  318.       2.2 Using the Library
  319.  
  320.       The WSC4VB has been tested on multiple computers running Windows 3.1,
  321.       Windows 95/98, and Windows NT 4.0.
  322.  
  323.       Please examine the WSC32.BAS file. Note that COM1 is defined as port
  324.       zero, not port one.  The user must assume the responsibility for
  325.       passing the correct information when calling WSC4VB functions.
  326.  
  327.       2.3 Win32 STDCALL and DECLSPEC
  328.  
  329.       WSC32 is written in ANSI C and is compiled using the _stdcall and
  330.       _declspec keywords. This means that WSC4VB uses the same calling
  331.       conventions and file naming conventions as the Win32 API. In
  332.       particular, function names are NOT decorated. There is no leading
  333.       underscore nor trailing "@size" added to function names.
  334.  
  335.       The WSC32.DLL functions may be called by any Windows application
  336.       program capable of calling the Windows API provided the proper
  337.       declaration file is used.
  338.  
  339.       2.4 Using Threads
  340.  
  341.       WSC4VB is thread safe, and can be used from any Windows application
  342.       capable of using threads.
  343.  
  344.       2.5 WSC Class
  345.  
  346.       The WSC class "wscClass" (wscClass.cls) is a Visual Basic class
  347.       wrapper for making calls to WSC32.DLL. The class name for each
  348.       function is the same as the DLL function, except the leading "wsc" is
  349.       replaced by "f".
  350.  
  351.       Those functions that return strings do so by use of the "String
  352.       Result" property.  Instantiate wscClass as any other class in VB:
  353.  
  354.          Dim X As New wscClass
  355.  
  356.       Refer to the ATOK project for an example of use. Use of wscClass is
  357.       limited to Visual Basic 5.0 and above.
  358.  
  359.  
  360.      WSC4VB Users Manual                                       Page 6
  361.  
  362.       3.0 Compiling Programs
  363.  
  364.       Each of the example programs should be compiled and run. Before
  365.       beginning, be sure to run INSTALL that will copy the proper Win16 (or
  366.       Win32) files.
  367.  
  368.       Refer to Section 8.0 "Example Programs" for more information on the
  369.       example programs.
  370.  
  371.       3.1 Compiling WSC
  372.  
  373.       WSC32.DLL is written in standard ANSI C (WSC32.C), and has been
  374.       compiled using Microsoft Visual C/C++ with the STDCALL and DECLSPEC
  375.       compiler keywords. Source code for the WSC library is provided in the
  376.       registered version only.
  377.  
  378.       WSC32.C may also be compiled using Borland C/C++ or Watcom C/C++
  379.       compilers. If you recompile WSC32.C using Borland or Watcom
  380.       compilers, the resulting WSC32.DLL can only be used by applications
  381.       compiled with the same compiler, unless the "_stdcall" and
  382.       "_declspec" keywords are specified.
  383.  
  384.       For more information on the C/C++ version of WSC, download the latest
  385.       version of WSC4C from our web site at www.marshallsoft.com.
  386.  
  387.       3.2 Compiling Example Programs
  388.  
  389.       Visual Basic MAK files are provided with all example programs. All
  390.       example source code is saved in Visual Basic 3.0 format so that it
  391.       can be read by all versions of Visual Basic.
  392.  
  393.       3.3 EXCEL, ACCESS, and WORD
  394.  
  395.       WSC can be used with Microsoft VBA (Visual Basic for Applications)
  396.       applications such as EXCEL, ACCESS, and WORD. Note that WSC16.DLL
  397.       must be used for 16-bit applications, even if running under Windows
  398.       95/98 or NT. See EXCEL.TXT, ACCESS.TXT, and WORD.TXT for more
  399.       information.
  400.  
  401.       3.4 PowerBuilder and FoxPro
  402.  
  403.       WSC can also be used with Power Builder and FoxPro applications.
  404.  
  405.       WSC.PBI : Power Builder declaration file.
  406.       WSC.PRG : FoxPro declaration file.
  407.  
  408.       See PBUILDER.TXT and FOXPRO.TXT for more information.
  409.  
  410.  
  411.  
  412.  
  413.  
  414.  
  415.  
  416.  
  417.  
  418.  
  419.  
  420.      WSC4VB Users Manual                                       Page 7
  421.  
  422.       4.0 MODEM I/O (MIO)
  423.  
  424.       4.1 MIO Introduction
  425.  
  426.       The file MIO32.BAS contains prototypes for using the Modem I/O DLL.
  427.       These functions ease communicating with modems using AT commands.
  428.  
  429.       The MIO functions are broken down into parts called states, and
  430.       control is returned to Windows between executing each state.
  431.  
  432.       For example:
  433.  
  434.       (1) Send the string to the MIO driver by executing:
  435.  
  436.       Code = mioSendTo(Port,100,"!ATDT1,256,880,9748")
  437.  
  438.       The '!' characters are converted to carriage returns.  The text
  439.       string is copied into the driver's data area.
  440.  
  441.       (2) Call mioDriver (typically based on a timer) until MIO_IDLE is
  442.       returned. Each time mioDriver is called, it will send another
  443.       character to the modem provided the required delay (since the
  444.       previous character was sent) has passed.  If the delay has not
  445.       passed, the driver simply returns MIO_RUNNING, but without actually
  446.       sending a character to the modem.  Once all characters have been
  447.       sent, mioDriver will return MIO_IDLE, indicating it is done and is
  448.       ready to accept another function.
  449.  
  450.       mioDriver will return MIO_RUNNING if it is still processing. Any
  451.       other return value indicates that it is still processing and the
  452.       returned value is a character from the modem that can be displayed if
  453.       wanted.
  454.  
  455.       (3) Once mioDriver returns MIO_IDLE, call mioResult to get the
  456.       result of the mioSendTo call.
  457.  
  458.       4.2 MIO Function Summary
  459.  
  460.        mioDriver : Drives the execution of mioSendTo, mioWaitFor, or
  461.                    mioQuiet once they have been started.
  462.         mioBreak : Forces the MIO driver to IDLE state.
  463.        mioSendTo : Sends a string (including control chars) to the modem.
  464.       mioWaitFor : Waits  for a particular string from the modem, passing
  465.                    all else through.
  466.         mioQuiet : Waits for continuous quiet of a specified duration.
  467.         mioBreak : Breaks further modem I/O activity.
  468.  
  469.       Refer to the WSC4VB Reference Manual (WSC4VB_R.TXT) for more
  470.       detailed information.
  471.  
  472.  
  473.  
  474.  
  475.  
  476.  
  477.  
  478.  
  479.  
  480.      WSC4VB Users Manual                                       Page 8
  481.  
  482.       5.0 XMODEM & YMODEM
  483.  
  484.  
  485.       5.1 XYDRIVER Introduction
  486.  
  487.       The XMODEM & YMODEM functions are implemented in XYDRV as a DLL
  488.       (Dynamic Link Library), and are state driven like the Modem I/O
  489.       functions described in the previous section. The TERM program
  490.       provides an example of using XYDRV.
  491.  
  492.       Files can be sent and received using XMODEM, XMODEM/CRC, XMODEM/1K,
  493.       and YMODEM. The basic procedure used to run XMODEM or YMODEM is as
  494.       follows:
  495.  
  496.       (1) Call xyAcquire() immediately after calling SioReset().
  497.  
  498.       (2) To receive a file, call xyStartRx(), then call xyDriver()
  499.           repeatedly until XY_IDLE is returned.
  500.  
  501.       (3) To send a file, call xyStartTx(), then call xyDriver() repeatedly
  502.           until XY_IDLE is returned.
  503.  
  504.       (4) Call xyRelease() immediately before calling SioDone().
  505.  
  506.       Refer to the TERM program for examples of calling the XYDRV
  507.       functions.
  508.  
  509.       5.2 XYDRIVER Function Summary
  510.  
  511.              xyAbort : Abort driver at any time.
  512.            xyAcquire : Acquire a port.
  513.              xyDebug : Set the debug level.
  514.             xyDriver : Executes the next state or states.
  515.         xyGetMessage : Get the next debug message.
  516.       xyGetParameter : Get a driver parameter.
  517.        xyGetFileName : Get name of file being sent or received.
  518.            xyRelease : Release a port.
  519.       xySetParameter : Set a driver parameter.
  520.            xyStartRx : Start a receive.
  521.            xyStartTx : Start a transmit.
  522.  
  523.       Refer to the WSC4VB Reference Manual (WSC4VB_R.TXT) for more detailed
  524.       information.
  525.  
  526.  
  527.  
  528.  
  529.  
  530.  
  531.  
  532.  
  533.  
  534.  
  535.  
  536.  
  537.  
  538.  
  539.  
  540.      WSC4VB Users Manual                                       Page 9
  541.  
  542.       6.0 ASCII File Transfer
  543.  
  544.       6.1 ASCII Protocol
  545.  
  546.       The "ASCII Protocol" is not a defined protocol, but rather it is a
  547.       loose set of conventions developed over a period of years by BBS
  548.       operators. Because XON/OFF flow control is used, only ASCII text can
  549.       be transferred. The ASCII protocol is implemented as a DLL and is
  550.       state driven like the MIO and XYDRIVER code.
  551.  
  552.       (1) Call ascInit(Port,RxQueSize,xFlag) to do initialization, where
  553.  
  554.             Port = The connected port (COM1, COM2, etc).
  555.        RxQueSize = The size of the Rx Queue as passed to SioReset().
  556.            xFlag = 1 if this module will perform XON/XOFF flow control.
  557.                    Set to FALSE if flow control is being performed by the
  558.                    WSC code (you called SioFlow()).
  559.  
  560.       (2) To send an ASCII file, call
  561.  
  562.       ascStartTx(FileName,CharPace,TermChar,EchoFlag), where
  563.          FileName = The path & name of the file to send.
  564.          CharPace = The delay in milliseconds between characters.
  565.          TermChar = The termination character to send after the file
  566.                     has been sent. If none, use 0x00.
  567.          EchoFlag = 1 if screen echo is desired.
  568.  
  569.       Then call ascDriver() until it returns IDLE (1).
  570.  
  571.       (3) To receive an ASCII file, call
  572.  
  573.       ascStartRx(FileName,TermChar,FirstWait,CharWait,EchoFlag), where
  574.          FileName = The path & name of the file to send.
  575.          TermChar = The termination character. If none, use 0x00.
  576.         FirstWait = The maximum number of seconds to wait for the
  577.                     first incoming character.
  578.          CharWait = The maximum number of seconds after which it is
  579.                     assumed that the other side has completed sending.
  580.                     If unsure, set this to 3 seconds.
  581.          EchoFlag = 1 if screen echo is desired.
  582.  
  583.       Then call ascDriver() until it returns IDLE (1).
  584.  
  585.       6.2 ASCII Function Summary
  586.  
  587.              ascAbort : Abort driver at any time.
  588.             ascDriver : Executes the next state or states.
  589.         ascGetMessage : Get the next debug message.
  590.       ascGetParameter : Get a driver parameter.
  591.        ascGetFileName : Get name of file being sent or received.
  592.               ascInit : Initialize the driver.
  593.            ascStartRx : Start a receive.
  594.            ascStartTx : Start a transmit.
  595.  
  596.  
  597.  
  598.  
  599.  
  600.      WSC4VB Users Manual                                       Page 10
  601.  
  602.       7.0 Problems
  603.  
  604.       If you cannot get your application to run properly, first compile and
  605.       run the example program EASY.BAS. Test EASY by connecting two
  606.       computers with a null modem cable or by connecting a modem to a
  607.       serial port.
  608.  
  609.       Once EASY runs, compile and run the SELFTEST program.  This program
  610.       will test your serial ports' functionality.
  611.  
  612.       If your application does not run but EASY and SELFTEST run correctly,
  613.       then you have most likely made a programming mistake in your
  614.       application. MarshallSoft Computing cannot debug your application,
  615.       especially over the telephone!  However, consider each of the
  616.       following when searching for an error in your application.
  617.  
  618.       1.  Have you included the file WSC32.BAS in your application ?
  619.  
  620.       2.  Are your receive and transmit buffers large enough ? Use a buffer
  621.       size that is twice the size of the largest expected block.
  622.  
  623.       3.  Have you selected too high a baud rate? Windows can multitask
  624.       many tasks at once. You may have to lower your baud rate (or get
  625.       16550 UARTS).
  626.  
  627.       4.  Did SioReset return a zero value ?  If not, then you must call
  628.       SioReset again. See EASY.BAS for an example.
  629.  
  630.       5.  Did you send the proper initialization string to your modem ?
  631.       Did you set DTR and RTS? (you should).
  632.  
  633.       7. Are you trying to link a 32-bit DLL to a 16-bit program (or vice
  634.       versa)? The typical error message refers to a "corrupted" DLL file.
  635.  
  636.       Keep Win16 & Win32 development separate.
  637.  
  638.       8. If you are using the registered version of WSC and you are still
  639.       getting the shareware screen, make sure you have deleted all copies
  640.       of the WSC shareware DLL's in the Windows search path.
  641.  
  642.       9. If you do not have the WSC4VB.BAS file, you have not run
  643.       INSTALL.BAT.
  644.  
  645.       We recommend the following steps if you believe that you have
  646.       discovered a bug in the library: (1) Create the smallest, simplest
  647.       test program possible that demonstrates the problem.  (2) Document
  648.       your exact machine configuration and what error the test program
  649.       demonstrates.  (3) Email us the example source.
  650.  
  651.       If the problem can be solved with an easy work-around, we will
  652.       publish the work-around.  If the problem requires a modification to
  653.       the library, we will make the change and make the modified library
  654.       available to our customers without charge.
  655.  
  656.  
  657.  
  658.  
  659.  
  660.      WSC4VB Users Manual                                       Page 11
  661.  
  662.       8.0 Example Programs
  663.  
  664.       The example programs are designed to demonstrate the various
  665.       capabilities of WSC4VB. The best way to become familiar with WSC4VB
  666.       is to study and run the example programs.
  667.  
  668.       8.1 EASY
  669.  
  670.       EASY is a very simple communications program using WSC4VB. Everything
  671.       that is typed on the keyboard is sent to the serial port, and
  672.       everthing incoming from the serial port is displayed on the screen.
  673.  
  674.       The easiest way to test EASY is to connect to a modem.  Typing 'AT'
  675.       should result in an 'OK' being displayed.
  676.  
  677.       A null-modem cable can also be used to connect two computers together
  678.       with their serial ports. Run EASY on both machines. Whatever is typed
  679.       on one machine will be displayed on the other.
  680.  
  681.       8.2 SELFTEST
  682.  
  683.       SELFTEST performs a serial port I/O functionality test. Either a pair
  684.       of ports on the same computer (using a null modem cable) or a single
  685.       port (using a loopback adapter) can be tested.
  686.  
  687.       Refer to LOOPBACK.TXT for an explanation of how to make a loopback
  688.       adapter (without tools!).
  689.  
  690.       8.3 MODEM
  691.  
  692.       MODEM is similiar to EASY, but with enhanced capability. It can set
  693.       flow control (hardware, software, or none), DTR line (set or clear),
  694.       RTS line (set or clear), display the transmit & receive queue sizes,
  695.       detect a break signal, detect changes in DSR and CTS, as well as
  696.       check for various line errors (parity error, framing error, data
  697.       overrun, receive queue overflow, and transmit buffer full).
  698.  
  699.  
  700.  
  701.  
  702.  
  703.  
  704.  
  705.  
  706.  
  707.  
  708.  
  709.  
  710.  
  711.  
  712.  
  713.  
  714.  
  715.  
  716.  
  717.  
  718.  
  719.  
  720.      WSC4VB Users Manual                                       Page 12
  721.  
  722.       8.4 TERM
  723.  
  724.       TERM is a simple terminal emulator suitable for calling up a BBS and
  725.       downloading or uploading files using XMODEM or YMODEM. The TERM
  726.       program uses MIO.DLL for modem control commands, ASDRV.DLL for the
  727.       ASCII protocol, and the XYDRV.DLL for XMODEM & YMODEM protocol.
  728.  
  729.       Selecting 'Dial' from the menu bar will result in a pop-up dialog
  730.       requesting the phone number to dial. Once entered, the number is
  731.       dialed, and the program will wait for up to 60 seconds for the
  732.       'CONNECT' string from the modem.  This wait can be terminated at any
  733.       time by choosing 'BREAK' on the menu bar.
  734.  
  735.       Once logged on, files can be uploaded or downloaded by selecting
  736.       'Send' or 'Receive' from the menu bar. To abort a file transfer,
  737.       choose 'BREAK' from the menu bar then type a series of Ctrl-X (^X)
  738.       characters from the keyboard.
  739.  
  740.       8.5 FINDER
  741.  
  742.       The FINDER program searches for a connected modem. Your modem must be
  743.       connected to one of COM1, COM2, COM3, or COM4, and must be turned on.
  744.  
  745.       FINDER takes no arguments. After connecting your modem to one of your
  746.       serial ports, type
  747.  
  748.          FINDER
  749.  
  750.       8.6 ATOK
  751.  
  752.       The ATOK program demonstrates the use of the Visual Basic class
  753.       "wscClass.cls". The program transmits an "AT" to the serial port, and
  754.       receives the response. If the serial port is connected to a modem,
  755.       sending an "AT" should result in "OK" being received and displayed.
  756.  
  757.  
  758.  
  759.  
  760.  
  761.  
  762.  
  763.  
  764.  
  765.  
  766.  
  767.  
  768.  
  769.  
  770.  
  771.  
  772.  
  773.  
  774.  
  775.  
  776.  
  777.  
  778.  
  779.  
  780.      WSC4VB Users Manual                                       Page 13
  781.  
  782.       9.0 Legal Issues
  783.  
  784.       9.1 Registration
  785.  
  786.       WSC4VB may be registered for $85 plus $7 S&H ($12 outside of North
  787.       America).
  788.  
  789.       To order, contact us as shown on the title page of this manual. All
  790.       prices are guaranteed for one year from the release date.
  791.  
  792.       Multiple copy discounts (3 or more) and site licenses are available.
  793.       Please call for details.
  794.  
  795.       We accept American Express, VISA, MasterCard, Discover, checks in US
  796.       dollars drawn on a US bank, International Postal Money Orders,
  797.       purchase orders (POs) from recognized US schools and companies listed
  798.       in Dun & Bradstreet, and COD (street address and phone number
  799.       required) within the USA (plus a $5 COD charge).
  800.  
  801.       For credit card orders, be sure to include the account number, the
  802.       expiration date, the exact name on the card, and the complete card
  803.       billing address (address to which the credit card bill is mailed).
  804.       Note that all ordering information collected, including email
  805.       addresses, is kept strictly confidential.
  806.  
  807.       Print the file INVOICE.TXT if a "Pro Forma" invoice is needed.
  808.  
  809.       If you wish to update from an older version of WSC4VB, updates are
  810.       $30 plus $7 S&H ($12 S&H outside of North America). The registered
  811.       package includes:
  812.  
  813.            o  Win16 / Win32 WSC4VB Libraries w/o shareware screens.
  814.            o  Win16 / Win32 source code for WSC, MIO, and XYDRIVER.
  815.            o  Printed Users Manual, Reference Manual, and RS232 Manuals.
  816.            o  Telephone and email support for one year.
  817.  
  818.       The registered user will receive the latest version of WSC4VB shipped
  819.       by US second day priority mail (packet airmail overseas).  A 3.5"
  820.       HD diskette is provided.
  821.  
  822.       9.2 Academic Discount
  823.  
  824.       We offer an "academic price" of 40% off the normal price for prepaid
  825.       email orders to faculty and students currently enrolled in any
  826.       accredited high school, college, or university. To qualify for the
  827.       discount, your school must have a web site and you must have an email
  828.       address at your school.
  829.  
  830.       When ordering, ask for the "academic discount", or enter "student at"
  831.       (or "faculty at") and your schools web site address (URL) in the
  832.       comments field of the order form on our web site order page.
  833.  
  834.       This offer is not retroactive and cannot be used with any other
  835.       discount. Products bought with academic pricing can not be used for
  836.       any commercial purpose.
  837.  
  838.  
  839.  
  840.      WSC4VB Users Manual                                       Page 14
  841.  
  842.       9.3 License
  843.  
  844.       MarshallSoft Computing, Inc. grants the registered user of WSC4VB the
  845.       right to use one copy of the WSC4VB library (in object form) on a
  846.       single computer in the development of any software product (other
  847.       than libraries such as WSC4VB). The user may not use the library on
  848.       more than one computer at the same time.  The source code for the
  849.       library (WSC16.C, WSC32.C, MIO.C, XYDRV.C, ASDRV.C) is copyrighted by
  850.       MarshallSoft Computing and may not be released in whole or in part.
  851.       The registered DLLs may be distributed (without royalty) in object
  852.       form only, as part of the user's compiled application.  The
  853.       registered DLL's may NOT be distributed as part of any software
  854.       development system (compiler or interpreter) without our express
  855.       written permission.
  856.  
  857.       9.4 Warranty
  858.  
  859.       MARSHALLSOFT COMPUTING, INC.  DISCLAIMS ALL WARRANTIES RELATING TO
  860.       THIS SOFTWARE, WHETHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT
  861.       LIMITED TO ANY IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  862.       A PARTICULAR PURPOSE, AND ALL SUCH WARRANTIES ARE EXPRESSLY AND
  863.       SPECIFICALLY DISCLAIMED. NEITHER MARSHALLSOFT COMPUTING, INC.  NOR
  864.       ANYONE ELSE WHO HAS BEEN INVOLVED IN THE CREATION, PRODUCTION, OR
  865.       DELIVERY OF THIS SOFTWARE SHALL BE LIABLE FOR ANY INDIRECT,
  866.       CONSEQUENTIAL, OR INCIDENTAL DAMAGES ARISING OUT OF THE USE OR
  867.       INABILITY TO USE SUCH SOFTWARE EVEN IF MARSHALLSOFT COMPUTING, INC.
  868.       HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES OR CLAIMS. IN NO
  869.       EVENT SHALL MARSHALLSOFT COMPUTING, INC.'S LIABILITY FOR ANY SUCH
  870.       DAMAGES EVER EXCEED THE PRICE PAID FOR THE LICENSE TO USE THE
  871.       SOFTWARE, REGARDLESS OF THE FORM OF THE CLAIM. THE PERSON USING THE
  872.       SOFTWARE BEARS ALL RISK AS TO THE QUALITY AND PERFORMANCE OF THE
  873.       SOFTWARE.
  874.  
  875.       Some states do not allow the exclusion of the limit of liability for
  876.       consequential or incidental damages, so the above limitation may not
  877.       apply to you.
  878.  
  879.       This agreement shall be governed by the laws of the State of Alabama
  880.       and shall inure to the benefit of MarshallSoft Computing, Inc.  and
  881.       any successors, administrators, heirs and assigns.  Any action or
  882.       proceeding brought by either party against the other arising out of
  883.       or related to this agreement shall be brought only in a STATE or
  884.       FEDERAL COURT of competent jurisdiction located in Madison County,
  885.       Alabama. The parties hereby consent to in personam jurisdiction of
  886.       said courts.
  887.  
  888.  
  889.  
  890.  
  891.  
  892.  
  893.  
  894.  
  895.  
  896.  
  897.  
  898.  
  899.  
  900.      WSC4VB Users Manual                                       Page 15
  901.  
  902.       10.0 Summary
  903.  
  904.       10.1 Revision History
  905.  
  906.  
  907.       Version 2.0: February 17, 1997.
  908.  
  909.           o  Includes Win16 and Win32 libraries.
  910.           o  Added XMODEM & YMODEM DLL (XYDRV.DLL).
  911.           o  Added TERM example program.
  912.  
  913.       Version 2.1: June 9, 1997.
  914.  
  915.           o  Screen display uses MEMO class.
  916.           o  WIN32 version can display error text from Win32 Windows.
  917.           o  Added FIND example program.
  918.           o  Added SioRead function.
  919.           o  SioInfo can return seconds to expiration [SHAREWARE].
  920.  
  921.       Version 2.2: November 1, 1997.
  922.  
  923.           o  XYDRV code fixes bugs.
  924.           o  Added xyGetFileName function to XYDRV.
  925.           o  Supports up to 16 ports.
  926.           o  WSC4VB runs under Windows NT.
  927.           o  Added ASCII protocol (ASDRV).
  928.  
  929.       Version 2.3: August 14, 1998
  930.  
  931.           o  Improvements to XYDRIVER (XMODEM and YMODEM).
  932.           o  SioTimer function added.
  933.           o  SioBaud and SioParms can be called before SioReset.
  934.           o  Declaration files for Power Builder added.
  935.  
  936.       Version 2.4: June 1, 1999
  937.  
  938.           o  Improvements made to XYDRIVER (XMODEM and YMODEM).
  939.           o  Added SioEvent function (Win32 only).
  940.           o  WSC Class added (VB 5.0 & up)
  941.           o  Added ATOK example program (VB 5.0 & up).
  942.  
  943.  
  944.  
  945.  
  946.  
  947.  
  948.  
  949.  
  950.  
  951.  
  952.  
  953.  
  954.  
  955.  
  956.  
  957.  
  958.  
  959.  
  960.      WSC4VB Users Manual                                       Page 16
  961.  
  962.       10.2 WSC Function Summary
  963.  
  964.       Refer to the WSC4VB Reference Manual (WSC4VB_R.TXT) for detailed
  965.       information.
  966.  
  967.       Refer to the RS232/485 Serial Communications Users Manual
  968.       (ASYNC.TXT) for technical information on UARTs, modems, and other
  969.       RS232/485 issues.
  970.  
  971.       A one line summary of each function follows:
  972.  
  973.       +-------------+-----------------------------------------------------+
  974.       | SioBaud     |  Sets the baud rate of the selected port.           |
  975.       | SioBrkSig   |  Asserts, cancels, or detects BREAK signal.         |
  976.       | SioCTS      |  Reads the Clear to Send (CTS) modem status bit.    |
  977.       | SioDCD      |  Reads the Data Carrier Detect (DCD) modem status.  |
  978.       | SioDone     |  Terminates further serial processing.              |
  979.       | SioDSR      |  Reads the Data Set Ready (DSR) modem status bit.   |
  980.       | SioDTR      |  Set, clear, or read the Data Terminal Ready (DTR). |
  981.       | SioEvent    |  Efficiently waits for specified serial event.      |
  982.       | SioFlow     |  Enables / disables hardware flow control.          |
  983.       | SioGetc     |  Reads the next character from the serial line.     |
  984.       | SioGets     |  Receives a string of characters.                   |
  985.       | SioInfo     |  Returns information such as library version.       |
  986.       | SioParms    |  Sets parity, stop bits, and word length.           |
  987.       | SioPutc     |  Transmit a character over a serial line.           |
  988.       | SioPuts     |  Transmits a string of characters.                  |
  989.       | SioRead     |  Reads any UART register.                           |
  990.       | SioReset    |  Initialize a serial port for processing.           |
  991.       | SioRI       |  Reads the Ring Indicator (RI) modem status bit.    |
  992.       | SioRTS      |  Sets, clears, or reads the Request to Send (RTS).  |
  993.       | SioRxClear  |  Clears the receive buffer.                         |
  994.       | SioRxQue    |  Returns the number of characters in the RX queue.  |
  995.       | SioStatus   |  Returns the serial port line status.               |
  996.       | SioTimer    |  Returns the system times in milliseconds.          |
  997.       | SioTxClear  |  Clears the transmit buffer.                        |
  998.       | SioTxQue    |  Returns the number of characters in the TX queue.  |
  999.       | SioUnGetc   |  "Ungets" (puts back) a specified character.        |
  1000.       | SioWinError |  Returns Win32 error message as text.               |
  1001.       +-------------+-----------------------------------------------------+
  1002.  
  1003.  
  1004.  
  1005.  
  1006.  
  1007.  
  1008.  
  1009.  
  1010.  
  1011.  
  1012.  
  1013.  
  1014.  
  1015.  
  1016.  
  1017.  
  1018.  
  1019.  
  1020.      WSC4VB Users Manual                                       Page 17
  1021.  
  1022.       10.3 Further Reading
  1023.  
  1024.       The best way to learn about serial communications is to read a good
  1025.       book on the subject. Several good texts are available.  Two that I
  1026.       like are:
  1027.  
  1028.       (1) C Programmer's Guide to Serial Communications by Joe Campbell
  1029.       (SAMS) (2) Mastering Serial Communications by Peter Gofton (SYBEX).
  1030.  
  1031.       Don't forget to read over the RS232 Users Manual (RS232.TXT). For
  1032.       more detailed information on XMODEM, YMODEM, and ZMODEM, download
  1033.       PPL4VB (see 11.2 below).
  1034.  
  1035.       11.0 Other MarshallSoft Computing Products for Visual Basic
  1036.  
  1037.       Several shareware products are available from MarshallSoft Computing.
  1038.  
  1039.       11.1 The Personal Communications Library for Visual Basic / DOS
  1040.  
  1041.       Personal Comm Library for Visual Basic. (PCL4VB62.ZIP), Jan 99, Ver
  1042.       6.2, [ASP]. Supports COM1 thru COM20 to 115200, 4 plus ports
  1043.       concurrently, many dumb multiport boards, 16550, 16650, 16750 UARTs,
  1044.       interrupt driven, RTS/CTS flow control, any UART address and IRQ.
  1045.       Requires VBDOS compiler. $85 + S&H.
  1046.  
  1047.       11.2 The Personal Protocol Library for Visual Basic / DOS
  1048.  
  1049.       Personal Protocol Library for Visual Basic (PPL4VB20.ZIP), April 95,
  1050.       Ver 2.0, [ASP]. PPL4PB is a protocol library supporting ASCII,
  1051.       XMODEM, XMODEM-CRC, XMODEM-1K, YMODEM, YMODEM-G, and ZMODEM
  1052.       protocols. Requires the Personal Communications Library for VBDOS
  1053.       (PCL4VB). $40.
  1054.  
  1055.       11.3 Serial Libraries for Other Languages
  1056.  
  1057.       We have communications libraries for C/C++, Turbo Pascal, Visual
  1058.       Basic, and Power Basic. All PCL libraries support the 8250, 16450,
  1059.       16550, 16650, and 16750 UARTs. Check our WEB site.
  1060.  
  1061.         PCL4C : C/C++, DOS (includes 16-bit protected mode).
  1062.         PCL4P : Turbo Pascal, DOS (includes 16-bit protected mode).
  1063.        PCL4VB : Visual Basic, DOS (VBDOS).
  1064.        PCL4PB : Power Basic, DOS.
  1065.  
  1066.         PCL4W : C/C++, Windows 3.1 & Win 95/98, talks to hardware directly.
  1067.        PCLVBW : Visual Basic, Win 3.1 & Win 95/98, talks to hardware directly.
  1068.  
  1069.         WSC4C : C/C++, Win 3.1/95/98/NT. Uses Windows API.
  1070.        WSC4VB : Visual Basic, Win 3.1/95/98/NT. Uses Windows API.
  1071.         WSC4D : Borland Delphi, Win 3.1/95/98/NT. Uses Windows API.
  1072.        WSC4PB : Power Basic Console Compiler, Win 95/98/NT. Uses Win API.
  1073.  
  1074.  
  1075.  
  1076.  
  1077.  
  1078.  
  1079.  
  1080.      WSC4VB Users Manual                                       Page 18
  1081.  
  1082.        11.4 Internet Libraries
  1083.  
  1084.         WIL4C : C/C++, Win 3.1/95/98/NT. The "Winsock Interface Library"
  1085.                 supports TCP,SMTP,POP3,TELNET,FTP, etc.
  1086.  
  1087.                 WINSOCK INTERFACE LIBRARY for C/C++. Win16 & Win32 DLLs.
  1088.                 (WIL4C20.ZIP). Feb 14, 1998. Version 2.0, [ASP]. The
  1089.                 Winsock Interface Library simplifies winsock network
  1090.                 communications programming and provides support for the
  1091.                 most common Internet protocols such as Finger, SMTP, POP3,
  1092.                 FTP, NNTP, and HTTP. Requires windows C compiler.
  1093.                 Registration is $95 + $7 S&H ($12 overseas).
  1094.  
  1095.         SEE4C : C/C++, Win 3.1/95/98/NT. The simplest way to email from your
  1096.                 C/C++ application, including MIME attachments.
  1097.  
  1098.                 SMTP/POP3 Email Engine for C/C++. Ver 3.0. Win16 and Win32
  1099.                 DLLs. (SEE4C30.ZIP) 4/1/99. Email from your C/C++
  1100.                 application. Simple API allows sending & receiving email,
  1101.                 including MIME attachments. Knowledge of Winsock and TCP/IP
  1102.                 is not needed. Includes multiple C/C++ examples. Requires
  1103.                 windows C/C++ compiler. Registration is $95.
  1104.  
  1105.        SEE4VB : Visual Basic, Win 3.1/95/98/NT.
  1106.  
  1107.        SEE4PB : Power Basic, Windows 95/98/NT.
  1108.  
  1109.         SEE4D : Delphi, Win 3.1/95/98/NT.
  1110.  
  1111.        SEE4DB : Visual dBase, Windows 95/98/NT.
  1112.  
  1113.        SEE4FP : Visual FoxPro, Windows 95/98/NT.
  1114.  
  1115.         SEE4F : ABSOFT Fortran, Windows 95/98/NT.
  1116.  
  1117.        SEE4CB : Fujitsu COBOL, Windows 95/98/NT.
  1118.  
  1119.  
  1120.  
  1121.  
  1122.  
  1123.  
  1124.  
  1125.  
  1126.  
  1127.  
  1128.  
  1129.  
  1130.  
  1131.  
  1132.  
  1133.  
  1134.  
  1135.  
  1136.  
  1137.  
  1138.  
  1139.  
  1140.      WSC4VB Users Manual                                       Page 19
  1141.  
  1142.