


                      Windows Standard Communications

                           Library for PowerBASIC

                                 (WSC4PB)


                             REFERENCE MANUAL



                               Version 2.4

                               May 24, 1999




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




                           Copyright (C) 1999
                           All rights reserved




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

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


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




      MARSHALLSOFT is a registered trademark of MarshallSoft Computing.



     WSC4PB Reference Manual                                   Page 1

                            C O N T E N T S



        Chapter                                     Page

        Table of Contents.............................2

        WSC Functions.................................4

           SioBaud....................................4
           SioBrkSig..................................4
           SioCTS.....................................5
           SioDCD.....................................5
           SioDone....................................6
           SioDSR.....................................6
           SioDTR.....................................7
           SioEvent...................................7
           SioFlow....................................8
           SioGetc....................................8
           SioGets....................................9
           SioInfo....................................9
           SioParms..................................10
           SioPutc...................................10
           SioPuts...................................11
           SioRead...................................11
           SioReset..................................12
           SioRI.....................................12
           SioRTS....................................13
           SioRxClear................................13
           SioRxQue..................................14
           SioStatus.................................14
           SioTimer..................................15
           SioTxClear................................15
           SioTxQue..................................16
           SioUnGetc.................................16
           SioWinError...............................17

        WSC Error Codes..............................17



















     WSC4PB Reference Manual                                   Page 2

                            C O N T E N T S

                              (continued)



        Chapter                                     Page

        Modem I/O Functions..........................18

           mioBreak..................................18
           mioDriver.................................18
           mioQuiet..................................19
           mioResult.................................19
           mioSendTo.................................20
           mioWaitFor................................20

        Xmodem/Ymodem Driver (XYDRV) Functions

           xyAbort...................................21
           xyAcquire.................................21
           xyDebug...................................22
           xyDriver..................................22
           xyGetMessage..............................23
           xyGetParameter............................23
           xyRelease.................................24
           xySetParameter............................24
           xyStartRx.................................25
           xyStartTx.................................25

        XYDRIVER Error Codes.........................26

        ASCII Driver (ASDRV) Functions

           ascAbort..................................27
           ascDriver.................................27
           ascGetMessage.............................28
           ascGetParameter...........................28
           ascInit...................................29
           ascStartRx................................29
           ascStartTx................................30

        ASDRIVER Error Codes.........................30

      NOTE: DefLng is assumed for all functions unless otherwise declared.
      Also note that all arguments are passed by value except for strings,
      which are always declared as ASCIIZ. When in doubt about a function,
      refer to the declarations in WSC32.BAS










     WSC4PB Reference Manual                                   Page 3

      +-------------+-----------------------------------------------------+
      |   SioBaud   |  Sets the baud rate.                                |
      +-------------+-----------------------------------------------------+


      SYNTAX Function SioBaud(ByVal Port, ByVal BaudCode) As Long
             ' Port     : Port selected.
             ' BaudCode : Baud code or actual baud rate.

      REMARK The SioBaud Function sets the baud rate without resetting
             the port. It is used to change the baud rate after calling
             SioReset. SioBaud may be called with either the actual baud
             rate value or one of the baud rate codes as follows:

             Code   Rate    Name             Code   Rate   Name
               0     300    %WSC_Baud300       5    9600   %WSC_Baud9600
               1     600    %WSC_Baud600       6   19200   %WSC_Baud19200
               2    1200    %WSC_Baud1200      7   38400   %WSC_Baud38400
               3    2400    %WSC_Baud2400      8   57600   %WSC_Baud57600
               4    4800    %WSC_Baud4800      9  115200   %WSC_Baud115200

             For example, to set 28800, SioBaud(Port,28800)

             Call SioBaud with Port==-1 before calling SioReset to set the
             default baud rate for subsequent calls to SioReset.

      Return    %WSC_IE_BADID : No such port.
             %WSC_IE_BAUDRATE : Unsupported baud rate.

       OTHER See SioReset.

      +-------------+-----------------------------------------------------+
      |  SioBrkSig  |  Asserts, cancels, or detects BREAK signal.         |
      +-------------+-----------------------------------------------------+

      SYNTAX Function SioBrkSig(ByVal Port, ByVal PortCmd) As Long
             ' Port : Port selected.
             ' Cmd  : ASSERT, CANCEL, or DETECT (see below).

      REMARK The SioBrkSig Function controls the BREAK bit in the line
             status register. The legal commands are:

             %WSC_ASSERT_BREAK : ASC("A") to assert BREAK
             %WSC_CANCEL_BREAK : ASC("C") to cancel BREAK
             %WSC_DETECT_BREAK : ASC("D") to detect BREAK

             %WSC_ASSERT_BREAK, %WSC_CANCEL_BREAK, and %WSC_DETECT_BREAK
             are defined in WSC4PB.BAS.

      RETURN   %WSC_NOPEN : Port not opened. Call SioReset first.
            %WSC_IE_BADID : No such port.
               %WSC_RANGE : Illegal command. Expected "A", "C", or "D".
                       >0 : BREAK signal detected (DETECT command only)

       OTHER None.



     WSC4PB Reference Manual                                   Page 4

      +-------------+-----------------------------------------------------+
      |   SioCTS    |  Reads the Clear to Send (CTS) modem status bit.    |
      +-------------+-----------------------------------------------------+

      SYNTAX Function SioCTS(ByVal Port) As Long
             ' Port : Port selected.

      REMARK The SioCTS Function is used to detect if CTS (Clear To Send)
             is set (1) or clear (0). Some Windows Win16 COMM drivers
             cannot read the CTS bit correctly!

             The CTS line is used by some error correcting modems to
             implement hardware flow control.  CTS is dropped by the modem
             to signal the computer not to send data and is raised to
             signal the computer to continue.

             Refer to the RS232/485 Serial Communications User's Manual
             (ASYNC.TXT) for a discussion of flow control.

      RETURN    %WSC_NOPEN : Port not opened. Call SioReset first.
             %WSC_IE_BADID : No such port.
                         0 : CTS is clear.
                        >0 : CTS is set.

       OTHER See SioFlow, SioDSR, SioRI, and SioDCD.









      +-----------+-------------------------------------------------------+
      |   SioDCD  | Reads the Data Carrier Detect (DCD) modem status bit. |
      +-----------+-------------------------------------------------------+

      SYNTAX Function SioDCD(ByVal Port) As Long
             ' Port : Port selected.

      REMARK The SioDCD Function is used to read the Data Carrier Detect
             (DCD) modem status bit. Also see SioStatus.

      RETURN   %WSC_NOPEN : Port not opened. Call SioReset first.
            %WSC_IE_BADID : No such port.
                        0 : DCD is clear.
                       >0 : DCD is set.

       OTHER See SioDSR, SioCTS, and SioRI.








     WSC4PB Reference Manual                                   Page 5

      +-------------+-----------------------------------------------------+
      |   SioDone   |  Terminates further serial processing.              |
      +-------------+-----------------------------------------------------+

      SYNTAX Function SioDone(ByVal Port) As Long
             ' Port : Port selected.

      REMARK The SioDone function terminates further serial processing,
             allowing other applications to use the port. SioDone should
             always be the last function called before exiting an
             application.


      RETURN   %WSC_NOPEN : Port not opened. Call SioReset first.
            %WSC_IE_BADID : No such port.

       OTHER See SioReset.









      +-------------+-----------------------------------------------------+
      |    SioDSR   |  Reads the Data Set Ready (DSR) modem status bit.   |
      +-------------+-----------------------------------------------------+

      SYNTAX Function SioDSR(ByVal Port) As Long
             ' Port : Port selected.

      REMARK The SioDSR function is used to detect if DSR (Data Set Ready)
             is set (1) or clear (0). Some Windows Win16 COMM drivers
             cannot read the DSR bit correctly!

             Modems normally set DSR as soon as they are powered up.

      RETURN   %WSC_NOPEN : Port not opened. Call SioReset first.
            %WSC_IE_BADID : No such port.
                        0 : DSR is clear.
                       >0 : DSR is set.

       OTHER See SioCTS, SioRI, and SioDCD.













     WSC4PB Reference Manual                                   Page 6

      +-------------+-----------------------------------------------------+
      |    SioDTR   |  Set, clear, or read Data Terminal Ready (DTR).     |
      +-------------+-----------------------------------------------------+

      SYNTAX Function SioDTR(ByVal Port, ByVal Cmd) As Long
             ' Port : Port selected.
             ' Cmd  : DTR command (see below).

      REMARK The SioDTR function controls the Data Terminal Ready (DTR) bit
             in the modem control register.  DTR should always be set when
             communicating with a modem.  Commands (defined in WSC4PB.BAS):

                  %WSC_SET_LINE   : ASC("S")  to set DTR (ON)
                  %WSC_CLEAR_LINE : ASC("C")  to clear DTR (OFF)
                  %WSC_READ_LINE  : ASC("R")  to read DTR

      RETURN  %WSC_NOPEN : Port not opened. Call SioReset first.
           %WSC_IE_BADID : No such port.
              %WSC_RANGE : Not one of "S", "C", or "R".
                       0 : DTR is OFF (%WSC_READ_LINE Command).
                      >0 : DTR is ON (%WSC_READ_LINE Command).

       OTHER See SioRTS.



      +-----------+-------------------------------------------------------+
      | SioEvent  |  Efficiently waits for serial event.                  |
      +-----------+-------------------------------------------------------+

      SYNTAX Function SioEvent(ByVal Port, ByVal Mask)
             ' Port : Port selected.
             ' Mask : Event Mask (see below).

      REMARK The SioEvent function (WIN32 only) waits (blocks) until the
             condition specfied in 'Mask' is satisfied. Multiple
             conditions can be OR'ed together. The event masks are:

              %EV_RXCHAR : A character was received.
               %EV_BREAK : A break signal was received.
                 %EV_CTS : The CTS line changed states.
                 %EV_DSR : The DST line changed states.
                 %EV_ERR : An error was detected.
                %EV_RLSD : The DCD line has changed states.
                %EV_RING : The RI line has been set.
             %EV_TXEMPTY : The TX queue has become empty.

      RETURN SioEvent does not return until the specified event occurs.

       OTHER See SioRead.








     WSC4PB Reference Manual                                   Page 7

      +------------+------------------------------------------------------+
      |   SioFlow  |  Sets flow control.                                  |
      +------------+------------------------------------------------------+

      SYNTAX Function SioFlow(ByVal Port, ByVal Cmd) As Long
             ' Port : Port selected.
             ' Cmd  : Class of flow control (see below).

      REMARK The SioFlow function is used to enable or disable hardware
             flow control.  Hardware flow control uses RTS and CTS to
             control data flow between the modem and the computer.  To
             enable flow control, call SioFlow with 'Cmd' set to:

                    Cmd     Flow Control
                  ASC("H")  Hardware (RTS/CTS) flow control.
                  ASC("S")  Software (XON/XOFF) flow control.
                  ASC("N")  No flow control.

             In order for hardware flow control to work correctly, your
             modem must also be configured to work with hardware flow
             control, and your computer to modem cable must have RTS and
             CTS wired straight through. If you enable hardware flow
             control, do not modify the RTS line (by calling SioRTS). Flow
             control is disabled after resetting a port.

      RETURN   %WSC_NOPEN : Port not opened. Call SioReset first.
            %WSC_IE_BADID : No such port.
               %WSC_RANGE : Cannot recognize Cmd.
                      -1  : Flow control disabled.
                      >0  : Flow control enabled.

       OTHER See SioPutc





      +------------+------------------------------------------------------+
      |   SioGetc  |  Reads the next character from the serial line.      |
      +------------+------------------------------------------------------+

      SYNTAX Function SioGetc(ByVal Port) As Long
             ' Port : Port selected.

      REMARK The SioGetc function reads a byte from the selected serial
             port. WSC_NO_DATA (-100) is returned if no byte is available.


      RETURN   %WSC_NOPEN : Port not opened. Call SioReset first.
            %WSC_IE_BADID : No such port.
             %WSC_NO_DATA : If timed out (no data available).
                     >= 0 : Character read.

       OTHER See SioUnGetc and SioGets.




     WSC4PB Reference Manual                                   Page 8

      +------------+------------------------------------------------------+
      |   SioGets  |  Reads the next byte buffer from the serial line.    |
      +------------+------------------------------------------------------+

      SYNTAX Function SioGets(ByVal Port, Buffer As String,
                              ByVal Cnt) As Long
             ' Port   : Port selected.
             ' Buffer : Receive buffer.
             ' Cnt    : Number bytes wanted.

      REMARK The SioGets function reads the smaller of the number of bytes
             wanted (Cnt) and the number of bytes in the receive buffer. A
             zero is return if no bytes are read.


      RETURN   %WSC_NOPEN : Port not opened. Call SioReset first.
            %WSC_IE_BADID : No such port.
                     >= 0 : Number of characters actually read.

       OTHER See SioUnGetc and SioPutc.



      +-------------+-----------------------------------------------------+
      |   SioInfo   |  Returns WSC4PB library information.                |
      +-------------+-----------------------------------------------------+

      SYNTAX Function SioInfo(ByVal Cmd) As Long
             ' Cmd : Command (See below).

      REMARK The SioInfo function returns an integer code corresponding to
             the Cmd as follows.

                  Command   SioInfo returns
                    "V"     Library version number. For example,

                            'display WSC version
                            Version = SioInfo(ASC("V"))
                            C = Hex$(&HF And Version)
                            Version = Version / 16
                            B = Hex$(&HF And Version)
                            Version = Version / 16
                            A = Hex$(&HF And Version)
                            PRINT "WSC Version " + A + "." + B + "." + C

      RETURN See remarks above.
             -1 : Cannot recognize Cmd.











     WSC4PB Reference Manual                                   Page 9

      +-------------+-----------------------------------------------------+
      |  SioParms   |  Sets parity, stop bits, and word length.           |
      +-------------+-----------------------------------------------------+

      SYNTAX Function SioParms(ByVal Port, ByVal Parity,
                               ByVal StopBits, ByVal DataBits) As Long
             ' Port     : Port selected.
             ' Parity   : Parity code.
             ' StopBits : Stop bits code.
             ' DataBits : Word length code.

      REMARK The SioParms function sets the parity, stop bits, and word
             length.  If the default parity (none), stop bits (1), or word
             length (8) is not acceptable, then they can be changed by
             calling SioParms.  SioParms can be called either before or
             after calling SioReset. Call SioParms with Port==-1 before
             calling SioReset to make the passed parameters the default.
             Use the constant values defined in WSC32.BAS to minimize the
             chance of passing an incorrect parameter value.

               Parity : NoParity, OddParity, EvenParity,
                        MarkParity, SpaceParity.
             StopBits : OneStopBit, One5StopBits, TwoStopBits.
             DataBits : WordLength7, WordLength8.

      RETURN   %WSC_IE_BADID : No such port.
            %WSC_IE_BYTESIZE : Word length not supported.
                  %WSC_RANGE : Parameter out of range.

       OTHER See SioReset.


      +-------------+-----------------------------------------------------+
      |   SioPutc   |  Transmit a character over a serial line.           |
      +-------------+-----------------------------------------------------+

      SYNTAX Function SioPutc(ByVal Port, ByVal Chr) As Long
             ' Port : Port selected.
             ' Chr  : Character to send.

      REMARK The SioPutc function copies the character to the transmit
             queue for subsequent transmission.

      RETURN   %WSC_NOPEN : Port not opened. Call SioReset first.
            %WSC_IE_BADID : No such port.
                        0 : No error.

       OTHER See SioGetc and SioFlow.










     WSC4PB Reference Manual                                   Page 10

      +-------------+-----------------------------------------------------+
      |   SioPuts   |  Transmits a byte buffer over a serial line.        |
      +-------------+-----------------------------------------------------+

      SYNTAX Function SioPuts(ByVal Port, Buffer As String,
                              ByVal Cnt) As Long
             ' Port   : Port selected.
             ' Buffer : String of bytes to transmit.
             ' Cnt    : Bytes in Buffer to send.

      REMARK The SioPuts function copies 'Cnt' bytes from 'Buffer' to the
             transmit queue for subsequent transmission.

      RETURN   %WSC_NOPEN : Port not opened. Call SioReset first.
            %WSC_IE_BADID : No such port.
                     >= 0 : The number of bytes actually transmitted.

       OTHER See SioGetc and SioFlow.




      +-------------+-----------------------------------------------------+
      |  SioRead    |  Read any UART port register.                       |
      +-------------+-----------------------------------------------------+

      SYNTAX Function SioRead(ByVal Port, ByVal Register) As Long
             ' Port     : Port selected.
             ' Register : UART register [0 through 6].

      REMARK  SioRead is NOT for Win32 applications running under Windows
             NT.  The SioRead function reads any of the 7 I/O ports
             directly, by-passing the Windows API. Only for COM1 through
             COM4.

             Note that all modem and/or line status bits can also be read
             using SioDTR, SioRTS, SioDCD, SioRI, SioDSR, and SioCTS. Refer
             to the RS232/485 Serial Communications User's Manual
             (ASYNC.TXT) for a description of the UART registers.

      RETURN %WSC_IE_BADID : No such port.
                 %WSC_OPEN : Already open.
                      else : Value of selected register.















     WSC4PB Reference Manual                                   Page 11

      +-------------+-----------------------------------------------------+
      |  SioReset   |  Initialize a serial port for processing.           |
      +-------------+-----------------------------------------------------+

      SYNTAX Function SioReset(ByVal Port, ByVal RxQueSize,
                               ByVal TxQueSize) As Long
             ' Port      : Port selected.
             ' RxQueSize : Receive queue size.
             ' TxQueSize : Transmit queue size.

      REMARK The SioReset function initializes (opens) the selected serial
             port. SioReset should be called before making any other calls
             to WSC4PB except for setting default behavior (port=-1).
             SioReset uses the parity, stop bits, and word length value
             previously set if SioParms was called, otherwise the default
             values (19200, no parity, 8 data, 1 stop) are used.

             SioReset can be called with Port=-1 in order to specify the
             behavior of DTR and RTS at port initialization:

                SioReset(-1, DTR_Default, RTS_Default)

             DTR will be set at port initialization if DTR_Default is 1,
             else DTR will be cleared. Similarly for RTS_Default.

      RETURN %WSC_IE_BADID : No such port.
                 %WSC_OPEN : Already open.
            %WSC_IE_MEMORY : Cannot allocate memory.
          %WSC_IE_HARDWARE : Hardware error.

       OTHER See SioBaud, SioParms, and SioDone.




      +-------------+-----------------------------------------------------+
      |    SioRI    |  Reads the Ring Indicator (RI) modem status bit.    |
      +-------------+-----------------------------------------------------+

      SYNTAX Function SioRI(ByVal Port) As Long
             ' Port : Port selected.

      REMARK The SioRI function is used to read the Ring Indicator (RI)
             modem status bit.

      RETURN   %WSC_NOPEN : Port not opened. Call SioReset first.
            %WSC_IE_BADID : No such port.
                        0 : RI is clear.
                       >0 : RI is set (RING has occurred).

       OTHER See SioDSR, SioCTS, and SioDCD.







     WSC4PB Reference Manual                                   Page 12

      +-------------+-----------------------------------------------------+
      |    SioRTS   |  Sets, clears, or reads the Request to Send (RTS).  |
      +-------------+-----------------------------------------------------+

      SYNTAX Function SioRTS(ByVal Port, ByVal Cmd) As Long
             ' Port : Port selected.
             ' Cmd  : RTS command (SET, CLEAR, or READ).

      REMARK The SioRTS function controls the Request to Send (RTS bit in
             the modem control register.

             The RTS line is used by some error correcting modems to
             implement hardware flow control.  RTS is dropped by the
             computer to signal the modem not to send data, and is raised
             to signal the modem to continue. RTS should be set when
             communicating with a modem unless Flow Control is being used.

             Refer to the RS232/485 Serial Communications User's Manual
             (ASYNC.TXT) for a discussion of flow control. Commands
             (defined in WSC4PB.BAS) are:

                    %WSC_SET_LINE  ASC("S") : set RTS (ON)
                  %WSC_CLEAR_LINE  ASC("C") : clear RTS (OFF)
                   %WSC_READ_LINE  ASC("R") : read RTS

      RETURN   %WSC_NOPEN : Port not opened. Call SioReset first.
            %WSC_IE_BADID : No such port.
               %WSC_RANGE : Command is not one of "S", "C", or "R".
                        0 : RTS is OFF ("R" command).
                       >0 : RTS is ON  ("R" command).

       OTHER See SioFlow and SioDTR.


      +------------+------------------------------------------------------+
      | SioRxClear |  Clears the receive buffer.                          |
      +------------+------------------------------------------------------+

      SYNTAX Function SioRxClear(ByVal Port) As Long
             ' Port : Port selected.

      REMARK The SioRxClear function will delete any characters in the
             receive buffer for the specified port.  After execution, the
             receive buffer will be empty.

      RETURN   %WSC_NOPEN : Port not opened. Call SioReset first.
            %WSC_IE_BADID : No such port.

       OTHER See SioRxQue.









     WSC4PB Reference Manual                                   Page 13

      +-------------+-----------------------------------------------------+
      |  SioRxQue   |  Returns the number of bytes in the receive queue.  |
      +-------------+-----------------------------------------------------+

      SYNTAX Function SioRxQue(ByVal Port) As Long
             ' Port : Port selected.

      REMARK The SioRxQue function will return the number of characters in
             the receive queue at the time of the call.

      RETURN   %WSC_NOPEN : Port not opened. Call SioReset first.
            %WSC_IE_BADID : No such port.

       OTHER See SioTxQue.




      +------------+------------------------------------------------------+
      | SioStatus  |  Returns the serial port status.                     |
      +------------+------------------------------------------------------+

      SYNTAX Function SioStatus(ByVal Port, ByVal Mask) As Long
             ' Port : Port selected.
             ' Mask : Error mask.

      REMARK The SioStatus function returns the serial port error status
             corresponding to the Mask argument. The numerical values of
             the PortMask constants are defined in WSC4PB.BAS.

             %WSC_RXOVER  : The receive queue overflowed.
             %WSC_OVERRUN : An incoming byte was overwritten.
              %WSC_PARITY : A parity error was detected (incoming byte)
               %WSC_FRAME : A framing error was detected (incoming byte)
               %WSC_BREAK : A break signal was detected.
              %WSC_TXFULL : The transmit queue is full.

      RETURN   %WSC_NOPEN : Port not opened. Call SioReset first.
            %WSC_IE_BADID : No such port.



















     WSC4PB Reference Manual                                   Page 14

      +-----------+-------------------------------------------------------+
      | SioTimer  |  Returns the system time in milliseconds.             |
      +-----------+-------------------------------------------------------+

      SYNTAX Function SioTimer() As Long

      REMARK The SioTimer returns the system time in milliseconds. SioTimer
             calls the Windows API function GetCurrentTime, and is provided
             as a convenience since GetCurrentTime could be called
             directly.

      RETURN The system time in milliseconds.



      +------------+------------------------------------------------------+
      | SioTxClear |  Clears the transmitter buffer.                      |
      +------------+------------------------------------------------------+

      SYNTAX Function SioTxClear(ByVal Port) As Long
             ' Port : Port selected.

      REMARK The SioTxClear function will delete any characters in the
             transmit buffer for the specified port.

             Once this function is called, any character in the transmit
             buffer (put there by SioPutc or SioPuts) will be lost and
             therefore not transmitted.

      RETURN   %WSC_NOPEN : Port not opened. Call SioReset first.
            %WSC_IE_BADID : No such port.

       OTHER See SioTxQue.

























     WSC4PB Reference Manual                                   Page 15

      +------------+------------------------------------------------------+
      |  SioTxQue  |  Returns the number of bytes in the transmit queue.  |
      +------------+------------------------------------------------------+

      SYNTAX Function SioTxQue(ByVal Port) As Long
             ' Port : Port selected.

      REMARK The SioTxQue function will return the number of characters in
             the transmit queue at the time of the call.

      RETURN   %WSC_NOPEN : Port not opened. Call SioReset first.
            %WSC_IE_BADID : No such port.

       OTHER See SioRxQue.








      +------------+------------------------------------------------------+
      | SioUnGetc  |  "Ungets" the last character read with SioGetc().    |
      +------------+------------------------------------------------------+

      SYNTAX Function SioUnGetc(ByVal Port, ByVal Ch) As Long
             ' Port : Port selected.
             ' Ch   : Character to unget.

      REMARK The SioUnGetc function returns (pushes) the character back
             into the serial input buffer.  The character pushed will be
             the next character returned by SioGetc.  Only one character
             can be pushed back. This function works just like the
             "ungetc" function in the C language.

      RETURN   %WSC_NOPEN : Port not opened. Call SioReset first.
            %WSC_IE_BADID : No such port.

       OTHER See SioReset.


















     WSC4PB Reference Manual                                   Page 16

      +--------------+----------------------------------------------------+
      | SioWinError  |  Return last Win32 error code & message text.      |
      +--------------+----------------------------------------------------+

      SYNTAX Function SioWinError(Buffer As Asciiz,
                                  ByVal Size As Long) As Long
             ' Buffer : Pointer to messages buffer.
             '   Size : Size of buffer.

      REMARK The SioWinError returns the last Win32 error code. If Buffer
             is not NULL, it will also copy the corresponding text message
             into 'Buffer' of size 'Size'.

      RETURN The Win32 numeric error code.




                        WSC Error Codes


      +----------------+--------------------------------------------+
      |  %WSC_NO_DATA  |  No incoming serial data is available.     |
      |  %WSC_RANGE    |  A parameter is out of range.              |
      |  %WSC_ABORTED  |  The shareware version of WSC corrupted.   |
      |  %WSC_WIN32ERR |  Win32 system error.                       |
      +----------------+---+----------------------------------------+
      |  %WSC_IE_BADID     |  No such port.                         |
      |  %WSC_OPEN         |  Port already opened.                  |
      |  %WSC_NOPEN        |  Port not opened. Call SioReset first. |
      |  %WSC_IE_MEMORY    |  Cannot allocate memory for queues.    |
      |  %WSC_IE_DEFAULT   |  Error in default parameters.          |
      |  %WSC_IE_HARDWARE  |  Hardware not present.                 |
      |  %WSC_IE_BYTESIZE  |  Unsupported byte size.                |
      |  %WSC_IE_BAUDRATE  |  Unsupported baud rate.                |
      +--------------------+----------------------------------------+


      The WSC_ABORTED error occurs in the shareware version only if there
      is a problem displaying the shareware screen.


















     WSC4PB Reference Manual                                   Page 17

      +-----------+-------------------------------------------------------+
      | mioBreak  |  Aborts the Modem I/O state driver.                   |
      +-----------+-------------------------------------------------------+

      SYNTAX Function mioBreak(ByVal Port) As Long
             ' Port : Port selected.

      REMARK Forces the MIO driver to the IDLE state, abandoning any work
             in progress (if any). Used to abort mioSendTo, mioQuiet, and
             mioWaitFor functions.

      RETURN MIO_IDLE.







      +------------+------------------------------------------------------+
      | mioDriver  |  Modem I/O state driver.                             |
      +------------+------------------------------------------------------+

      SYNTAX Function mioDriver(ByVal Port) As Long
             ' Port : Port selected.

      REMARK Executes the next state of any previously started MIO function
             such as mioSendTo, mioWaitFor, and mioQuiet. Returns %MIO_IDLE
             (defined in MIO32.BAS) if ready not running, %MIO_RUNNING if
             running, and anything else is a character from the modem that
             can be displayed if wanted.

      RETURN   %MIO_IDLE : if the driver is ready for the next mioSendTo,
                           mioWaitFor, or mioQuiet.
            %MIO_RUNNING : if the driver is not idle.
                  <else> : if the driver is not idle, and the returned
                           character was received from the modem.





















     WSC4PB Reference Manual                                   Page 18

      +-----------+-------------------------------------------------------+
      | mioQuiet  |  Waits for Modem I/O state driver.                    |         *
      +-----------+-------------------------------------------------------+

      SYNTAX Function mioQuiet(ByVal Port, ByVal Wait As Long) As Long
             ' Port : Port selected.
             ' Wait : Wait in milliseconds.

      REMARK The mioQuiet function waits for continuous quiet [no incoming
             serial data] of 'Wait' milliseconds before returning.  Any
             incoming character while mioQuiet is running is lost.

      RETURN TRUE.




      +------------+------------------------------------------------------+
      | mioResult  |  Returns result of last mioWaitFor.                  |
      +------------+------------------------------------------------------+

      SYNTAX Function mioResult(ByVal Port) As Long
             ' Port : Port selected.

      REMARK The mioResult function returns the result of the last
             mioWaitFor Function. This function should not be called until
             the driver returns %MIO_IDLE. See the remarks section of the
             mioWaitFor function for an example.

      RETURN  0 : False (last WaitFor not matched)
             !0 : '0' if first substring matched, '1' if second substring
             matched, etc.

       OTHER See mioWaitFor.
























     WSC4PB Reference Manual                                   Page 19

      +-----------+-------------------------------------------------------+
      | mioSendTo |  Sends string to modem.                               |
      +-----------+-------------------------------------------------------+

      SYNTAX Function mioSendTo(ByVal Port, ByVal Pace,
                                Text As String) As Long
             ' Port : Port selected.
             ' Pace : The inter-character delay in milliseconds.
             ' Text : The string to send.

      REMARK The mioSendTo function sends the characters in the string
             'Text' to serial output. There is a delay of 'Pace'
             milliseconds between characters.

             Three characters in 'Text' are interpreted as:

             '^' : next character is control char (^A for 0x01)
             '!' : replaced with carriage return.
             '~' : removed from string (delay 1/2 second).

      RETURN TRUE.



      +-------------+-----------------------------------------------------+
      | mioWaitFor  |  Waits for continuous quiet.                        |
      +-------------+-----------------------------------------------------+

      SYNTAX Function mioWaitFor(ByVal Port, ByVal Wait,
                                 Text As String) As Long

             ' Port : Port selected.
             ' Wait : Total time to wait for response (milliseconds).
             ' Text : The expected response string.

      REMARK The mioWaitFor function waits for characters from serial
             input that match the string 'Text'. A total of 'Wait'
             milliseconds are allowed before timing out and returning FALSE
             (0). The string comparison is NOT case sensitive.

             For example, to wait up to one minute for 'CONNECT', 'NO
             CARRIER', or 'BUSY' from the modem after dialing a number.

             Code = mioWaitFor(ByVal Port,60000,'CONNECT|NO CARRIER|BUSY')

             The function mioDriver() must be called until %MIO_IDLE is
             returned. Then mioResult() is called to get the result of the
             mioWaitFor.  A value of 0 indicates that neither 'CONNECT',
             'BUSY', nor 'NO CARRIER' was received. A non-zero value
             indicates that one of the three sub-strings was received.  A
             '0' is returned if 'CONNECT' was seen, '1' is returned if 'NO
             CARRIER' was seen, and '2' is returned if 'BUSY' was seen.

      RETURN TRUE.

       OTHER See mioResult.


     WSC4PB Reference Manual                                   Page 20

      +---------+---------------------------------------------------------+
      | xyAbort | Aborts the XYDRIVER state driver.                       |
      +---------+---------------------------------------------------------+

      SYNTAX Function xyAbort(ByVal Port) As Long
             ' Port :  Port selected.

      REMARK The xyAbort function forces the driver to IDLE, terminating
             any file transfer which may be in progress.

      RETURN XY_NO_ERROR (0).






      +-----------+-------------------------------------------------------+
      | xyAcquire | Prepares the state driver for operation.              |
      +-----------+-------------------------------------------------------+

      SYNTAX Function xyAcquire(ByVal Port) As Long
             ' Port :  Port selected.


      REMARK The xyAcquire function initializes the driver for subsequent
             use. This should be the first driver function called.

      RETURN =0 : No error (%XY_NO_ERROR).
             <0 : XYDRIVER error. See .XYDRIVER Error Codes.

       OTHER See xyRelease.


























     WSC4PB Reference Manual                                   Page 21

      +----------+--------------------------------------------------------+
      | xyDebug  | Set the driver debug level.                            |
      +----------+--------------------------------------------------------+

      SYNTAX Function xyDebug(ByVal DebugLevel) As Long
             ' DebugLevel : Debug level value.

      REMARK The xyDebug Functions sets the driver debug level as follows:

             DebugLevel :  Meaning
                 0         Only error messages are generated [default].
                 1         Minimal debug messages are generated.
                 2         Maximal debug messages are generated.

             Debug messages are retrieved using the xyGetMessage Function.

      RETURNs New debug level [0,1,2]




      +----------+--------------------------------------------------------+
      | xyDriver | XMODEM / YMODEM state driver.                          |
      +----------+--------------------------------------------------------+

      SYNTAX Function xyDriver(ByVal Port) As Long
             ' Port :  Port selected.

      RETURN    %XY_IDLE : A transfer is not underway.
             %XY_RUNNING : A transfer is underway.

      REMARK The xyDriver function drives the state engine. It is normally
             called within a timer loop. Note that xyDriver never returns
             an error code.

             xyDriver can be called as often as wanted whether or not a
             file transfer was initiated.

       OTHER See xyStartTx and xyStartRx.



















     WSC4PB Reference Manual                                   Page 22

      +--------------+----------------------------------------------------+
      | xyGetMessage |  Get next XYDRIVER message.                        |
      +--------------+----------------------------------------------------+

      SYNTAX Function xyGetMessage(Buffer As String, ByVal Size) As Long
             ' Buffer : Message buffer.
             ' Size   : Size of message buffer.

      REMARK The xyGetMessage function retrieves the next message from the
             driver message queue. Refer to the XMR.BAS example program for
             an sample of using xyGetMessage.

      RETURN  TRUE : A message was copied into Buffer.
             FALSE : No messages are available.

       OTHER See xyDebug.



      +----------------+--------------------------------------------------+
      | xyGetParameter | Retrieves driver parameter.                      |
      +----------------+--------------------------------------------------+

      SYNTAX Function xyGetParameter(ByVal Port, ByVal Parameter) As Long
             ' Port      : Port Selected.
             ' Parameter : Parameter to return.

      REMARK The driver parameter corresponding to the following table is
             returned.

                       Parameter :  Description
               %XY_GET_ERROR_CODE : Driver error code (see XYDRIVER.BAS)
              %XY_GET_ERROR_STATE : Error state (if in error).
                   %XY_GET_PACKET : Current packet number.
                    %XY_GET_STATE : Current state (see XYDRIVER.BAS).
                %XY_GET_FILE_SIZE : File size.
                 %XY_GET_NBR_NAKS : Number of packets ACKed.
                 %XY_GET_LAST_GET : Last incoming (serial) character.
                 %XY_GET_LAST_PUT : Last outgoing (serial) character.
                %XY_GET_GET_COUNT : Number of incoming characters (bytes).
                %XY_GET_PUT_COUNT : Number of outgoing characters (bytes).
             %XY_GET_DRIVER_COUNT : Number times xyDriver() was called.
                               -1 : Cannot recognize parameter.

             The xyGetParameter function can be used to check the state of
             the driver. For example:

            1) xyGetParameter(Port,%XY_GET_STATE) returns %XY_IDLE if idle.

            2) xyGetParameter(Port,%XY_GET_ERROR_CODE) returns the driver
               error code if an error has occurred or %XY_NO_ERROR (0)
               otherwise.

      RETURN See above.




     WSC4PB Reference Manual                                   Page 23

      +-----------+-------------------------------------------------------+
      | xyRelease | Releases driver port.                                 |
      +-----------+-------------------------------------------------------+

      SYNTAX Function xyRelease(ByVal Port) As Long
             ' Port : Port selected.

      REMARK The xyRelease function releases a port that was previously
             acquired with xyAcquire. This function should be called before
             calling the WSC function SioDone.

      RETURN  0 : No error (%XY_NO_ERROR).
             <0 : XYDRIVER error. See XYDRIVER Error Codes.

       OTHER See xyAcquire.





      +----------------+--------------------------------------------------+
      | xySetParameter | Retrieves driver parameter.                      |
      +----------------+--------------------------------------------------+

      SYNTAX Function xySetParameter(ByVal Port, ByVal ParmName,
                                     ByVal ParmValue) As Long
             ' Port      : Port Selected.
             ' ParmName  : Parameter Name.
             ' ParmValue : Parameter Value.

      REMARK The ParmValue corresponding to the following table is set.

                        ParmName : Description
                %XY_SET_NAK_RATE : Sets the prompt delay (in seconds).
                %XY_SET_EOF_CHAR : Sets the XMODEM pad character.
                              -1 : Cannot recognize parameter.

             The %XY_SET_NAK_RATE parameter sets the delay (in seconds)
             between prompts that the receiver transmits to the sender to
             start the file transfer. The legal range is 1 to 10 seconds.

             The %XY_SET_EOF_CHAR parameter sets the pad character used by
             XMODEM in padding the last packet to 128 bytes. The normal
             value is control-Z (hex 1A). For example, to set the pad
             character to zeros:

                 Code = xySetParameter(%COM1, %XY_SET_EOF_CHAR, 0)

      RETURN See above.









     WSC4PB Reference Manual                                   Page 24

      +-----------+-------------------------------------------------------+
      | xyStartRx | Start XMODEM or YMODEM receive.                       |
      +-----------+-------------------------------------------------------+

      SYNTAX Function xyStartRx(ByVal Port, Filename As String,
                                ByVal NCGchar, ByVal Batch) As Long
             ' Port     : Port to use.
             ' Filename : File to receive (XMODEM only).
             ' NCGchar  : NAK, "C", or 'G'.
             ' Batch    : YMODEM flag (T/F).

      REMARK The xyStartRx starts the XMODEM or YMODEM file receive. Once
             started, calls to xyDriver are made to execute the next state
             (or states). The xyStartTx function returns immediately.

             Protocol   :  NCGchar   BatchFlag  :  Comments
             XMODEM     :   NAK        FALSE       Standard XMODEM
             XMODEM/CRC :   "C"        FALSE
             XMODEM/1K  :   "C"        FALSE
             YMODEM     :   "C"        TRUE        Standard YMODEM

             The xyStart function is used to receive a file using XMODEM or
             YMODEM.

      RETURN =0 : No error (%XY_NO_ERROR).
             <0 : Driver error. See "XYDRIVER Error Codes".

       OTHER See xyStartTx and xyDriver.



      +-----------+-------------------------------------------------------+
      | xyStartTx | Start XMODEM or YMODEM transmit.                      |
      +-----------+-------------------------------------------------------+

      SYNTAX Function xyStartTx(ByVal Port, Filename As String,
                                ByVal OneKflag, ByVal Batch) As Long
             ' Port     : Port to use.
             ' Filename : File to send.
             ' OneK     : Want 1K blocks (T/F).
             ' Batch    : YMODEM flag (T/F).

      REMARK The xyStartTx starts the XMODEM or YMODEM file send. Once
             started, calls to xyDriver are made to execute the next state
             (or states). The xyStartTx function returns immediately.

             Protocol   :  OneKflag  BatchFlag : Comments
             XMODEM     :   FALSE      FALSE     Standard XMODEM
             XMODEM/CRC :   FALSE      FALSE
             XMODEM/1K  :   TRUE       FALSE
             YMODEM     :   TRUE       TRUE      Standard YMODEM

      RETURN =0 : No error (%XY_NO_ERROR).
             <0 : Driver error. See "XYDRIVER Error Codes".

       OTHER See xyStartRx and xyDriver.


     WSC4PB Reference Manual                                   Page 25


                         XYDRiVER Error Codes

      Error codes are always negative, except for 'no error'. Most of these
      error conditions rarely occur. Also note that XYDRV functions can
      return WSC errors. An error message is queued when an error occurs
      which can be retrieved with xyGetMessage.

      The numeric values for error codes can be found in XYDRV32.BAS.

      +---------------------------+---------------------------------------+
      |              %XY_NO_ERROR | No error. (0)                         |
      |         %XY_UNKNOWN_ERROR | Unknown error.                        |
      |  %XY_ALREADY_ACTIVE_ERROR | Port already acquired.                |
      |     %XY_CANNOT_OPEN_ERROR | Cannot open specifed file.            |
      |      %XY_EMPTY_FILE_ERROR | Specified file is empty.              |
      | %XY_NO_STARTUP_CHAR_ERROR | Must specify NAK or "C".              |
      |         %XY_NOT_NCG_ERROR | Expected NAK or "C".                  |
      |       %XY_DISK_READ_ERROR | Error reading disk.                   |
      |      %XY_NO_EOT_ACK_ERROR | EOT was not ACKed.                    |
      |        %XY_INTERNAL_ERROR | Internal error!                       |
      |       %XY_CANCELLED_ERROR | Other side cancelled.                 |
      |     %XY_OUT_OF_SYNC_ERROR | Protocol has lost synchronization.    |
      |         %XY_RETRIES_ERROR | Packet retry limit was exceeded.      |
      |  %XY_BAD_PACKET_NBR_ERROR | Incorrect packet number.              |
      |       %XY_TIMED_OUT_ERROR | Timed out waiting for other side.     |
      |    %XY_NO_SUCH_FILE_ERROR | No such file.                         |
      |      %XY_NOT_ACTIVE_ERROR | Port not acquired by xyAcquire.       |
      |      %XY_PORT_RANGE_ERROR | Port number out of range.             |
      +---------------------------+---------------------------------------+




























     WSC4PB Reference Manual                                   Page 26

      +----------+--------------------------------------------------------+
      | ascAbort | Aborts the Ascii state driver.                         |
      +----------+--------------------------------------------------------+

      SYNTAX Function ascAbort() As Long

      REMARK The ascAbort function forces the ASCII driver to IDLE,
             terminating any file transfer which may be in progress.

      RETURN none.



      +-----------+-------------------------------------------------------+
      | ascDriver | Ascii state driver.                                   |
      +-----------+-------------------------------------------------------+

      SYNTAX Function ascDriver() As Long

      RETURN 1 : IDLE (A transfer is not underway).
             0 : Running (A transfer is underway).

      REMARK The ascDriver function drives the state engine. It executes
             the next driver state, and is typically called from within a
             timer loop.

             ascDriver can be called as often as wanted whether or not a
             file transfer was initiated. Note that ascDriver never
             returns an error code.

       OTHER See ascStartTx and ascStartRx.



























     WSC4PB Reference Manual                                   Page 27

      +---------------+---------------------------------------------------+
      | ascGetMessage |  Get next Ascii driver message.                   |
      +---------------+---------------------------------------------------+

      SYNTAX Function ascGetMessage(Buffer As String, ByVal Size) As Long
             ' Buffer : Message buffer.
             ' Size   : Size of message buffer.

      REMARK The ascGetMessage function retieves the next message from the
             driver message queue.

      RETURN  TRUE : A message was copied into Buffer.
             FALSE : No messages are available.

       OTHER See ascGetParameter.



      +-----------------+-------------------------------------------------+
      | ascGetParameter | Retrieves driver parameter.                     |
      +-----------------+-------------------------------------------------+

      SYNTAX Function ascGetParameter(ByVal Parameter) As Long
             ' Parameter : Parameter to return.

      REMARK The driver parameter corresponding to the following table is
             returned.

                         Parameter :  Desciption
               %ASC_GET_ERROR_CODE : Driver error code (see ASCDRV.BAS)
              %ASC_GET_ERROR_STATE : Error state (if in error).
                    %ASC_GET_STATE : Current state (ss ASCDRV.BAS).
                                -1 : Cannot recognize parameter.

             The ascGetParameter function can be used to check the state of
             the driver. For example:

             1) ascGetParameter(Port,%ASC_GET_STATE) returns the current
                state.

             2) ascGetParameter(Port,%ASC_GET_ERROR_CODE) returns the
                driver error code if an error has occurred or %ASC_NO_ERROR
                (0) otherwise.

      RETURN See above.













     WSC4PB Reference Manual                                   Page 28

      +---------+---------------------------------------------------------+
      | ascInit | Start Ascii receive.                                    |
      +---------+---------------------------------------------------------+

      SYNTAX Function ascInit(ByVal Port, ByVal RxBufSize,
                              ByVal xFlag) As Long
             ' Port : Port selected.
             ' RxBufSize : RX buffer size
             ' xFlag : Perform XON/XOFF flag (T/F).

      REMARK The ascInit initializes the Ascii driver for subsequent use.
             RxBufSize is the size of the receive buffer as passed to
             SioReset. xFlag is used to request that XON/XOFF flow control
             be performed by the Ascii driver.

      RETURN =0 : No error (%ASC_NO_ERROR).
             <0 : Driver error. See "ASDRIVER Error Codes".

       OTHER See ascStartTx and ascDriver.

      +------------+------------------------------------------------------+
      | ascStartRx | Start Ascii receive.                                 |
      +------------+------------------------------------------------------+

      SYNTAX function ascStartRx(FileName As String, ByVal TermChar,
                                 ByVal FirstWait, ByVal CharWait,
                                 ByVal EchoFlag) As Long
             ' Filename : File to receive
             ' TermChar : Termination character ($00 if none)
             ' FirstWait: Max seconds to wait for 1st incoming char
             ' CharWait : Max seconds between chars to wait
             ' EchoFlag : Echo to display if true

      REMARK The ascStartRx starts the ASCII file receive. Once
             started, calls to ascDriver are made to execute the next state
             (or states). The ascStartTx function returns immediately.

             You may need to prompt the sender by sending a carriage return
             ($0d) or XON character ($11).
             example.

      RETURN =0 : No error (%ASC_NO_ERROR).
             <0 : Driver error. See "Error Codes" for a list of errors.

       OTHER See ascStartTx and ascDriver.













     WSC4PB Reference Manual                                   Page 29

      +------------+------------------------------------------------------+
      | ascStartTx | Start Ascii transmit.                                |
      +------------+------------------------------------------------------+

      SYNTAX Function ascStartTx(FileName As String, ByVal CharPace,
                                 ByVal TermChar, ByVal EchoFlag) As Long
             ' Filename : File to receive
             ' CharPace : Delay in millisecs between chars
             ' TermChar : Termination character ($00 if none)
             ' EchoFlag : Echo to display if true

      REMARK The ascStartTx starts the Ascii file send. Once
             started, calls to ascDriver are made to execute the next state
             (or states). The ascStartTx function returns immediately.

      RETURN =0 : No error (%ASC_NO_ERROR).
             <0 : Driver error. See XTDRIVER.BAS for a list of errors.

       OTHER See ascStartRx and ascDriver.

                         ASCDRIVER Error Codes

      Error codes are always negative, except for 'no error'. Most of these
      error conditions rarely occur. Also note that ASCII DRIVER functions
      can return WSC errors. An error message is queued when an error
      occurs which can be retrieved with ascGetMessage.

      The numeric values for error codes can be found in AscDriver.bas.

      +-------------------------+-----------------------------------------+
      |           %ASC_NO_ERROR | No error. (0)                           |
      |   %ASC_NOT_ACTIVE_ERROR | ascInit not previously called.          |
      |  %ASC_CANNOT_OPEN_ERROR | Cannot open specifed file.              |
      |      %ASC_DISK_IO_ERROR | Error reading or writting disk.         |
      |     %ASC_INTERNAL_ERROR | Internal error!                         |
      |     %ASC_NOT_OPEN_ERROR | File not open.                          |
      +-------------------------+-----------------------------------------+





















     WSC4PB Reference Manual                                   Page 30

