


                         Personal Communications Library

                                 For PowerBASIC


                                     (PCL4PB)


                                 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
                          Anon FTP : ftp.marshallsoft.com /marshallsoft
                               web : www.marshallsoft.com



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



      MARSHALLSOFT is a trademark of MarshallSoft Computing, Inc.




     PCL4PB 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 MODEM_IO functions.........................................10
           3.1 ModemEcho..............................................10
           3.2 ModemSendTo............................................10
           3.3 ModemWaitFor...........................................10
           3.4 ModemQuiet.............................................10
           3.5 ModemCmdState..........................................10
           3.6 ModemHangup............................................10
       4.0 Problems...................................................11
       5.0 Types of Serial Programs...................................12
           5.1 Terminal Programs......................................12
           5.2 Door Programs..........................................12
           5.3 BBS Programs...........................................12
           5.4 Communication with Serial Device.......................12
       6.0 Application Notes..........................................13
           6.1 Running under Windows..................................13
           6.2 Buffered UARTs.........................................13
           6.3 Running 3 or 4 Ports Concurrently......................14
           6.4 Transmitter Interrupts.................................15
       7.0 Using Multiport Cards......................................16
           7.1 Digiboards.............................................16
           7.2 BOCA Boards............................................16
       8.0 Example Programs...........................................17
       9.0 Legal Issues...............................................19
           9.1 Registration...........................................19
           9.2 License................................................20
           9.3 Warranty...............................................20
      10.0 Summary....................................................21
           10.1 Revision History......................................21
           10.2 Function Summary......................................22
           10.3 Further Reading.......................................22










     PCL4PB Users Manual                                        Page 2

      1.0 Introduction

      The Personal Communications Library for PowerBASIC (PCL4PB) is an
      asynchronous communications library designed for experienced software
      developers programming in PowerBASIC, version 3.0c and above. An IBM
      PC/XT/AT or compatible is required.  The PCL features:

          o User selectable baud rates.
          o 38 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 (PPL4PB).

      Why should you buy PCL4PB ?  Several good reasons are:

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

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

            FAST - PCL4PB 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 PCL4PB for a very reasonable price!

        UPGRADES - Once you buy PCL4PB, 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).





     PCL4PB Users Manual                                        Page 3

      1.1 User Support

      We want our customers to be successful in developing applications
      using PCL4PB! 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 PCL4PB, 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@marshallsot.com


      However, we can only answer questions with respect to using the
      PCL4PB 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 PCL4PB 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.





     PCL4PB Users Manual                                        Page 4

      1.3 A Typical Application

      The following code is the complete MINIMAL.BAS program. It talks on
      COM1 at 2400 baud. The code is as follows:

      +--------------------------------------------------------+
      |  '                                                     |
      |  '  MINIMAL.BAS:  Talk on COM1 @ 2400 baud             |
      |  '                                                     |
      |  $ERROR ALL ON                                         |
      |  $LIB ALL OFF                                          |
      |  $LINK "PCL4PB.OBJ"                                    |
      |  $INCLUDE "PCL4PB.BI"                                  |
      |  DIM Buffer(256+16) AS BYTE                            |
      |  DIM BufSeg AS WORD                                    |
      |  DIM Code AS INTEGER                                   |
      |  'Reset port                                           |
      |  BufSeg = 1 +VARSEG(Buffer(0)) +(VARPTR(Buffer(0))\16) |
      |  Code = SioRxBuf(%COM1, BufSeg, %Size256)              |
      |  Code = SioReset(%COM1, %Baud2400)                     |
      |  DO                                                    |
      |    'Anything incoming ?                                |
      |    Code = SioGetc(%COM1, 1)                            |
      |    IF Code = 13 THEN                                   |
      |      PRINT                                             |
      |    ELSEIF Code >= &H20 THEN                            |
      |      PRINT CHR$(Code);                                 |
      |    END IF                                              |
      |    'Anything to send ?                                 |
      |    AnyKey$ = INKEY$                                    |
      |    IF AnyKey$ <> "" THEN                               |
      |      'Exit if user types Escape (ESC=27)               |
      |      IF AnyKey$ = CHR$(27) THEN EXIT DO                |
      |      Code = SioPutc(%COM1,ASC(AnyKey$))                |
      |    END IF                                              |
      |  LOOP                                                  |
      |  Code = SioDone(%COM1)                                 |
      |  END                                                   |
      |                                                        |
      +--------------------------------------------------------+


      A slightly more capable program SIMPLE.BAS is in the distribution
      archive. If can be compiled by typing

         pbc -ODV simple.bas

      or choosing Open from the File menu in the IDE, and then selecting
      SIMPLE.BAS.









     PCL4PB Users Manual                                        Page 5

      1.4 Installation

      (1) Before installation of PCL4PB, your PowerBASIC compiler should
      already be installed on your system and tested.

      Each test program can be compiled either from within the integrated
      development environment or by using a command file.  For example,
      the SIMPLE application can be compiled either by choosing SIMPLE.BAS
      from the IDE or by typing SIMPLE_ which invokes the command line
      compiler.

      (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 hard
      disk).  For example, to create a work directory named PCL4PB, we
      first log onto the work disk and then type:

                       MKDIR PCL4PB

      (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 PCL4PB
                      COPY A:*.*

      (5) Compile SIMPLE.BAS.  To use the integrated development
      environment (IDE), simply choose SIMPLE.BAS from the File menu, then
      Open, and choose SIMPLE.BAS.

      You can also use the command line compiler by typing SIMPLE_.

      (6) 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 your port to a modem. Transmitting an "AT" to the modem
      should result in an "OK" being received.

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
















     PCL4PB Users Manual                                        Page 6

      2.0 Library Organization

      The PCL4PB library is organized into six categories of functions.
      Refer to the PCL4PB Reference Manual (PCL4PB_R.TXT) for details on
      individual functions, and the Serial Communications Manual
      (ASYNC.TXT) for details on UARTs and RS-232 pin definition.

      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.



     PCL4PB 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    : Sets, clears, or reads 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 the last bit is transmitted by the UART.

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

      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  : "Ungets" (puts back) a specified character.


     PCL4PB 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 PCL4PB function (every PCL4PB function returns a code).

      SioBrkKey   : Returns NOT 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 PCL4PB Reference Manual (PCL4PB.TXT) for information on
      particular functions.




























     PCL4PB Users Manual                                        Page 9

      3.0 MODEM_IO Functions

      The file MODEM_IO.BAS contains several functions that ease
      communicating with your modem.  Look in the SIMPLE.BAS code for
      examples of their use.

      3.1 ModemEcho

      Syntax: FUNCTION ModemEcho(Port,Echo)

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

      3.2 ModemSendTo

      Syntax: FUNCTION ModemSendTo(Port,Pace,Text$)

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

      3.3 ModemWaitFor

      Syntax: FUNCTION ModemWaitFor(Port,Tics,CaseFlag,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.

      3.4 ModemQuiet

      Syntax: FUNCTION ModemQuiet(Port,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.

      3.5 ModemCmdState

      Syntax: FUNCTION ModemCmdState(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.

      3.6 ModemHangup

      Syntax: FUNCTION ModemHangup(Port)

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





     PCL4PB Users Manual                                        Page 10

      4.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.PAS. 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.  Is the receive buffer large enough ? If you are using 1K data
      blocks in YMODEM, then your receive buffer should be at least 1K (2K
      if baud rates above 19200 are to be used).

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

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

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

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

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

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

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






     PCL4PB Users Manual                                        Page 11

      5.0 Types Of Serial Programs

      5.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 Library for PowerBASIC (PPL4PB).
      Source code is included in the shareware distribution for everything
      except ZMODEM and the script interpreter.

      5.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 DOOR.BAS example programs.  Also be sure to
      free any memory that you may have allocated in your door program
      before exiting.

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

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





     PCL4PB Users Manual                                        Page 12

      6.0 Application Notes

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

      6.2 Buffered UARTS

      PCL4PB 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 PCL4PB Reference Manual (PCL4PB_R.TXT) and the
      Serial Communications Manual (ASYNC.TXT) for more detailed
      information.












     PCL4PB Users Manual                                        Page 13

      6.3 Running 3 or 4 Ports Concurrently

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




     PCL4PB Users Manual                                        Page 14

      6.4 Transmitter Interrupts

      PCL4PB comes assembled with transmitter interrupts enabled
      (PCL4PB.LIB) and also with transmitter interrupts disabled
      (PCL4PB1.LIB).

      When transmitter interrupts are NOT enabled, the following logic
      occurs every time SioPutc 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
      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 PCL4PB transmitter queue must be transmitted by SioPutc
      rather than by the Interrupt Service Routine (ISR). The remainder of
      the bytes in the PCL4PB transmit queue are transmitted by the ISR
      when the transmitter interrupt occurs.  This process is called
      "kick starting" the transmitter interrupts.

      When transmitter interrupts are enabled, the following logic occurs
      every time SioPutc is called:

      1.  The byte from SioPutc are put into the PCL4PB 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 PCL4PB transmitter queue and puts it in
      the UART transmit register.

      While you can now call SioPutc 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).



     PCL4PB Users Manual                                        Page 15

      7.0 Using Multiport Cards

      7.1 The DigiBoard

      PCL4PB supports the DigiBoard PC/4 and PC/8. However, you must first
      configure PCL4PB 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:

      +----------+--------------------------------------------------------+
      |  DEFINT A-Z                                                       |
      |  RC = SioPorts(8,COM1,&H140,DIGIBOARD)  'COM1 = 1st BOCA port     |
      |  Address = &H100                        '1st BOCA UART address    |
      |  FOR Port=COM1 TO COM8                  'look at each port        |
      |    RC = SioUART(Port,Address)           'set the UART address     |
      |    Address = Address + 8                'compute next address     |
      |    RC = SioIRQ(Port,IRQ5)               'set the BOCA IRQ         |
      |  NEXT I                                                           |
      +-------------------------------------------------------------------+

      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.

      7.2 The BOCA Board

      PCL4PB supports the dumb BOCA board and compatibles.  As with the
      DigiBoard, you must configure PCL4PB 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:

      +-----------+-------------------------------------------------------+
      |   DEFINT A-Z                                                      |
      |   RC = SioPorts(16,COM1,&H107,BOCABOARD) 'COM1 = 1st BOCA port    |
      |   Address = &H100                        '1st BOCA UART address   |
      |   FOR Port=COM1 TO COM16                 'look at each port       |
      |     RC = SioUART(Port,Address)           'set the UART address    |
      |     Address = Address + 8                'compute next address    |
      |     RC = SioIRQ(Port,IRQ5)               'set the BOCA IRQ        |
      |   NEXT I                                                          |
      +-------------------------------------------------------------------+

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


     PCL4PB Users Manual                                        Page 16

      8.0 Example Programs

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

      8.1 SIMPLE

      SIMPLE is a simple terminal program. It displays all incoming serial
      characters on the display, and transmits any characters typed on the
      keyboard. To run SIMPLE on COM1 at 9600 baud, type

         SIMPLE 1 9600

      Connect your serial port to a modem, and run SIMPLE. If you type
      "AT", you should receive an "OK" back from the modem.

      8.2 LOGIN

      LOGIN is programmed to dial our support BBS (no longer available)
      and log on as GUEST.  Start LOGIN like SIMPLE by providing a COM
      port and a baud rate. For example,

         LOGIN 1 38400

      8.3 DOOR

      The DOOR program is a simple communications program which can "take
      over" a serial port.  For example, say you are running PROCOMM,
      PCPLUS, or any communications program with a DOS gateway.  Select the
      DOS gateway from PROCOMM (or whatever) and then type

         DOOR 1

      at the DOS prompt to take over port COM1.

      8.4 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 (baud rate is hard-coded at 19200), type:

         HOST 1

      8.5 FINDER

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

         FINDER

      to search serial ports COM1 through COM4 for the modem.



     PCL4PB Users Manual                                        Page 17

      8.6 SELFTEST

      The SELFTEST program is designed to test a serial port terminated
      with a loopback adapter (see LOOPBACK.TXT) or by using a modem.
      SELFTEST can also be used to test a multiport board.

      For example, to test PC port COM1, type:

         SELFTEST PC 1

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

      Be sure to boot to DOS before running SELFTEST since running under
      Windows prevents accurate results.

      8.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
      capacity 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.BAS source code for details.

      Be sure to boot to DOS before running FIFOTEST since FIFO levels
      cannot be set under Windows.

      8.8 COMTYPE

      COMTYPE is a simple program that lists the UART type (8250/16450,
      16550, 16650, 16750) for COM1 through COM4. Just type (w/o arguments)

         COMTYPE

      8.9 RS485

      Similar to SIMPLE except for RS385 rather than RS232 ports.

      8.10 PUTS

      Same as SIMPLE but can send using SioPuts.






     PCL4PB Users Manual                                        Page 18

      9.0 Legal Issues

      9.1 Registration

      If you wish to register the PCL4PB 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. The shipping
      and handling charge includes the cost of the printed manuals.

      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 PCL4PB 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 PCL4PB is 15238. Please have your credit card
      billing address ready.

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

      The registered package includes:

         o  COM1 thru COM20 supported for all libs.
         o  Assembler source code for the library.
         o  Printed Users and Reference Manuals.
         o  Printed ASYNC and Products 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 PCL4PB shipped by two day
      priority mail (packet airmail overseas).  A 3.5" HD diskette is
      provided.




     PCL4PB Users Manual                                        Page 19

      9.2 License

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

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

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

      9.3 Warranty

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

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

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













     PCL4PB Users Manual                                        Page 20

      10.0 Summary

      10.1 Revision History

      Version 4.2 - 1 Sept 1994

      This was the first release of the BASIC language version of our
      library. (Lib is identical to that used by C/C++, version 4.2).

      Version 4.3 - 25 April 1995

         o  BREAK detection bug fixed.
         o  Port definitions extended to COM20.
         o  Support for IRQ8 through IRQ15.
         o  Line status bits preserved.

      Internal Version [PB version not released]

         o  Renamed SioRxFlush to SioRxClear.
         o  Renamed SioTxFlush to SioTxClear.
         o  Added SioTxFlush
         o  Added more choices in SioInfo.
         o  Only force 15 bytes (not 16) into TX side FIFO.
         o  Handles simultaneous BOCA interrupts under all conditions.

      Version 6.1 - 22 December 1997

         o  Supports user selectable baud rates. See SioSetDiv.
         o  Supports the (StarTech) 16650 & (TI) 16750 UARTs.
         o  HOST, FINDER, FIFOTEST & COMTYPE example programs added.

      Version 6.2 - 28 January 1999

         o  Added SioGets and SioPuts functions.
         o  RX queue will accept bytes even if CTS is down.
         o  SioEmpty function added.
         o  RS485.BAS example program added.





















     PCL4PB Users Manual                                        Page 21

      10.2 Function Summary

      Refer to the PCL4PB Reference Manual (PCL4PB_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, 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.

      10.3 Further Reading

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

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


     PCL4PB Users Manual                                        Page 22

