


                         Personal Communications Library

                             For the C/C++ Language


                                     (PCL4C)


                                 USERS MANUAL



                                   Version 6.2
                                January 28, 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
                               FTP : ftp.marshallsoft.com/marshallsoft
                               web : www.marshallsoft.com


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



      MARSHALLSOFT is a registered trademark of MarshallSoft Computing.





     PCL4C Users Manual                                        Page 1

                                C O N T E N T S



       Chapter                                                   Page

       1.0 Introduction................................................3
           1.1 User Support............................................4
           1.2 ASP Ombudsman...........................................4
           1.3 A Typical Application...................................5
           1.4 Installation............................................6
       2.0 Library Organization........................................7
           2.1 Configuration...........................................7
           2.2 Initialization & Termination............................7
           2.3 Modem Control & Status..................................8
           2.4 Serial I/O..............................................8
           2.5 Error Detection.........................................9
           2.6 General Support.........................................9
       3.0 Library Overview...........................................10
           3.1 Memory Models..........................................10
           3.2 16-bit Protected Mode..................................11
           3.3 Compilers Supported....................................12
           3.4 Using the Library......................................12
           3.5 Compiling & Linking....................................13
           3.6 Using a Makefile.......................................13
           3.7 Using an IDE...........................................14
       4.0 Modem I/O..................................................15
       5.0 Problems...................................................16
       6.0 Types of Serial Programs...................................17
           6.1 Terminal Programs......................................17
           6.2 Door Programs..........................................17
           6.3 BBS Programs...........................................17
           6.4 Communication with Serial Device.......................17
       7.0 Application Notes..........................................18
           7.1 Running under Windows..................................18
           7.2 Buffered UARTs.........................................18
           7.3 Running 3 or 4 Ports Concurrently......................19
           7.4 Transmitter Interrupts.................................20
       8.0 Using Multiport Cards......................................21
           8.1 Digiboards.............................................21
           8.2 BOCA Boards............................................21
       9.0 Example Programs...........................................22
      10.0 Legal Issues...............................................24
           10.1 Registration..........................................24
           10.2 License...............................................25
           10.3 Warranty..............................................25
      11.0 Summary....................................................26
           11.1 Revision History......................................26
           11.2 Function Summary......................................28
           11.3 Further Reading.......................................28








     PCL4C Users Manual                                        Page 2

      1.0 Introduction

      The Personal Communications Library for the C Language (PCL4C) is an
      asynchronous communications library designed for experienced software
      developers programming in C/C++.  Six compilers are supported:
      Microsoft C, Quick C, Borland C, Turbo C, Watcom C, and MIX Power C.
      An IBM PC/XT/AT or compatible is required.  The PCL features:

              o Supports 16-bit PROTECTED MODE.
              o SMALL, COMPACT, MEDIUM, LARGE, & FLAT memory models.
              o User selectable baud rates.
              o 40 communications and support functions.
              o Supports 8250, 16450, 16550, 16650, and 16750 UARTs.
              o Supports the PC/4 and PC/8 DigiBoard.
              o Supports the BOCA BB1004, BB1008, and BB2016 boards.
              o Supports hardware (RTS/CTS) flow control.
              o Interrupt driven transmitter & receiver.
              o Supports 300 baud to 115,200 baud.
              o Use IRQ2 through IRQ15 with any UART address.
              o Supports COM1 thru COM4 (COM20 in registered version).
              o Adjustable receive queues from 8 bytes to 32 KB.
              o Control-BREAK error exit.
              o 18 communications error conditions trapped.
              o Allows 4 ports to run concurrently (more with multiport).
              o Complete modem control & status.
              o Written in assembly language for small size & high speed.
              o Terminal program featuring ASCII (with XON/XOFF), XMODEM,
                YMODEM, & YMODEM-G. ZMODEM is available (PPL4C).

         Why should you buy PCL4C ?  Several good reasons are:

        COMPLETE - PCL4C is complete since it provides absolute control of
                   the serial ports (including the 16550/650/750 UARTs).

         COMPACT - PCL4C is very compact at less than 10 KB.  Your
                   application doesn't carry a lot of excess code.

            FAST - PCL4C is fast since it will support 38400 baud even on
                   slow 8088 PCs (4.77 MHZ).

         SUPPORT - If you get stuck, you talk to the programmer that wrote
                   the code, not a person hired to answer the phone.

        INTERNET - A support web site www.marshallsoft.com and FTP site
                   ftp.marshallsoft.com/marshallsoft are maintained.

      NEWSLETTER - We publish a quarterly newsletter "Comm Talk", which
                   discusses serial communications problems and solutions.

           PRICE - You get PCL4C for a very reasonable price!

        UPGRADES - Once you buy PCL4C, you can always update to the most
                   recent version very inexpensively ($30 plus shipping).

      Also see Serial Communications Manual (ASYNC.TXT) and Products
      (PRODUCTS.TXT).


     PCL4C Users Manual                                        Page 3

      1.1 User Support

      We want our customers to be successful in developing applications
      using PCL4C! We depend on our customers to let us know what they
      need in a communications library.  This means we are committed to
      providing the best communications library that we can. If you have
      any suggestions or comments, please let us know!

      We provide customer support for registered customers by voice,
      Internet email, and US mail.

      If you are having a problem using PCL4C, call us at 256-881-4630
      between 7:00 AM and 7:00 PM (CST) Monday through Friday. You can
      often contact us on the weekends.  We also provide customer support
      by email at

                support@marshallsoft.com

      However, we can only answer questions with respect to using the PCL4C
      library. We cannot help you program your application, but we'll be
      glad to discuss it with you.

      Those on the Internet can access our web site at

          http://www.marshallsoft.com

      and our FTP site at

          ftp://ftp.marshallsoft.com/marshallsoft

      The MarshallSoft Computing, Inc.  newsletter "Comm Talk" is published
      quarterly on our web site.  It discusses various communications
      problems and solutions using PCL4C as well as related information.

      The latest copy of our newsletter can be found on our anonymous FTP
      site and on our Web site.

          FTP : ftp://ftp.marshallsoft.com/marshallsoft
          Web : http://www.marshallsoft.com

      1.2 ASP Ombudsman

      MarshallSoft Computing, Inc. is a member of the Association of
      Shareware Professionals (ASP).  ASP wants to make sure that the
      shareware principle works for you.  If you are unable to resolve a
      shareware-related problem with an ASP member by contacting the member
      directly, ASP may be able to help. The ASP Ombudsman can help you
      resolve a dispute or problem with an ASP member, but does not provide
      technical support for members' products. Please write to the ASP
      Ombudsman at 157-F Love Ave., Greenwood, IN 26142 USA, FAX
      317-888-2195, or send email to omb@asp-shareware.org.







     PCL4C Users Manual                                        Page 4

      1.3 A Typical Application

      In general, there are two classes of applications that use a
      communications library like PCL4C - those that use a modem to connect
      to the outside world and those that connect directly to a peripheral
      device. In either case, a typical (real mode) application program
      using PCL4C might look like the following code outline:

           +---------------------------------------------------+
           | #include  "pcl4c.h"                               |
           |                                                   |
           | void main(void)                                   |
           | {                                                 |
           |  ...                                              |
           |  /* initialize serial comm  system  */            |
           |  SioRxBuf(Port,AllocSeg(1024),Size1024);          |
           |  SioTxBuf(Port,AllocSeg(128),Size128);            |
           |  SioParms(Port,NoParity,OneStopBit,WordLength8);  |
           |  SioReset(Port,Baud2400);                         |
           |                                                   |
           |  ...application code...                           |
           |                                                   |
           |  /* terminate serial comm system  */              |
           |  SioDone(Port);                                   |
           | }                                                 |
           +---------------------------------------------------+

      In the above example, SioRxBuf is called to set up a 1024 byte
      receive buffer; SioTxBuf is called to set up a 128 byte transmit
      buffer; SioParms is called to set up the parity, stop bit count, and
      word length; SioReset is called to set the baud rate to 2400 and
      reset the UART (Univeral Asynchronous Receiver / Transmitter).

      The function AllocSeg allocates a buffer of specified size on the far
      heap and returns the segment SEG such that SEG:0 points to the
      buffer.  The function AllocSeg is part of the example code and can be
      found in the file ALLOCSEG.C.

      Before leaving the application, SioDone is called to restore the
      prior state of the serial communications system.

      If you are using a modem, you also need to be concerned about
      initializing the modem correctly and handling any required flow
      control. Refer to the Serial Communications Manual (ASYNC.TXT) for a
      discussion on flow control.

      The communication library has been pre-assembled to library files:

              PCL4C_S.LIB : Small memory model.
              PCL4C_C.LIB : Compact memory model.
              PCL4C_M.LIB : Medium memory model.
              PCL4C_L.LIB : Large memory model.
              PCL4C_P.LIB : 16-bit Protected mode [Large model].
              PCL4C_S.MIX : MIX PowerC small memory model.
              PCL4C_M.MIX : MIX PowerC medium memory model.
              PCL4C_L.MIX : MIX PowerC large memory model.


     PCL4C Users Manual                                        Page 5

      1.4 Installation

      (1) Before installation of PCL4C, the C compiler should already be
      installed on your system and tested. If you are not familiar with
      makefiles, refer to your compiler manual. If you are using the
      interactive environment for Quick C or Turbo C, be sure to compile
      with the memory model corresponding to the PCL4C library used, and
      include the correct library in the project file.

      (2) Make a backup copy of your distribution disk.  Put your original
      distribution disk in a safe place.

      (3) Create a work directory on your work disk (normally your
      harddisk).  For example, to create a work directory named PCL4C, we
      first log onto the work disk and then type:

                          MKDIR PCL4C

      (4) Copy all the files from your backup copy of the distribution disk
      to your work directory.  For example, to copy from the A: drive to
      your work directory, we type:

                          CD PCL4C
                          COPY A:*.*

      (5) [OPTIONAL] Delete the makefiles that you won't need.  For
      example, if you use the Microsoft C compiler, then you want to keep
      all makefiles ending *._M_ but can delete those for Turbo C (*._T_),
      Quick C (*._Q_), and MIX Power C (*.PRJ).  You may also delete any
      libraries that you won't need.

      (6) Compile SIMPLE.C and link with the appropriate PCL4C library
      (PCL4C_S.LIB for all but Power C which must use PCL4C_S.MIX).
      Makefiles (or project files) are provided for each of the supported
      compilers.

              a) Microsoft C/C++:  MAKE SIMPLE._M_
              b) Microsoft QuickC: MAKE SIMPLE._Q_
              c) Borland C/C++:    MAKER -fSIMPLE._B_
              d) Turbo C/C++:      MAKE -fSIMPLE._T_
              e) MIX Power C:      PC/E SIMPLE.PRJ
              f) WATCOM C/C++:     WMAKE -f SIMPLE._W_

      SIMPLE.C should compile without any problems as all example code has
      been tested with each of the supported compilers.

      (7) The recommended way to test SIMPLE is to run it on two computers
      connected by a null modem cable.  Whatever is typed on one computer
      should be displayed on the other.

      SIMPLE can also be tested by connecting the serial port to a modem.
      Transmitting an "AT" to the modem should result in an "OK" being
      received.





     PCL4C Users Manual                                        Page 6

      2.0 Library Organization

      The PCL4C library is organized into six categories of functions.
      Refer to the PCL4C Reference Manual (PCL4C_R.TXT) for details on
      individual functions, and the Serial Communications Manual
      (ASYNC.TXT) for details on UARTs and RS232/422/485 pin definitions.

      2.1 Configuration

      There are three functions in the configuration category.  SioPorts
      sets the number of PC and DigiBoard (or BOCA board) ports. SioUART is
      used to change the UART base address for a communications port to a
      non-standard address, while SioIRQ is used to assign a nonstandard
      IRQ line to a port.  (See the Serial Communications Manual for more
      details on standard UART addresses and IRQ lines).

      The configuration functions SioPorts, SioUART and SioIRQ must be
      called before calling any other library functions.  Be very careful
      in using these functions.  Remember that the serial hardware must
      support the UART and IRQ that you specify.  Always test any new
      configuration immediately.

      SioPorts -  Sets number of PC and DigiBoard (or BOCA board) ports.
      SioUART  |  Sets the UART base address.
      SioIRQ   -  Assigns an IRQ line to a port.

      THE IRQ GOLDEN RULE: You may open (via SioReset) only one port per
      IRQ (except for the DigiBoard and BOCA board).

      2.2 Initialization & Termination

      There are eight functions in the initialization and termination
      category. Together, SioParms, SioFIFO, SioRxBuf, SioTxBuf, and
      SioReset initialize the serial communications system.  Your
      application must call SioRxBuf and SioTxBuf before calling SioReset,
      and SioReset must be called before any serial I/O processing can be
      done.

      After initialization, SioParms and SioBaud can be called to change
      the communications parameters without resetting the serial port.
      SioFlow can be called to enable hardware flow control.  SioFIFO can
      be called to set the FIFO interrupt level for the 16550, 16650, and
      16750 UARTs.

      Before exiting from the application, SioDone must be called. Failure
      to call SioDone can crash the system later.

      SioRxBuf   : Sets up receive buffer.
      SioTxBuf   : Sets up transmitter buffer.
      SioFIFO    : Sets the interrupt level for the 16550
      SioParms   : Sets parity, stop bits, and word length.
      SioReset   : Initialize a serial port for processing.
      SioDone    : Terminates further serial processing.
      SioBaud    : Sets the baud rate of the selected port.
      SioFlow    : Enables / disables hardware flow control.



     PCL4C Users Manual                                        Page 7

      2.3 Modem Control & Status

      There are 11 functions in this category which provide complete
      control over the status and control bits of the modem.

      There are two modem control bits, "Data Terminal Ready" (DTR) and
      "Request To Send" (RTS).  These bits can be read, set, or cleared by
      SioDTR and SioRTS.

      There are four modem status bits, "Data Set Ready" (DSR), "Clear To
      Send" (CTS), "Ring Indicator" (RI), and "Data Carrier Detect" (DCD).
      SioModem can read any of the modem status bits.  SioDSR, SioCTS,
      SioRI, and SioDCD can only read their respective modem status bit.
      SioGetDiv reads the baud rate divisor register so the baud rate can
      be determined. SioSetDiv sets the divisor for the user baud rate.

      Refer to the Serial Communications Manual (ASYNC.TXT) for a
      discussion of each of the control and status bits.

      SioDTR    : Set, clear, or read the Data Terminal Ready (DTR) bit.
      SioRTS    : Sets, clears, or reads the Request to Send (RTS) line.
      SioModem  : Reads the modem status register.
      SioDSR    : Reads the Data Set Ready (DSR) modem status bit.
      SioCTS    : Reads the Clear to Send (CTS) modem status bit
      SioDCD    : Reads the Data Carrier Detect (DCD) modem status bit.
      SioRI     : Reads the Ring Indicator (RI) modem status bit.
      SioRead   : Reads the contents of the 7 UART registers.
      SioGetDiv : Reads the baud rate divisor registers.
      SioSetDiv : Sets the divisor for the user selectable baud rate.
      SioEmpty  : Waits until UART has transmitted last bit.

      2.4 Serial I/O

      There are 11 library functions in this category which together
      provide the programmer complete control over serial I/O. Higher level
      functions such as protocols and smart modem communications can be
      completely implemented in terms of these functions.

      SioGetc, SioGets, SioPutc, and SioPuts perform all the actual serial
      I/O. SioUnGetc "ungets" the last serial byte read.  SioRxClear clears
      the receive queue while SioTxClear clears the transmit queue.
      SioTxFlush flushes the transmit queue.  SioLine can be used to test
      for UART errors. SioRxQue returns the number of bytes in the RX queue
      while SioTxQue returns the number of bytes in the TX queue.

      SioGetc    : Reads the next character from the serial line.
      SioGets    : Reads a buffer of characters from the serial line.
      SioLine    : Reads the line status register.
      SioPutc    : Transmit a character over a serial line.
      SioPuts    : Transmit a buffer of characters over a serial line.
      SioRxClear : Clears the RX buffer.
      SioRxQue   : Returns the number of characters in the RX queue.
      SioTxClear : Clears the TX buffer.
      SioTxFlush : Flushes the TX buffer by restarting TX interrupts.
      SioTxQue   : Returns the number of characters in the TX queue.
      SioUnGetc  : "Un:gets" (puts back) a specified character.


     PCL4C Users Manual                                        Page 8

      2.5 Error Detection

      There are four functions in the error detection category.  They are
      concerned with detecting or reporting communications errors.  Use of
      these functions can make your application significantly more robust.

      SioBrkKey can be used as an "emergency" exit from an application.
      SioBrkSig can read or modify the UART break bit.  This is useful for
      signalling the remote system that a fatal condition has occurred.
      SioLoopBack can be used to test the integrity of an UART.  SioError
      displays a error message corresponding to an error code returned from
      a PCL4C function (every PCL4C function returns a code).

      SioBrkKey   : Returns !0 if CTL-BREAK was pressed.
      SioBrkSig   : Asserts, cancels, or detects the RS232 BREAK  signal.
      SioError    : Displays error in text.
      SioLoopBack : Performs a UART loopback test.

      2.6 General Support

      There are three functions in the general support category.  They are
      as follows:

      SioInfo     : Returns library information such as version number.
      SioDelay    : Delays one or more tics (18.2 tics per second).
      SioTimer    : Returns the number of system clock tics.

      Refer to the PCL4C Reference Manual (PCL4C_R.TXT) for information on
      particular functions.





























     PCL4C Users Manual                                        Page 9

      3.0 Library Organization

      3.1 Memory Models

      Because of the segmented architecture of the INTEL CPU, there are
      four real mode memory organizations possible for computer programs.
      These are named the SMALL, COMPACT, MEDIUM, and LARGE memory models,
      which correspond to the four combinations of "near" and "far"
      addresses for code and data.

      Each (real mode) executable is composed of one or more segments,
      where each segment can occupy from one byte to 64 KB of memory.  A
      "near" address is a 16 bit offset in a segment, whereas a "far"
      address consists of both a 16 bit segment value and a 16 bit offset.

      In the small memory model, code and data each occupy one segment.
      Thus, near addresses are allocated for both code and data.

      In the compact memory model, code occupies one segment while data may
      occupy multiple segments.  Near addresses are allocated for code but
      far addresses are allocated for data.

      In the medium memory model, data occupies one segment while code may
      occupy multiple segments.  Near addresses are allocated for data but
      far addresses are allocated for code.

      In the large memory model, data and code each occupy multiple
      segments.  Far addesses are allocated for both code and data. Thus,
      both code and data can use as many segments as required.

      Refer to your compiler manual for a discussion of the memory models
      supported by your compiler.

      PCL4C is organized as four separate libraries (PCL4C_S.LIB,
      PCL4C_C.LIB, PCL4C_M.LIB and PCL4C_L.LIB) corresponding to the four
      standard memory models. For the MIX Power C compiler, the small,
      medium, and large models are provided. Lastly, there is the 16-bit
      protected mode model which is linked into protected mode
      applications.

         MODEL      CODE      DATA     Library
         Small      Near      Near     PCL4C_S.LIB & PCL4C_S.MIX
         Compact    Near      Far      PCL4C_C.LIB
         Medium     Far       Near     PCL4C_M.LIB & PCL4C_M.MIX
         Large      Far       Far      PCL4C_L.LIB & PCL4C_L.MIX
         Protected  Far       Far      PCL4C_P.LIB.

      However, one can always use the large memory model library
      PCL4C_L.LIB with any memory model application code by explicitly
      declaring the PCL4C procedures to be FAR (by prefixing "far" before
      the name of each function in the PCL4C.H file) and declaring the
      receive buffer to be FAR.  If you are compiling with the HUGE memory
      mode (real mode), link with PCL4C_L.LIB.





     PCL4C Users Manual                                        Page 10

      3.2 16-Bit Protected Mode

      The Personal Communications Library (PCL4C_P.LIB) supports 16-bit
      protected mode, and has been tested with Borlands DOS Power Pack
      (requires Borland C/C++ 4.0 or 4.5) and with PharLaps 286 DOS
      extender. Customers also report being able to use it with other
      16-bit extenders.

      16-Bit Protected Mode programming takes advantage of the segmented
      architecture of 286 and up Intel processors.  In contrast to normal
      real mode programming which limits programs to an address space of 1
      MB (1024 KB), 16-bit protected mode allows up to 16 MB. Protected
      mode also offers some measure of protection of one program from
      another.

      A program that can execute in protected mode under DOS requires three
      modules:

      (1) A DPMI (DOS Protected Mode Interface) server loaded in memory.
      Execute the real mode program DPMI.EXE to determine if a DPMI server
      is loaded.

      (2) A protected mode runtime C library linked to your program.

      (3) A 16-bit DOS extender which provides protected mode equivalents
      for:
          a) A subset of DOS interrupt 21H calls.
          b) A subset of BIOS calls.

      The application program must be compiled with a C/C++ compiler that
      supports protected mode.

      Examine the example program SIMPLE16.C, which is a (16-bit) protected
      mode version of the normal DOS based SIMPLE.C. Compare it to SIMPLE.C
      to see the differences necessary to run in protected mode.

      In particular, note the manner in which memory is allocated for use
      in PCL4C. The transmit and receive buffers must be allocated in
      conventional DOS memory (the first 1MB) since serial interrupts can
      occur during both protected mode and real mode. Also notice that
      memory should be freed after calling SioDone but before exiting.

      Examine the makefile (SIMPLE16._B_) used to compile SIMPLE16.C using
      the Borland compiler 4.0 or 4.5 (and Borland's PowerPack for DOS),
      and SIMPLE16._P_ for use with Microsoft C and the Pharlap 16-bit
      extender.

      The program SELFTEST.C can also be compiled for protected mode by
      using the makefile SELF16._B_ (Borland) or SELF16._P_ (PharLap).

      For more information on protected mode, refer to your DOS extender
      such as the Borland Power Pack or Pharlap 16-bit DOS extender manual.

      Check out our Windows Standard Communications Library for C/C++
      (WSC4C) if you want to write native Win32 (Win95 & WinNT) console
      mode applications.


     PCL4C Users Manual                                        Page 11

      3.4 Compilers Supported

      At this time, six C compilers are supported by PCL4C.

              (1)  Microsoft C Compiler.
              (2)  Quick C Compiler.
              (3)  Turbo C Compiler.
              (4)  Borland C Compiler.
              (5)  MIX Power C Compiler
              (6)  Watcom C compiler.

      The Microsoft C Compiler supports all memory models.  Just be careful
      to link with the PCL4C library that corresponds to the memory model
      used.  Recall that the small memory model is the default.  Examine
      the (small model) makefiles *._M_ for the Microsoft compiler.

      The Microsoft Quick C Compiler supports all memory models, but be
      careful to link with the PCL4C library that corresponds with the
      memory model used. Recall that the small memory model is the default
      for the command line compiler (QCL) while the medium memory model is
      the default for the interactive compiler environment.  Examine the
      (small model) makefiles *._Q_ for the Microsoft Quick C compiler.

      The Borland and Turbo C Compilers also support all memory models. Be
      sure to link with the correct PCL4C library corresponding to the
      memory model used. Examine the (small model) makefiles *._T_ for the
      Turbo C compiler and *._B_ for the Borland compiler.

      The MIX Power C Compiler supports the small, medium, and large memory
      models. However, older versions of Power C only support the small
      model.  Examine the (small model) project batch files *.PRJ for the
      Power C Compiler.

      Other compilers may also work with one or more of the PCL4C libraries
      but have not been tested. Give us a call if you have any difficulty.

      3.5 Using the Library

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

      If there are any conflicts between PCL4C definitions and those in
      other libraries, the PCL4C definitions can be changed in the PCL4C.H
      file and any file that uses the definition. There is no change
      necessary for the library code itself.

      The PCL4C libraries contain no references to any runtime libraries.
      Only BIOS and MSDOS functions are called.









     PCL4C Users Manual                                        Page 12

      3.6 Compiling and Linking

      Registered users may wish to assemble PCL4C.ASM.  Use the /MX switch
      in order to disable automatic conversion from lower case to upper
      case.  If the /MX switch is not used, then all PCL4C function
      references in C code must be in upper case.

              Model    Command

              Small    MASM PCL4C /DSMALL_MODEL   /MX;
              Compact  MASM PCL4C /DCOMPACT_MODEL /MX;
              Medium   MASM PCL4C /DMEDIUM_MODEL  /MX;
              Large    MASM PCL4C /DLARGE_MODEL   /MX;

      To disable transmitter interrupts, add "/DNO_TBE" to each MASM
      command line above.

      For example, to make the (small) model PCL4C.OBJ into a library file:

               DEL PCL4C_S.LIB
               LIB PCL4C_S.LIB+PCL4C,PCL4C.MAP;

      If you are using the MIX Power C Compiler, create the MIX object file
      (you will need version 1.3 of MIX which has the /_ switch):

               MIX /_ PCL4C_S

      Similarly with the other memory model libraries.  See the batch files
      MAKE_S.BAT, MAKE_C.BAT, MAKE_M.BAT, MAKE_L.BAT, and MAKE_P.BAT.


      3.7 Using a MAKEFILE

      Makefiles are provided for all example code. Borland makefiles end
      with the extension '._B_', Turbo C makefiles with '._T_', Microsoft C
      makefiles end with '._M_', Microsoft Quick C makefiles files end with
      '._Q_', WATCOM makefiles end with '._W_', and Power C project batch
      files end with '.PRJ'.

      To compile and link SIMPLE (small model), use:

           Microsoft C:   NMAKE SIMPLE._M_
                          NMAKE SIMPLE._P_      [Pharlap 16-bit PM]
               Quick C:   QCL /AS SIMPLE.C /LINK PCL4C_S.LIB
             Borland C:   MAKER -fSIMPLE._B_
               Turbo C:   MAKE -fSIMPLE._T_
           MIX Power C:   PC/E /ms SIMPLE.C PCL4C_S.MIX
              WATCOM C:   WMAKE -f SIMPLE._W_










     PCL4C Users Manual                                        Page 13

      3.8 Using an IDE

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

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

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

         SIMPLE.EXE
         +++ SIMPLE.C
         +++ PCL4C_S.LIB

      3.8.1 Microsoft IDE

      Choose "Project", then "New". Select DOS as the target. A dialog box
      will then pop up into which the project file names are entered.

      3.8.2 Microsoft Developer

      Choose "File", then "New", then "Project Workspace". Select
      "Application" for "Type:" and your project name for "Name:". Choose
      DOS for platform. Then select "Create".

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

      3.8.3 Borland IDE

      Turn off LINKER case sensitivities: Choose "Options", "Projects",
      "Linker", "General". Turn off the "case sensitive link" and "case
      sensitive exports and imports" boxes.

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

      3.8.4 Watcom IDE

      Choose "File", then "New Project". Enter the project name and then
      choose DOS as the target. Use the INS (Insert) key to pop
      up a dialog box into which the project file names are entered.

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



     PCL4C Users Manual                                        Page 14

      4.0 Modem I/O Functions

      The file MODEM_IO.C contains several functions that ease
      communicating with your modem.  Note that the modem I/O functions are
      provided in source code form. Look at HOST.C and SESSION.C for
      examples of usage.

      4.1 ModemEcho

      Syntax: int ModemEcho(int Port, int Echo);

      The ModemEcho functions copies bytes from serial input to the display
      for 'Echo' timer tics (18.2 tics per second).

      4.2 ModemSendTo

      Syntax: int ModemSendTo(int Port, int Pace, char *Text);

      The ModemSendTo function sends the characters in the string 'Text' to
      serial output. There is a delay of 'Pace' timer tics between
      characters.

      4.3 ModemWaitFor

      Syntax: int ModemWaitFor(int Port, int Tics,
                               int CaseFlag, char *Text);

      The ModemWaitFor function waits for characters from serial input that
      match the string 'Text'. A total of 'Tics' timer tics are allowed
      before timing out and returning FALSE.  If the 'CaseFlag' is TRUE,
      then the string comparison is case sensitive.

      4.4 ModemQuiet

      Syntax: int ModemQuiet(int Port, int Tics);

      The ModemQuiet function waits for continuous quiet of 'Tics' timer
      tics before returning.  Any incoming character is echoed to the
      display and the wait begins anew.

      4.5 ModemCmdState

      Syntax: int ModemCmdState(int Port);

      The ModemCmdState sets the modem to command state, provided that your
      modem uses a guard time of 1 second and the standard 3 characters
      "+-+". Refer to your Modem manual for information on setting command
      states.

      4.6 ModemHangup

      Syntax: int ModemHangup(int Port);

      The ModemHangup command hangs up the modem by first calling
      ModemCmdState and then sending the string "ATH0".



     PCL4C Users Manual                                        Page 15

      5.0 Problems

      Before developing your application, you should run the example
      programs. They should all execute correctly.

      If you have two ports on your computer, connect them together with a
      null modem cable and run SELFTEST.C. If SELFTEST does not execute
      properly then there is something wrong with either (1) your serial
      port hardware, (2) your null modem cable, or (3) you selected ports
      that are not connected by the null modem cable.

      Another easy test is to connect the serial port to a modem, and use
      SIMPLE to send a "AT" to the modem, which should respond with a "OK".
      If you cannot get your application to run properly, first compile and
      run the example emulator program SIMPLE.

      If your application does not run but the example programs run
      correctly, then you have most likely made a programming mistake in
      your application. MarshallSoft Computing cannot debug your
      application, especially over the telephone!  However, consider each
      of the following when searching for an error in your application.

      1.  Windows interferes with hardware access by DOS programs. Boot to
      DOS before testing.

      2.  Did you link with the correct PCL4C library ?  This is the most
      probable cause if an application 'hangs' as soon as it starts and
      must be rebooted. The function SioInfo('M') returns the model ID
      under which the library was assembled.

      3.  Is the receive buffer large enough ? If you are using 1K data
      blocks in YMODEM, then your receive buffer should be 2K.

      4.  Have you selected too high a baud rate (if you are using a slow
      PC) ?  If only one COM port is being run, you should be able to run
      at 38400 baud on 8088 machines and 115200 on most 286s and above.

      5.  Are you attempting to run another application in the background ?
      Try running without any other programs running in the background.

      6.  If you are running two COM ports simultaneously, are you using
      separate receive and transmit buffers ? (you should).

      7.  Did SioReset return a zero value ?  If not, then you must call
      SioReset again. See SIMPLE.C for an example.

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

      9.  Do you have more than one COM1 port, etc.  For example, if you
      have a COM1 port on your motherboard, you cannot add another COM1
      port or modem board that uses COM1 without first disabling the COM1
      on the motherboard.

      10.  Are you passing the proper segment of the receive (and transmit)
      buffer? See SIMPLE.C for an example.


     PCL4C Users Manual                                        Page 16

      6.0 Types Of Serial Programs

      6.1 Terminal Programs

      The "terminal program" is the most common class of communications
      program.  It is used to call up a BBS or on-line service such as
      CompuServe, America On-Line, etc.  Refer to the programs SIMPLE and
      HOST in section 8 for examples of simple terminal programs.

      A more sophisticated terminal program featuring ASCII, XMODEM,
      YMODEM, and ZMODEM protocol file transfers can be found in our sister
      product -- The Personal Protocol Libray (PPL4C).  Source code is
      included in the shareware distribution for everything except ZMODEM
      and the script intepreter.

      6.2 Door Programs

      In order to write a door program which "takes over" a serial port
      without resetting the port or changing the baud rate, call SioReset
      with NORESET as the second argument rather than the baud rate. Call
      SioGetDiv to get the baud rate divisor if the baud rate must be
      determined. Be sure to call SioDone before returning to the invoking
      program.  Refer to the SPAWN.C and DOOR.C example programs.  Also be
      sure to free any memory that you may have allocated in your door
      program before exiting.

      6.3 BBS Programs

      If you are designing a BBS program (also known as HOST programs),
      consider using 16550, 16650, or 16750 UARTS.  You should also choose
      a multiport card such as the DigiBoard or BOCA board if you wish to
      run more than 4 ports simultaneously.

      If you are using an error correcting modem, then you should be sure
      to set flow control and fix your baud rate at the highest possible
      transfer rates.  For 14,400 modems, this means 19200 or 38400. You
      may need at least a 16550 UART in order to run at the higher speed.

      If you are using an older multi-speed modem (say 1200, 2400, 4800,
      9600) that doesn't use flow control, you should change your baud rate
      to match the CONNECT message baud rate.

      6.4 Communicating with Serial Devices

      If you will be communicating with a serial device (motor control,
      digitizing tablet, etc.) be sure to (1) not enable flow control
      unless you are certain that flow control is used by the serial
      device, (2) include a short delay after sending each character to the
      serial device (start with 1/4 second), and (3) set DTR and RTS since
      many devices require DTR to be set before they will respond.

      As a first step, try to communicate with the serial device using a
      terminal emulator such as SIMPLE.





     PCL4C Users Manual                                        Page 17

      7.0 Application Notes

      7.1 Running under Windows

      Windows (3.1/95/NT) virtualizes all serial ports that have been
      installed. Under Win 3.1, this can degrade serial port performance
      for DOS programs. Under Win 95/NT, DOS cannot reliably use the serial
      ports. The best solution is to use a separate serial card for use by
      DOS. Use an IRQ and base address that Windows does not use.

      7.2 Buffered UARTS

      PCL4C supports all standard unbuffered and buffers UARTS.

      The National 8250 was the UART designed for the original 8-bit
      IBM/PC. The 8250 is only suitable to 9600 - 19200 baud on IBM-PC
      class machines. It has no buffering capability.

      The National 16450 was the UART designed for 16-bit IBM AT class
      machines. It is suitable for most DOS applications up to 38400 and
      some Windows applications. It has no buffering capability.

      The National 16550 contains 16-byte FIFOs and is the minimum UART
      that should be used for most Windows applications and many serial
      intensive DOS applications. The receive FIFO trigger level can be set
      at 1, 4, 8, or 14 bytes before an interrupt is generated.

      The StarTech 16650 features 32-byte FIFOs and is suitable when high
      performance serial communications is necessary. The 16650 is also pin
      for pin compatible with the 16550 and can be run at up to 460,800
      baud. The receive FIFO trigger level can be set at 8, 16, 24, or 28
      bytes before an interrupt is generated.

      The Texas Instruments 16750 features 64-byte FIFOs and is suitable
      when high performance serial communications is necessary.  The 16750
      is NOT pin for pin compatible with the 16550 but can be run at up to
      921,600 baud. The receive FIFO trigger level can be set at 1, 16, 32,
      or 56 bytes before an interrupt is generated.

      The SioFIFO function returns an integer code which identifies the
      UART (0 for 8250/16450, 1 for 16550, 2 for 16650, and 3 for 16750)
      type. Refer to the example programs for examples of its use.

      Refer to the PCL4C Reference Manual (PCL4C_R.TXT) and the
      Serial Communications Manual (ASYNC.TXT) for more detailed
      information.












     PCL4C Users Manual                                        Page 18

      7.3 Running 3 or 4 Ports Concurrently

      PCL4C supports up to 4 serial ports running concurrently (more if you
      have a DigiBoard or BOCA board).  One free interrupt for each port is
      required.  Refer to the next section if you have a multiport board.

      Interrupts IRQ4 and IRQ3 are dedicated to the communications ports in
      a standard IBM PC/XT/AT configuration.  IRQ4 is shared between COM1
      and COM3 while IRQ3 is shared between COM2 and COM4.

      Suppose that you wish to run 3 ports simultaneously. To begin, you
      must have 3 UARTs (serial ports) installed on the computer.  Assume,
      for purposes of this discussion, that COM1 is installed on the
      motherboard, and that you have purchased a new 2 port serial
      communications board.

      You should be able to configure the first serial board port as COM2,
      which uses IRQ3.  Refer to the manual that came with your serial
      board.

      In order to run the third serial port concurrently with the first
      two, an unused interrupt must be found.  If your serial card can use
      only IRQ3 and IRQ4, then there is no way to run a third line since
      IRQ4 and IRQ3 are used for COM1 and COM2.

      However, many serial cards can use other IRQs, typically IRQ2 through
      IRQ7. Many of the newer serial cards can use IRQs through IRQ15.
      Since IRQ5 is normally used for a second printer port, it is a good
      candidate for COM3.  To use IRQ5 for the third serial port, first set
      your serial card to use IRQ5 for COM3 (refer to your serial card
      manual) and then add the following line to your applications code
      before calling SioReset:

                SioIRQ(COM3,IRQ5);

      Don't forget to disable any device that might use IRQ5, such as a
      second printer port or a music card.  Unfortunately, there is no easy
      way to determine that you have no conflicts until you actually
      attempt to use the IRQ.  If there are conflicts, your system will
      probably hang and you will have to reboot.

      To run a fourth serial port, another free IRQ must be found.  On some
      systems, IRQ7 can be used. To use IRQ7 for the fourth serial port,
      first set your serial card to use IRQ7 for COM4 and then add:

                SioIRQ(COM4,IRQ7);

      Also note that conflicts are possible with port addresses. You cannot
      have two cards using the same port address. This problem most often
      occurs when adding a multiport board since each UART uses 8
      consecutive port addresses.

      Of course, you can select any IRQ and UART address that your serial
      card can physically use.




     PCL4C Users Manual                                        Page 19

      7.4 Transmitter Interrupts

      PCL4C comes assembled for all memory models with transmitter
      interrupts enabled (PCL4C_?.LIB) and also with transmitter interrupts
      disabled (PCL4C_?1.LIB), where '?' is the memory model (S,M,C,L,P).

      When transmitter interrupts are NOT enabled, the following logic
      occurs everytime SioPutc or SioPuts is called:

      1.  Wait for the UART transmit buffer to become empty.  The UART
      transmit buffer may not be empty if the previous transmit is not
      completed (the UART breaks down the byte & sends 1 bit at a time).

      2.  When the UART transmit buffer is empty, the byte from the SioPutc
      or SioPuts call is loaded into the UART transmit buffer and control
      is returned to the caller.

      Transmitter interrupts provide a way for an application program to
      write to the serial port faster than the baud rate, but transmitter
      interrupts do have several caveats.  To begin, they are slower than
      polled transmission, although not significantly.  Secondly, they are
      more complex and thus result in a slightly larger library.

      The increased complexity of transmitter interrupts is due to the fact
      that even though transmitter interrupts are enabled, a transmitter
      interrupt can occur only when the UART transmitter register
      transitions from not-empty to empty (a byte has just been
      transmitted). To start the transmitter interrupt process, the first
      byte in the PCL4C transmitter queue must be transmitted by SioPutc
      (or SioPuts) rather than by the Interrupt Service Routine (ISR). The
      remainder of the bytes in the PCL4C transmit queue are transmitted by
      the ISR when the transmitter interrupt occurs.  This process is
      called "kickstarting" the transmitter interrupts.

      When transmitter interrupts are enabled, the following logic occurs
      everytime SioPutc or SioPuts is called:

      1.  The byte from SioPutc or bytes from SioPuts are put into the
      PCL4C transmitter queue.

      2.  If there is no byte presently being transmitted, then the
      transmitter interrupt process is kickstarted.

      3.  Each time a transmitter interrupt occurs, the ISR gains control,
      removes the next byte from the PCL4C transmitter queue and puts it in
      the UART transmit register.

      While you can now call SioPutc and SioPuts faster than the baud rate,
      bytes are still transmitted at the given baud rate. The advantage of
      using transmitter interrupts is that an application program can write
      a string of bytes to the serial transmit queue without having to wait
      for those bytes to be transmitted before regaining control.

      When running a streaming protocol (one that doesn't wait for any
      acknowledgement from the other side), be sure to check for
      transmitter buffer overflow (eg, SioPutc returns -1).


     PCL4C Users Manual                                        Page 20

      8.0 Using Multiport Cards

      8.1 The DigiBoard

      PCL4C supports the DigiBoard PC/4, PC/8, and "Classic". In order to
      use the DigiBoard, you must configure PCL4C using the SioPorts,
      SioUART, and SioIRQ functions.

      Your PC's ports must be partitioned into "standard" PC ports and dumb
      card ports.  Remember that standard PC ports cannot share IRQs like
      the DigiBoard (or BOCA board) can. If you are using IRQ4 and IRQ3 for
      standard PC ports COM1 and COM2, then you cannot use either for
      DigiBoard ports (try IRQ5 or IRQ7).

      Suppose that COM1 through COM2 are standard PC ports (using IRQ4 and
      IRQ3) and you have installed a PC/8 DigiBoard that you wish to use
      for COM3 through COM10 using interrupt line IRQ5.  You choose to use
      the recommended DigiBoard UART addresses starting at 0x100:

      +-------------------------------------------------------------------+
      | SioPorts(10,COM3,0x140,DIGIBOARD);/* COM3 = 1st DigiBoard port */ |
      | Address = 0x100;                  /* 1st DigiBoard UART address */|
      | for(Port=COM3;Port<=COM10;Port++) /* look at each port */         |
      |   {SioUART(Port,Address);         /* set the UART address */      |
      |    Address += 8;                  /* compute next address */      |
      |    SioIRQ(Port,IRQ5);             /* set the DigiBoard IRQ */     |
      |   }                                                               |
      +-------------------------------------------------------------------+

      The DigiBoard uses 0x140 for the status address for odd interrupts
      and 0x141 for even interrupts.

      DigiBoard may be contacted at 612-943-9020, FAX 612-943-5398, or web
      site http://www.digiboard.com.

      8.2 The BOCA Board

      PCL4C supports the dumb BOCA board and compatibles.  As with the
      DigiBoard, you must configure PCL4C before using the BOCA board.

      For example, to configure the BOCA BB2016 to use COM1 to COM16, with
      base addresses starting at 0x100 and IRQ5:

      +-------------------------------------------------------------------+
      | SioPorts(16,COM1,0x107,BOCABOARD);/* COM3 = 1st BOCA board port */|
      | Address = 0x100;                  /* 1st BOCA UART address */     |
      | for(Port=COM1;Port<=COM16;Port++) /* look at each port    */      |
      |   {SioUART(Port,Address);         /* set the UART address */      |
      |    Address += 8;                  /* compute next address */      |
      |    SioIRQ(Port,IRQ15);            /* set the BOCA IRQ */          |
      |   }                                                               |
      +-------------------------------------------------------------------+

      BOCA may be contacted 407-241-8088, FAX 407-997-0918, web site
      http://www.bocaresearch.com.



     PCL4C Users Manual                                        Page 21

      9.0 Example Programs

      Nine example programs are included with PCL4C.  In addition, the
      Personal Protocol Library for C (PPL4C) includes the terminal program
      TERM which features ASCII, XMODEM, YMODEM, and ZMODEM protocols.
      Complete source code is included in the shareware product for all of
      the protocols above except ZMODEM.  In order to get ZMODEM source,
      PPL4C must be registered.

      Two example programs (SIMPLE and SELFTEST) can also be compiled as
      16-bit protected mode programs.

      9.1 MINIMAL

      MINIMAL is the simplest possible communications program. It displays
      on the screen what it reads from the serial port and transmits over
      the serial line what is typed at the keyboard.

      COM1 and 9600 baud are hard coded for simplicity. MINIMAL cannot talk
      to a modem since it does not assert DTR.

      9.2 SIMPLE

      SIMPLE is a simple terminal program. It operates like MINIMAL, except
      that both a port and a baud rate can be specified. Use SIMPLE to
      talk to your modem or other serial device. For example.

           SIMPLE 1 9600

      SIMPLE.C may also be compiled as a 16-bit protected mode program. See
      SIMPLE16.

      9.3 HOST

      HOST is a simple one-line BBS program. Its purpose is to provide a
      structure for developing more sophisticated BBS programs. To start
      HOST for COM1 at 38400 baud, type:

           HOST 1 38400

      9.4 SPAWN and DOOR

      The SPAWN program is the same as the SIMPLE program except that it
      spawns DOOR when the user types a '$'. For example, to start SPAWN on
      COM3, type

           SPAWN 3

      The DOOR program is also the same as SIMPLE except that it can "take
      over" a serial port without changing any of the port parameters.
      Exiting DOOR returns to the invoking program (SPAWN).

      9.5 FINDER

      The FINDER.C program searches for connected modems. Connect a modem
      to one of the serial ports, turn the modem on, then type FINDER.


     PCL4C Users Manual                                        Page 22

      9.6 SELFTEST

      The SELFTEST.C (and SELF16.C) program is designed to test serial
      ports provided that one port (with a loopback adapter) or two ports
      (connected together with a null-modem adapter) are available.
      SELFTEST can also be used to test a multiport board.

      For example, to test PC port COM1 against COM2, type:

           SELFTEST PC 1 2

      SELFTEST may need to be configured for non-standard PC ports or
      multiport boards. Refer to the SELFTEST.C source code for details.

      9.7 FIFOTEST

      The FIFOTEST program is used to test the functionality of the UART
      FIFO (16550, 16650, & 16750 only) by counting interrupts and
      calculating the number of bytes moved per interrupt.

      Since both the 16650 and the 16750 require additional programming
      beyond what is required with the 16550 UART to enable the larger
      capacity FIFOs (32 bytes for the 16650 and 64 bytes for the 16750),
      this program is a practical method for verifying that the larger
      capcity FIFOs are indeed enabled.

      For example, to test COM3, type:

           FIFOTEST PC 3

      FIFOTEST may need to be configured for non-standard PC ports or for
      multiport boards. Refer to the FIFOTEST.C source code for details.

      9.8 TESTER

      The TESTER program is used to test the throughput from one computer
      to another and back again, using either a null modem cable or modems.
      TESTER requires that the other computer echos everthing back that is
      receives. For example, to send a 100 byte test packet out COM1 (and
      receive it back) at 19200 baud, type:

          TESTER 1 19200 100

      9.9 RS485

      The RS485.C program is similar to SIMPLE except that it uses RTS
      control of the UART transmitter in a 2-wire RS485 connection. For
      example, to use COM4 at 19200, type

          RS485 4 19200

      Refer to Serial Communications Manual (ASYNC.TXT) for more information
      on RS485.





     PCL4C Users Manual                                        Page 23

      10.0 Legal Issues

      10.1 Registration

      If you wish to register the PCL4C library , please send $85 plus $7
      S&H ($12 outside of North America) to:

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

      The $85 price is good for one year from the date on the title page of
      the manual. Call for the current price after one year.

      Multiple copies are discounted when ordered at the same time. The
      second copy is discounted 25%, the third discounted 30%, the fourth
      35%, and 5 or more are discounted 40%. A site license is also
      available for $995 (includes 20 sets of printed documentation). We
      pay shipping.

      We accept American Express, Discover, MasterCard, and VISA (account
      number, expiration date, exact name on your card, and complete card
      billing address required), checks in US dollars drawn on a US bank,
      purchase orders (POs) from recognized US schools and companies listed
      in Dun & Bradstreet, and COD (street address and phone number
      required) within the USA (plus an additional $5.00 COD charge).

      A secure server is available for processing credit card orders on our
      internet web site at http://www.marshallsoft.com.

      You can also order PCL4C from The Public Software Library (PSL) in
      Houston Texas with your American Express, MasterCard, VISA, or
      Discover card by calling 800-242-4PSL (from overseas: 713-524-6394)
      or by FAX at 713-524-6398. THESE NUMBERS ARE FOR ORDERING ONLY. The
      product number for PCL4C is 10908. Please have your credit card
      billing address ready.

      If you wish to update from an older version of PCL4C, send $30 plus
      $7 S&H ($12 outside of North America).  Updates must be ordered
      directly from MarshallSoft Computing.

      The registered package includes:

         o  Small, Compact, Medium, Large, and 16-bit Protected mode.
         o  COM1 thru COM20 supported for all libs.
         o  Assembler source code for the library.
         o  Printed Users and Reference Manuals.
         o  Email and Telephone support for one year.

      Print the file INVOICE.TXT if an invoice is needed. The registered
      user will receive the latest version of PCL4C shipped by two day
      priority mail (packet airmail overseas).  A 3.5" HD diskette is
      provided.





     PCL4C Users Manual                                        Page 24

      10.2 License

      MarshallSoft Computing, Inc. grants the registered user of PCL4C the
      right to use one copy of the PCL4C library (in object form) on a
      single computer in the development of any software product (other
      than libraries such as PCL4C).  The user may not use the library on
      more than one computer at the same time.  The source code for the
      library (PCL4C.ASM) is copyrighted by MarshallSoft Computing and may
      not be released in whole or in part.

      Products developed using the registered version of PCL4C may include
      the object form of the library and may be distributed royalty free.

      Under no circumstances can PCL4C be used for any commercial purpose
      without registration.

      10.3 Warranty

      MARSHALLSOFT COMPUTING, INC.  DISCLAIMS ALL WARRANTIES RELATING TO
      THIS SOFTWARE, WHETHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT
      LIMITED TO ANY IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
      A PARTICULAR PURPOSE, AND ALL SUCH WARRANTIES ARE EXPRESSLY AND
      SPECIFICALLY DISCLAIMED.  NEITHER MARSHALLSOFT COMPUTING, INC. NOR
      ANYONE ELSE WHO HAS BEEN INVOLVED IN THE CREATION, PRODUCTION, OR
      DELIVERY OF THIS SOFTWARE SHALL BE LIABLE FOR ANY INDIRECT,
      CONSEQUENTIAL, OR INCIDENTAL DAMAGES ARISING OUT OF THE USE OR
      INABILITY TO USE SUCH SOFTWARE EVEN IF MARSHALLSOFT COMPUTING, INC.
      HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES OR CLAIMS. IN NO
      EVENT SHALL MARSHALLSOFT COMPUTING, INC.'S LIABILITY FOR ANY SUCH
      DAMAGES EVER EXCEED THE PRICE PAID FOR THE LICENSE TO USE THE
      SOFTWARE, REGARDLESS OF THE FORM OF THE CLAIM.  THE PERSON USING THE
      SOFTWARE BEARS ALL RISK AS TO THE QUALITY AND PERFORMANCE OF THE
      SOFTWARE.

      Some states do not allow the exclusion of the limit of liability for
      consequential or incidental damages, so the above limitation may not
      apply to you.

      This agreement shall be governed by the laws of the State of Alabama
      and shall inure to the benefit of Marshallsoft Computing, Inc.  and
      any successors, administrators, heirs and assigns.  Any action or
      proceeding brought by either party against the other arising out of or
      related to this agreement shall be brought only in a STATE or FEDERAL
      COURT of competent jurisdiction located in Madison County, Alabama.
      The parties hereby consent to in personam jurisdiction of said courts.













     PCL4C Users Manual                                        Page 25

      11.0 Summary

      11.1 Revision History

      Version 1.0 - 14 January 1991 - original release.

      Version 1.1 - 11 March 1991
         o  Added SioUnGetc function to library.

      Version 1.2 - 1 June 1991
         o  SioParms bug - could not call before SioReset.
         o  SioReset bug - was not saving & restoring all regs.

      Version 1.3 - 1 July 1991
         o  Added NORESET option to SioReset.
         o  Added SioDSR, SioCTS, SioDCD, SioLoopBack, and SioRI.

      Version 2.0 - 1 Nov 1991
         o  Reorganized as four memory model libraries.
         o  Added SioModel function to library.
         o  Added support for Quick C and Power C.

      Version 2.1 - 1 Dec 1991
         o  Fixed bug due to Microsoft Assembler (MASM 5.0,5.1) error.

      Version 3.0 - 15 Jan 1992
         o  Added SioUART function.
         o  Added "UART undefined" error code.
         o  Added "Bad or missing UART" error code.
         o  Added "Port already enabled" error code.
         o  Added "Cannot enable both COM1 & COM3 ..." error code.
         o  Fixed several minor bugs (using new automated testing).

      Version 3.1 - 1 March 1992
         o  Added SioFIFO (INS16550 support).
         o  Added SioIRQ function.
         o  Increased maximum receive buffer size to 32K bytes.

      Version 3.2 - 1 May 1992
         o  Modified SioReset so that it no longer clears DTR & RTS.
         o  Modified SioModel & renamed to SioInfo.
         o  Fixed bug in SioDone when using 2 ports simultaneously.
         o  Added SioFlow to library.
         o  Added YMODEM-G protocol to TERM program.

      Version 3.3 - 3 August 1992
         o  Fixed bug in SioUnGet when using 2 ports simultaneously.
         o  Add SioRead function.

      Version 3.4 - 4 Jan 1993
         o  Library modified to use up to four ports simultaneously.
         o  SioIRQ was modified to include a third argument.
         o  EXAMPORT utility distributed to registered users.





     PCL4C Users Manual                                        Page 26

      11.1 Revision History (continued)

      Version 3.5 - 15 May 1993
         o  Supports dumb DigiBoards (PC/4 and PC/8).
         o  Two new error traps added ("No such IRQ" & "No such ISR").
         o  ASCII file transfer protocol added to TERM (with XON/XOFF).

      Version 4.0 - 18 Oct 1993
         o  The library supports transmitter interrupts.
         o  Corrects bug in Ver 3.5 requiring calling SioIRQ for COM3/4.
         o  All example code compiles with supported C++ compilers.
         o  The SioIRQ function has been simplified.

      Version 4.1 - 1 May 1994
         o  Transmitter FIFO enabled.
         o  Minor internal modifications.
         o  Supports dumb BOCA boards (BB1004, BB1008, & BB2016).
         o  Port definition extented to COM16.

      Version 4.2 - 1 Sept 1994
         o  A flow control bug was fixed.
         o  SioGetDiv function added.
         o  SioRxBuf & SioTxBuf function modified.

      Version 4.3 - 15 March 1995
         o  BREAK detection bug fixed.
         o  Port definitions extended to COM20.
         o  Support for IRQ8 through IRQ15.
         o  Line status bits preserved.

      Version 5.0 - 20 November 1995
         o  Supports Protected Mode.
         o  Renamed SioRxFlush to SioRxClear & SioTxFlush to SioTxClear.
         o  Added (new) SioTxFlush.
         o  Added more choices in SioInfo.
         o  Removed SioCrtWrite (use putch instead).
         o  Removed SioKeyPress (use kbhit instead).
         o  Removed SioKeyRead  (use getch instead).
         o  Added SioGets & SioPuts.

      Version 6.0 - 21 October 1996
         o Only force 15 bytes (not 16) into TX side FIFO.
         o Handles simultaneous BOCA interrupts under all conditions.
         o Added 32-bit library.

      Version 6.1 - 8 December 1997
         o Supports user selectable baud rates. See SioSetDiv().
         o Supports the (StartTech) 16650 & (TI) 16750 UARTs.
         o Supports 16-bit Pharlap DOS extender.
         o FINDER and FIFOTEST example programs added.
         o Dropped 32-bit protected mode [for lack of compiler support].

      Version 6.2 - 28 January 1999
         o RX queue will accept bytes even if CTS is down.
         o SioEmpty function added.
         o TESTER and RS485 example programs added.


     PCL4C Users Manual                                        Page 27

      11.2 Function Summary

      Refer to the PCL4C Reference Manual (PCL4C_U.TXT) for detailed
      information on the communications and support functions.  A one line
      summary of each function follows:

      SioBaud     Sets the baud rate of the selected port.
      SioBrkKey   Returns non-zero if the Control-BREAK key was pressed.
      SioBrkSig   Asserts, cancels, or detects BREAK signal.
      SioCTS      Reads the Clear to Send (CTS) modem status bit.
      SioDCD      Reads the Data Carrier Detect (DCD) modem status bit.
      SioDelay    Delays one or more tics (18 tics per second).
      SioDone     Terminates further serial processing.
      SioDSR      Reads the Data Set Ready (DSR) modem status bit.
      SioDTR      Set, clear, or read the Data Terminal Ready (DTR) bit.
      SioEmpty    Waits for UART transmitter to send last bit.
      SioError    Displays error in text.
      SioFIFO     Sets the interrupt level for the 16550/16650/16750.
      SioFlow     Enables / disables hardware flow control.
      SioGetc     Reads the next character from the serial line.
      SioGetDiv   Reads the baud rate divisor registers.
      SioGets     Reads a buffer of characters from the serial line.
      SioInfo     Returns library information (version number, etc.)
      SioIRQ      Assigns an IRQ line to a port.
      SioLine     Reads the line status register.
      SioLoopBack Performs a UART loopback test.
      SioModem    Reads the modem status register.
      SioParms    Sets parity, stop bits, and word length.
      SioPorts    Sets # ports, 1st DigiBoard / BOCA port & status reg.
      SioPutc     Transmits a character over a serial line.
      SioPuts     Transmits a buffer of characters over a serial line.
      SioRead     Reads any of 7 UART ports.
      SioReset    Initialize a serial port for processing.
      SioRI       Reads the Ring Indicator (RI) modem status bit.
      SioRTS      Sets, clears, or reads the Request to Send (RTS) line.
      SioRxBuf    Sets up receive buffer.
      SioRxClear  Clears the receive buffer.
      SioRxQue    Returns the number of characters in the receive queue.
      SioSetDiv   Sets the divisor for the user baud rate.
      SioTimer    Returns the number of system clock tics.
      SioTxBuf    Sets up transmit buffer.
      SioTxClear  Clears the transmit buffer.
      SioTxFlush  Restarts transmitter interrupts thus flushing the TX queue.
      SioTxQue    Returns the number of characters in the transmit queue.
      SioUART     Sets the UART base address.
      SioUnGetc   "Un-gets" (puts back) a specified character.

      11.3 Further Reading

      The best way to learn about serial communications is to read a good
      book on the subject. Several good texts are available.  Two that I
      like are:

      (1) C Programmers's Guide to Serial Communications by Joe Campbell
      (SAMS)
      (2) Mastering Serial Communications by Peter Gofton (SYBEX).


     PCL4C Users Manual                                        Page 28

