


                       Personal Communications Library

                             For PowerBASIC


                                 (PCL4PB)



                             REFERENCE 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 Reference Manual                                   Page 1

                            C O N T E N T S



        Chapter                                     Page

        Table of Contents.............................2
        Introduction..................................3
           SioBaud....................................4
           SioBrkKey..................................4
           SioBrkSig..................................5
           SioCTS.....................................5
           SioDCD.....................................6
           SioDelay...................................6
           SioDone....................................7
           SioDSR.....................................7
           SioDTR.....................................8
           SioEmpty...................................8
           SioError...................................9
           SioFIFO....................................9
           SioFlow...................................10
           SioGetc...................................10
           SioGets...................................11
           SioGetDiv.................................11
           SioInfo...................................12
           SioIRQ....................................12
           SioLine...................................13
           SioLoopBack...............................13
           SioModem..................................14
           SioParms..................................14
           SioPorts..................................15
           SioPutc...................................15
           SioPuts...................................16
           SioRead...................................16
           SioReset..................................17
           SioRI.....................................17
           SioRTS....................................18
           SioRxBuf..................................18
           SioRxClear................................19
           SioRxQue..................................19
           SioSetDiv.................................20
           SioTimer..................................20
           SioTxBuf..................................21
           SioTxClear................................21
           SioTxFlush................................22
           SioTxQue..................................22
           SioUART...................................23
           SioUnGetc.................................23
        Function Summary.............................24
        Error Code Summary...........................25
        Code Examples................................26







     PCL4PB Reference Manual                                   Page 2

                          Introduction

      This manual lists all of the PCL4PB functions in alphabetical order.
      Every library function will return a value as follows:

      1. Negative values for error conditions. See last page of this
         manual for a list of error values and their meanings.
      2. Non-negative values when returning data (eg: SioLine).
      3. Zero otherwise.

      When debugging an application, be sure to test all return values. Use
      SioError to print the associated text for errors.

      Example Code Segment

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

      Note that there are two versions of the library: One version is with
      transmitter interrupts disabled (PCL4PB1.OBJ) and one with them
      enabled (PCL4PB2.OBJ or PCL4PB.OBJ).


     PCL4PB Reference Manual                                   Page 3

      +-------------+-----------------------------------------------------+
      |   SioBaud   |  Sets the baud rate of the selected port.           |
      +-------------+-----------------------------------------------------+

      Syntax FUNCTION SioBaud(Port,BaudCode)
             REM Port:      Port selected (COM1 - COM20)
             REM BaudCode:  Baud code

      Remark The SioBaud function sets the baud rate without resetting the
             port. It is used to change the baud rate after calling
             SioReset.

             Note that baud code 'BaudUser' sets the baud rate as
             specified by a previous call to SioSetDiv (set divisor).

                Code   Rate    Name             Code   Rate   Name
                  0       0    BaudUser           5    9600   Baud9600
                  1     300    Baud300            6   19200   Baud19200
                  2    1200    Baud1200           7   38400   Baud38400
                  3    2400    Baud2400           8   57600   Baud57600
                  4    4800    Baud4800           9  115200   Baud115200

      Return     -4 : No such port. Expect 0 to MaxPort.
                  -11 : Bad baud rate code. See above code values.

       Other SioSetDiv, SioGetDiv, and SioReset






      +-------------+------------+---------------+------------------------+
      |  SioBrkKey  |  Return non|zero if Control|Break key pressed.      |
      +-------------+------------+---------------+------------------------+

      Syntax FUNCTION SioBrkKey()

      Remark The SioBrkKey function returns a TRUE value (non-zero) if the
             Control-BREAK key was pressed, else it returns a zero.  Use
             SioBrkKey as a safety exit from a polling loop. Don't mix this
             function up with SioBrkSig.

      Return -1 : Control-BREAK was pressed.
              0 : Control-BREAK was NOT pressed.

       Other SioBrkSig











     PCL4PB Reference Manual                                   Page 4

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

      Syntax FUNCTION SioBrkSig(Port,Cmd)
             REM Port:      Port selected (COM1 thru COM20)
             REM char Cmd:  ASSERT, CANCEL, or DETECT

      Remark The SioBrkSig function controls the BREAK bit in the line
             status register. The legal commands are:

                  ASSERT.BREAK ('A') to assert BREAK
                  CANCEL.BREAK ('C') to cancel BREAK
                  DETECT.BREAK ('D') to detect BREAK

             ASSERT.BREAK, CANCEL.BREAK, and DETECT.BREAK are defined in
             PCL4PB.BI. See TERM.BAS (in PPL4PB) for an example of the use
             of SioBrkSig.

      Return -2 : Port not enabled. Call SioReset first.
             -4 : No such port. Expect 0 to MaxPort.
             -6 : Illegal command. Expected 'A', 'C', or 'D'.
             >0 : BREAK signal detected (DETECT command only)

       Other SioBrkKey






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

      Syntax FUNCTION SioCTS(Port)
             REM Port: Port selected (COM1 thru COM20)

      Remark The SioCTS function is used to read the Clear to Send (CTS)
             modem status bit.

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

             Refer to the Serial Communications Manual (ASYNC.TXT) for a
             discussion of flow control.

      Return -2 : Port not enabled. Call SioReset first.
             -4 : No such port.  Expect 0 to MaxPort.
              0 : CTS is clear.
             >0 : CTS is set.

       Other SioFlow, SioDSR, SioRI, SioDCD, and SioModem.



     PCL4PB Reference Manual                                   Page 5

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

      Syntax FUNCTION SioDCD(Port)
             REM Port: Port selected (COM1 thru COM20)

      Remark The SioDCD function is used to read the Data Carrier Detect
             (DCD) modem status bit. Also see SioModem.

      Return -2 : Port not enabled. Call SioReset first.
             -4 : No such port.  Expect 0 to MaxPort.
              0 : DCD is clear.
             >0 : DCD is set.

       Other SioDSR, SioCTS, SioRI, and SioModem.








      +-------------+-----------------------------------------------------+
      |   SioDelay  |  Delays one or more timer tics.                     |
      +-------------+-----------------------------------------------------+

      Syntax FUNCTION SioDelay(Tics)
             REM Tics: # timer tics to delay

      Remark The SioDelay function is used to delay one or more timer tics,
             where each timer tic is approximately 55 milliseconds (18.2
             tics to the second).

      Return zero.

       Other SioTimer




















     PCL4PB Reference Manual                                   Page 6

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

      Syntax FUNCTION SioDone(Port)
             REM Port: Port selected (COM1 thru COM20)

      Remark The SioDone function terminates further serial processing.
             SioDone MUST be called before exiting your application so that
             interrupts can be restored to their original state.  Failure
             to do this can crash the operating system.  If you forget to
             call SioDone before exiting, be sure to re-boot your computer.
             You can call SioDone even if SioReset has not been called, so
             it is good practice to always call SioDone before exiting your
             application.

             Also note that SioDone de-references the transmit and receive
             buffers set up by SioRxQue and SioTxQue.

      Return -2 : Port not enabled. Call SioReset first.
             -4 : No such port. Expect 0 to MaxPort.

       Other SioReset.






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

      Syntax FUNCTION SioDSR(Port)
             REM Port: Port selected (COM1 thru COM20)

      Remark The SioDSR function is used to read the Data Set Ready (DSR)
             modem status bit.

             The DSR is often used by serial devices (such as modems) to
             signal the computer that they are ready.

      Return -2 : Port not enabled. Call SioReset first.
             -4 : No such port.  Expect 0 to MaxPort.
              0 : DSR is clear.
             >0 : DSR is set

       Other SioCTS, SioRI, SioDCD, and SioModem










     PCL4PB Reference Manual                                   Page 7

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

      Syntax FUNCTION SioDTR(Port,Cmd)
             REM Port: Port selected (COM1 thru COM20)
             REM Cmd:  DTR command (SET, CLEAR, or READ)

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

                  SET.LINE ('S')  to set DTR (ON)
                  CLEAR.LINE ('C')  to clear DTR (OFF)
                  READ.LINE ('R')  to read DTR

      Return -2 : Port not enabled. Call SioReset first.
             -4 : No such port. Expect 0 to MaxPort.
             -5 : Not one of 'S', 'C', or 'R'.
              0 : DTR is OFF (READ.LINE Command).
             >0 : DTR is ON (READ.LINE Command).

       Other SioRTS.




      +---------------+---------------------------------------------------+
      |    SioEmpty   |  Waits till UART is empry before returning.       |
      +---------------+---------------------------------------------------+

      Syntax function SioEmpty(Port)
             REM  Port: Port selected (COM1 thru COM20)

      Remark The SioEmpty function waits until the UART has completed the
             transmission of its last bit (TXE and TBE are both set) before
             returning. Call SioLine to check the TXE and TBE bits without
             waiting.

             The primary use of this function is to determine when RTS can
             be dropped in 2-wire RS485 control.

      Return -2 : Port not enabled. Call SioReset first.
             -4 : No such port. Expect 0 to MaxPort.
             -5 : Not one of 'S', 'C', or 'R'.
              0 : UART has completed transmission of the last bit.











     PCL4PB Reference Manual                                   Page 8

      +-------------+-----------------------------------------------------+
      |   SioError  |  Displays error in text.                            |
      +-------------+-----------------------------------------------------+

      Syntax FUNCTION SioError(Code)
             REM Code: PCL4PB error code

      Remark The SioError function displays the error in text corresponding
             to the error code returned from a PCL4PB function.  During
             development of a communications application, it is a good idea
             to always test return codes, and print out their descriptions
             with SioError.

      Return  zero.




      +-------------+------------------------------------+----------------+
      |   SioFIFO   |  Sets the FIFO trigger level (16550| UART only).    |
      +-------------+------------------------------------+----------------+

      Syntax FUNCTION SioFIFO(Port, Level)
             REM  Port: Port selected (COM1 thru COM20)
             REM Level: FIFO level code (see below)

      Remark The SioFIFO function is used to enable both transmit and
             receive FIFOs for 16550, 16650, and 16750 UARTS, and to set
             the trigger level at which receive interrupts are generated.
             Transmitter interrupts are set at the maximum value (16 for
             16550, 32 for 16650, and 64 for 16750).

             Level   Level       16550     16650     16750
             Code    Name        Trigger   Trigger   Trigger
              0      LEVEL.1ST      1         8         1
              1      LEVEL.2ND      4        16        16
              2      LEVEL.3RD      8        24        32
              3      LEVEL.4TH     14        28        56

      Return -2 : Port not enabled. Call SioReset first.
             -4 : No such port.  Expect 0 to MaxPort.
              0 : No FIFO. (8250 or 16450)
              1 : 16550 FIFO level set (16 byte FIFOs).
              2 : 16650 FIFO level set (32 byte FIFOs).
              3 : 16750 FIFO level set (64 byte FIFOs).













     PCL4PB Reference Manual                                   Page 9

      +------------+------------------------------------------------------+
      |   SioFlow  |  Sets hardware (RTS/CTS) flow control.               |
      +------------+------------------------------------------------------+

      Syntax FUNCTION SioFlow(Port,Tics)
             REM Port: Port selected (COM1 thru COM20)
             REM Tics: # tics before timeout

      Remark The SioFlow function is used to enable or disable hardware
             flow control.  Hardware flow control uses RTS and CTS to
             control data flow between the modem and the computer.  Refer
             to the Serial Communications Manual (ASYNC.TXT) for a discussion of
             flow control. To enable hardware flow control, call SioFlow
             with Tics >=0. "Tics" is the number of timer tics (18.2 per
             second) before a call to SioPutc will time out because CTS was
             not set.

             In order for hardware flow control to work correctly, your
             modem must also be configured to work with hardware flow
             control, and your computer to modem cable must have RTS and
             CTS wired straight through.

      Return -2 : Port not enabled. Call SioReset first.
             -4 : No such port.  Expect 0 to MaxPort.
             =0 : Flow control disabled.
             >0 : Flow control enabled.




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

      Syntax FUNCTION SioGetc(Port,Tics)
             REM Port: Port selected (COM1 thru COM20)
             REM Tics: Timeout

      Remark The SioGetc function reads a byte from the selected serial
             port. The function will wait for the number of system tics
             given by the 'Tics' argument before returning 'timed out'
             (-1). There are 18.2 tics to the second.

      Return -2 : Port not enabled. Call SioReset first.
             -4 : No such port. Expect 0 to MaxPort.
             -1 : If timed out.
             >0 : Character read.

       Other SioUnGetc and SioPutc.









     PCL4PB Reference Manual                                   Page 10

      +-----------+-------------------------------------------------------+
      |  SioGets  |  Receive a buffer from the serial line.               |
      +-----------+-------------------------------------------------------+

      Syntax function SioGets(Port,BufSeg,BufOfs,Length)
             REM Port:   Port selected (COM1 thru COM20)
             REM BufSeg: Segment of byte buffer.
             REM BufOfs  Offset of byte buffer.
             REM Length: Length of Buffer (# of requested bytes)

      Remark The SioGets function reads a buffer of bytes from the selected
             serial port.  This function will read either the number of
             requested bytes or fewer if no character is immediately
             available. SioGets cannot return more characters than are in
             the receive buffer at the time it is called. The number of
             characters actually read is returned.

      Return -2 : Port not enabled. Call SioReset first.
             -4 : No such port. Expect 0 to MaxPort.
             -1 : If timed out.
             >0 : Number of characters read into Buffer.

       Other SioGetc and "Code Example" section.





      +---------------+---------------------------------------------------+
      |   SioGetDiv   |  Reads the baud rate divisor.                     |
      +---------------+---------------------------------------------------+

      Syntax FUNCTION SioGetDiv(Port)
             REM Port: Port selected (COM1 thru COM20)

      Remark The SioGetDiv function reads the baud rate divisor.  The baud
             rate can then be determined by the formula:

                 BaudRate = 115200 / Divisor

             Some common values are:

               Baud   Divisor      Baud  Divisor      Baud  Divisor
                300    0180        4800   0018       38400   0003
               1200    0060        9600   000C       57600   0002
               2400    0030       19200   0006      115200   0001

      Return -2 : Port not enabled. Call SioReset first.
             -4 : No such port. Expect 0 to MaxPort.
             >0 : Baud rate divisor.

       Other SioParms.






     PCL4PB Reference Manual                                   Page 11

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

      Syntax FUNCTION SioInfo(Cmd)
             REM Cmd: Command (See below)

      Remark The SioInfo function returns a word value depending on the
             character argument in the table below.  This function is
             useful for understanding what the hardware is doing.  Note
             that the command argument is case sensitive.

                Info Codes

                'V' : Version [as hex byte XY means version X.Y]
                'I' : TRUE if library compiled with TX interrupts enabled.
                'T' : Total (over all ports) transmitter interrupts.
                'R' : Total (over all ports) receiver interrupts.
                'd' : Total (over all ports) times RTS dropped.
                'r' : Total (over all ports) times RTS raised.
                'c' : Total (over all ports) times CTS drop detected.

      Return  -1 : Function argument not recognized.
             >=0 : Value as per above table.


      +-------------+-----------------------------------------------------+
      |    SioIRQ   |  Assigns an IRQ line to a port.                     |
      +-------------+-----------------------------------------------------+

      Syntax FUNCTION SioIRQ(Port,IRQcode)
             REM Port:    Port selected (COM1 thru COM20)
             REM IRQcode: IRQ number [IRQ2..IRQ15]

      Remark The SioIRQ function assigns an IRQ line to a port. SioIRQ
             (like SioUART) must be called before calling SioReset. Unless
             you have a non-standard (COM1 & COM3 use IRQ4 while COM2 &
             COM4 use IRQ3) serial port configuration (or don't want to run
             more than 2 ports concurrently), you will not need to call
             SioIRQ.  Be EXTREMELY careful with SioIRQ as it can lock your
             machine up if given incorrect information.

             In particular, remember that your port hardware must generate
             the interrupt that you have specified.  You should refer to
             your serial board hardware manual for specfic instructions in
             configuring your hardware.  Be sure to call SioPorts first to
             setup DigiBoard or BOCA ports if you have them.  Refer to the
             PCL4PB User's Manual (PCL4PB_U.TXT) for more information.

      Return -4 : No such port. Expect 0 to MaxPort.
            -15 : Port already enabled.  SioReset has already been called.
            -17 : No such IRQ.
            -18 : ISR limit (maximum of 4 PC IRQs) exceeded.
              0 : Otherwise

       Other SioUART and SioPorts.


     PCL4PB Reference Manual                                   Page 12

      +-------------+-----------------------------------------------------+
      |   SioLine   |  Reads the line status register.                    |
      +-------------+-----------------------------------------------------+

      Syntax FUNCTION SioLine(Port)
             REM Port: Port selected (COM1 thru COM20)

      Remark The SioLine function reads the line status register.  The
             individual bit masks are as follows:

                  0x40  = Transmitter empty.
                  0x20  = Transmitter buffer empty.
                  0x10  = Break detected.
                  0x08  = Framming error.
                  0x04  = Parity error.
                  0x02  = Overrun error.
                  0x01  = Data ready.

               The above are documented in the file PCL4PB.BI.

      Return    -2 : Port not enabled. Call SioReset first.
                  -4 : No such port. Expect 0 to MaxPort.
                  >0 : Line status (rightmost byte of word).

       Other SioModem.




      +-------------+-----------------------------------------------------+
      | SioLoopBack |  Does a UART loopback test.                         |
      +-------------+-----------------------------------------------------+

      Syntax FUNCTION SioLoopBack(Port)
             REM Port: Port selected (COM1 thru COM20)

      Remark SioLoopBack makes use of the built in loopback test capability
             of the 8250 family UART.  Normally SioLoopBack will never need
             to be called unless you suspect that your UART is bad. Some
             UARTs must be reset after running a loopback test.

      Return  0 : Loopback test is successfull.
             -2 : Port not enabled. Call SioReset first.
             -4 : No such port.  Expect 0 to MaxPort.
            -12 : Loopback test fails.













     PCL4PB Reference Manual                                   Page 13

      +-------------+-----------------------------------------------------+
      |   SioModem  |  Reads the modem status register.                   |
      +-------------+-----------------------------------------------------+

      Syntax FUNCTION SioModem(Port, Mask)
             REM Port: Port selected (COM1 thru COM20)
             REM Mask: Modem function mask

      Remark The SioModem function reads the modem register.  The bit
             definitions for the function mask are as follows:

               Bit Name  Function               Bit  Name      Function
                7  DCD   Data Carrier Detect     3   DeltaDCD  DCD has changed
                6  RI    Ring Indicator          2   DeltaRI   RI has changed
                5  DSR   Data Set Ready          1   DeltaDSR  DSR has changed
                4  CTS   Clear To Send           0   DeltaCTS  CTS has changed

             Bits 4 through 7 represent the absolute state of their
             respective RS-232 inputs.  Bits 0 through 3 represent a change
             in the state of their respective RS-232 inputs since last
             read. Once UART register 3 is read, the Delta bits are
             cleared.  Thus, it is best not to depend on the Delta bits.

      Return -2 : Port not enabled. Call SioReset first.
             -4 : No such port. Expect 0 to MaxPort.
             >0 : Modem status (rightmost byte of word).

       Other SioCTS, SioDCD, SioDSR and SioRI.

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

      Syntax  FUNCTION SioParms(Port,Parity,StopBits,DataBits)
             REM Port:     Port selected (COM1 - COM20)
             REM Parity:   Parity code [0,1,3,5,7]
             REM StopBits: Stop bits code [0,1]
             REM DataBits: Word length code [0,1,2,3]

      Remark The SioParms function sets the parity, stop bits, and word
             length.  If the default parity (none), stop bits (1), or word
             length (8) is not acceptable, then they can be changed by
             calling SioParms.  SioParms can be called either before or
             after calling SioReset. See file PCL4PB.BI.

                 Parity codes : NoParity, OddParity, EvenParity,
                                MarkParity, SpaceParity
                StopBit codes : OneStopBit, TwoStopBits
               DataBits codes : WordLength7, WordLength8.

      Return     -4 : No such port. Expect 0 to MaxPort.
                  -7 : Bad parity code selected. Expecting 0,1,3,5,7.
                  -8 : Bad stop bits code. Expecting 0 or 1.
                  -9 : Bad word length code. Expecting 0 to 3.

       Other  SioReset.


     PCL4PB Reference Manual                                   Page 14

      +-------------+-----------------------------------------------------+
      |  SioPorts   |  Sets number of PC & Digiboard / BOCA Board ports.  |
      +-------------+-----------------------------------------------------+

      Syntax FUNCTION SioPorts(NbrPorts,FirstPort,StatusReg,Code)
             REM NbrPorts:  Total number of ports
             REM FirstPort: First DigiBoard port
             REM StatusReg: DigiBoard Status Register
             REM Code:      PC.PORTS, DIGIBOARD, or BOCABOARD

      Remark The SioPorts function must be called before ANY other serial
             functions.  The purpose of the SioPorts function is to set the
             total number of ports, the first DigiBoard (or BOCA board)
             port and the DigiBoard (or BOCA board) status register
             address.

             Once SioPorts is called, all COM ports starting with
             "FirstPort" will be treated as DigiBoard (or BOCA board)
             ports.  The default setup is 4 standard PC ports and no
             DigiBoard or BOCA ports [ SioPorts(4,4,0,PC.PORTS) ].

      Return -4 : No such port. Expect 0 to 9.
              0 : No error (sets MaxPort to NumberPorts-1).

       Other SioUART, SioIRQ, and Code Examples.


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

      Syntax FUNCTION SioPutc(Port,Ch)
             REM Port: Port selected (COM1 thru COM20)
             REM Ch:   Character to send

      Remark The SioPutc function writes one byte to the selected serial
             line UART for transmission.

             If flow control has been enabled, then SioPutc may return a -1
             (time out) if the number of tics specified in the SioFlow
             function was exceeded waiting for the modem to raise CTS.

             Refer to the Serial Communications Manual (ASYNC.TXT) for a discussion
             of flow control.

             If transmitter interrupts are enabled (there are separate
             versions of the library for transmitter interrupts enabled),
             then the byte is placed in the transmit buffer, awaiting
             transmission by the PCL4PB interrupt service routine.

       Return -2 : Port not enabled. Call SioReset first.
              -4 : No such port. Expect 0 to MaxPort.
              -1 : Timed out waiting for CTS (flow control enabled)

       Other SioGetc and SioFlow.



     PCL4PB Reference Manual                                   Page 15

      +-------------+-----------------------------------------------------+
      |   SioPuts   |  Transmit a buffer over a serial line.              |
      +-------------+-----------------------------------------------------+

      Syntax function SioPuts(Port,BufSeg,BufOfs,Length)
             REM Port:   Port selected (COM1 thru COM20)
             REM BufSeg: Segment of byte buffer.
             REM BufOfs  Offset of byte buffer.
             REM Length: Length of Buffer (# of requested bytes)

      Remark The SioPuts function transmits each buffer character over the
             selected serial line.  The number of characters actually
             transmitted is returned. This function can take a long time
             for large buffers if transmitter interrupts are not enabled!

             If flow control has been enabled, then SioPuts may transmit
             fewer characters than requested if the number of tics
             specified in the SioFlow function was exceeded waiting for the
             modem to raise CTS.

             If transmitter interrupts are enabled, SioPuts will transmit
             fewer than the number of characters requested if the transmit
             buffer would overflow. The actual number of characters
             transmitted is returned.

      Return -2 : Port not enabled. Call SioReset first.
             -4 : No such port. Expect 0 to MaxPort.
             >=0: Number of characters actually transmitted.

       Other SioPutc and "Code Example" section.

      +-------------+-----------------------------------------------------+
      |   SioRead   |  Reads any UART register.                           |
      +-------------+-----------------------------------------------------+

      Syntax FUNCTION SioRead(Port,Reg)
             REM Port: Port selected (COM1 thru COM20)
             REM Reg:  UART register (0 to 7)

      Remark The SioReset function directly reads the contents of any of
             the 7 UART registers.  This function is useful when debugging
             application programs and as a method for verifying UART
             contents.

             The line status register (register 5) can also be read with
             SioLine while the modem status register (register 6) can also
             be read with SioModem.  Refer to the Serial Communications Manual
             (ASYNC.TXT) for a discussion of the UART registers.

      Return -3 : No buffer available. Call SioRxBuf first.
             -4 : No such port. Expect 0 to MaxPort.

       Other SioGetDiv, SioLine and SioModem.





     PCL4PB Reference Manual                                   Page 16

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

      Syntax FUNCTION SioReset(Port,BaudCode)
             REM Port:     Port selected (COM1 thru COM20)
             REM BaudCode: Baud code or -1

      Remark The SioReset function initializes the selected serial port.
             SioReset should be called after calling SioParm, SioRxBuf and
             SioTxBuf, but before making any other calls. SioReset uses the
             parity, stop bits, and word length value previously set if
             SioParm was called, otherwise the default values are used.

             Recall that COM1 and COM3 share the same interrupt vector and
             therefore cannot operate simultaneously. Similiarly, COM2 and
             COM4 cannot operate simultaneously. Any other combination of
             two ports can be used.

             By specifing NORESET (-1) for the baud rate code, the port
             will NOT be reset.  This is used to "take over" a port from a
             host communications program that allows a "DOS gateway".
             External protocols can be implemented this way.

      Return  -3 : No buffer available. Call SioRxBuf first.
              -4 : No such port. Expect 0 to MaxPort.
             -11 : Bad baud rate code selected. Expecting 0 to 9.
             -13 : UART undefined. SioUART(Port,0) was called previously.
             -14 : Bad or missing UART. You may not have hardware present.
             -15 : Port already enabled. SioReset has already been called.
             -16 : Interrupt already in use.

       Other SioBaud, SioParms, SioRxBuf, SioDone, and SioUART.

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

      Syntax FUNCTION SioRI(Port)
             REM Port: Port selected (COM1 thru COM20)

      Remark The SioRI function is used to read the Ring Indicator (RI)
             bit. When a ring occurs, the modem will typically transmit the
             string "RING" to the the computer.

      Return -2 : Port not enabled. Call SioReset first.
             -4 : No such port.  Expect 0 to MaxPort.
              0 : RI is clear.
             >0 : RI is set (RING has occurred).

       Other SioDSR, SioCTS, SioDCD, and SioModem.







     PCL4PB Reference Manual                                   Page 17

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

      Syntax FUNCTION SioRTS(Port, Cmd)
             REM Port: Port selected (COM1 thru COM20)
             REM Cmd:  RTS command (SET, CLEAR, or READ)

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

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

             Refer to the Serial Communications Manual (ASYNC.TXT) for a
             discussion of flow control. Commands (defined in PCL4PB.BI)
             are:

                  SET.LINE ('S')   - set RTS (ON)
                  CLEAR.LINE ('C') | clear RTS (OFF)
                  READ.LINE ('R')  - read RTS

      Return -2 : Port not enabled. Call SioReset first.
             -4 : No such port. Expect 0 to MaxPort.
             -5 : Command is not one of 'S', 'C', or 'R'.
              0 : RTS is OFF (READ.LINE Command).
             >0 : RTS is ON  (READ.LINE Command).

       Other SioFlow and SioDTR.

      +------------+------------------------------------------------------+
      |  SioRxBuf  |  Sets up receive buffers.                            |
      +------------+------------------------------------------------------+

      Syntax FUNCTION SioRxBuf(Port,Segment,SizeCode)
             REM Port:     Port selected (COM1 thru COM20)
             REM BufSeg:   Receive buffer segment
             REM SizeCode: Buffer size code

      Remark The SioRxBuf function passes the address segment and size of
             the receive buffer. SioRxBuf must be called before SioReset.

               Code  Size  Name           Code   Size  Name
                 4    128  Size128           9   4096  Size4K
                 5    256  Size256          10   8192  Size8K
                 6    512  Size512          11  16384  Size16K
                 7   1024  Size1K           12  32678  Size32K
                 8   2048  Size2K

      Return  -4 : No such port. Expect 0 to MaxPort.
             -10 : Bad buffer size code. Expecting 0 to 11.

       Other SioReset and SioTxBuf.


     PCL4PB Reference Manual                                   Page 18

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

      Syntax FUNCTION SioRxClear(Port)
             REM Port: Port selected (COM1 thru COM20)

      Remark The SioRxClear function will delete any characters in the
             receive buffer for the specified port.  After execution, the
             receive buffer will be empty.  Call SioRxBuf after resetting a
             port in order to delete any spurious characters.

      Return    -2 : Port not enabled. Call SioReset first.
                  -4 : No such port. Expect 0 to MaxPort.

       Other SioRxQue.






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

      Syntax FUNCTION SioRxQue(Port)
             REM Port: Port selected (COM1 thru COM20)

      Remark The SioRxQue function will return the number of characters in
             the receive queue at the time of the call. It can be used to
             implement XON/XOFF flow control.

      Return -2 : Port not enabled. Call SioReset first.
             -4 : No such port. Expect 0 to MaxPort.

       Other SioRxClear.





















     PCL4PB Reference Manual                                   Page 19

      +-------------+-----------------------------------------------------+
      |  SioSetDiv  |  Sets the user definable baud rate divisor.         |
      +-------------+-----------------------------------------------------+

      Syntax FUNCTION SioSetDiv(Divisor)
             REM Divisor: User baud rate divisor

      Remark The SioSetDiv function sets the divisor for the user baud
             rate. Once set, SioBaud(Port,%BaudUser) is called to set the
             baud rate associated with the baud rate divisor, which is:

                 BaudRate = 115200 / Divisor

             For example, the divisor for 110 baud is 115200/110 = 1047,
             and the divisor for 28800 baud is 115200/28800 = 4. To set
             your port to a baud rate of 28800,

                 SioSetDiv(4)
                 SioBaud(Port,BaudUser)

             The divisor must be a 16 bit integer. Referring to PCL4PB.BI,
             note that the baud rate code (BaudUser) for the user baud rate
             is 0.

      Return >0 : Previous user baud rate divisor.

       Other SioGetDiv.





      +------------+------------------------------------------------------+
      |  SioTimer  |  Returns the number of system clock tics.            |
      +------------+------------------------------------------------------+

      Syntax FUNCTION SioTimer()

      Remark The SioTimer function will return the number of system clock
             tics since midnight, at 18.2 tics per second.  This function
             is useful for timing various functions.

       Other SioDelay















     PCL4PB Reference Manual                                   Page 20

      +------------+------------------------------------------------------+
      |  SioTxBuf  |  Sets up transmitter buffer.                         |
      +------------+------------------------------------------------------+

      Syntax FUNCTION SioTxBuf(Port,Segment,SizeCode)
             REM Port:     Port selected (COM1 thru COM20)
             REM BufSeg:   Receive buffer segment
             REM SizeCode: Buffer size code

      Remark The SioTxBuf function passes the address segment and size of
             the transmit buffer to PCL4PB, provided that you will link
             with a PCL4PB library with transmitter interrupts enabled.
             PCL4PB requires a transmit buffer for each port in
             simultaneous operation if you are using the version of the
             library with transmitter interrupts enabled (PCL4PB2.OBJ).
             SioTxBuf() must be called before SioReset.

               Code  Size  Name           Code   Size  Name
                 4    128  Size128           9   4096  Size4K
                 5    256  Size256          10   8192  Size8K
                 6    512  Size512          11  16384  Size16K
                 7   1024  Size1K           12  32678  Size32K
                 8   2048  Size2K

             This function is not used unless transmitter interrupts are
             enabled (PCL4PB2.OBJ).  Refer to the PCL4PB User's Manual
             (PCL4PB_U.TXT) for information on transmitter (TX) interrupts.

      Return  -4 : No such port. Expect 0 to MaxPort.
             -10 : Bad buffer size code. Expecting 0 to 11.

       Other SioRxBuf and SioReset.

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

      Syntax FUNCTION SioTxClear(Port)
             REM Port: Port selected (COM1 thru COM20)

      Remark The SioTxClear function will delete any characters in the
             transmit buffer for the specified port, provided that you have
             linked with the PCL4PB library with transmitter interrupts
             enabled. After execution, the transmit buffer will be empty.

             Once this function is called, any character in the transmit
             buffer (put there by SioPutc) will be lost and therefore not
             transmitted. This function is not used unless the transmitter
             interrupts are enabled. Refer to the Serial Communications Manual for
             information on transmitter (TX) interrupts.

      Return -2 : Port not enabled. Call SioReset first.
             -4 : No such port. Expect 0 to MaxPort.

       Other SioTxQue.



     PCL4PB Reference Manual                                   Page 21

      +------------+------------------------------------------------------+
      | SioTxFlush |  Flushes the transmitter buffer.                     |
      +------------+------------------------------------------------------+

      Syntax FUNCTION SioTxFlush(Port)
             REM Port: Port selected (COM1 thru COM20)

      Remark The SioTxFlush function will re-enable transmitter interrupts
             if they had been disabled by CTS dropping. This has the effect
             of forcing all data out of the transmitter queue unless
             stopped again by CTS going down.

             Once the transmitter interrupt has been disabled (by CTS
             going down), the only way to restart it is by calling one of
             the serial I/O functions (SioPutc, SioGetc, SioTxQue,
             SioRxClear, SioTxClear, or SioTxFlush).

             The primary purpose of SioTxFlush is to provide an explicit
             means of restarting transmitter interrupts.

      Return -2 : Port not enabled. Call SioReset first.
             -4 : No such port. Expect 0 to MaxPort.

      Other SioTxQue.




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

      Syntax FUNCTION SioTxQue(Port)
             REM Port: Port selected (COM1 thru COM20)

      Remark The SioTxQue function will return the number of characters in
             the transmit queue at the time of the call, provided that you
             have linked with the PCL4PB library with transmitter
             interrupts enabled.

             This function is not used unless the transmitter interrupts
             are enabled.  Refer to the PCL4PB User's Manual (PCL4PB_U.TXT)
             for information on transmitter (TX) interrupts.

      Return -2 : Port not enabled. Call SioReset first.
             -4 : No such port. Expect 0 to MaxPort.

       Other SioTxClear.










     PCL4PB Reference Manual                                   Page 22

      +------------+------------------------------------------------------+
      |  SioUART   |  Sets the UART base address.                         |
      +------------+------------------------------------------------------+

      Syntax FUNCTION SioUART(Port,Address)
             REM Port:    Port selected (COM1 thru COM20)
             REM Address: UART address

      Remark The SioUART function sets the UART base address for the
             specified port.  SioUART must be called before SioReset in
             order to have effect.  Be extremely sure that you know what
             you are doing!  Note that PCL4PB uses the standard PC/XT/AT
             port addresses, interrupt request lines, and interrupt service
             vectors.  Therefore, this function is only needed for
             non-standard ports.

      Return  >0 : The previous base address for this port.
              -4 : No such port.  Expect 0 to MaxPort.
             -15 : Port already enabled.  SioReset has already been called.

       Other SioPorts, SioIRQ, and SioReset.



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

      Syntax FUNCTION SioUnGetc(Port,Ch)
             REM Port: Port selected (COM1 thru COM20)
             REM Ch:   Character to unget

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

      Return -2 : Port not enabled. Call SioReset first.
             -4 : No such port. Expect 0 to MaxPort.

       Other SioReset.
















     PCL4PB Reference Manual                                   Page 23

                               Function Sumary


           +-------------+----------+----------+----------+----------+
           | Function    |   Arg1   |   Arg2   |   Arg3   |   Arg4   |
           +-------------+----------+----------+----------+----------+
           | SioBaud     | Port     | BaudCode |          |          |
           | SioBrkSig   | Port     | Cmd      |          |          |
           | SioBrkKey   |          |          |          |          |
           | SioCTS      | Port     |          |          |          |
           | SioDCD      | Port     |          |          |          |
           | SioDelay    | Tics     |          |          |          |
           | SioDone     | Port     |          |          |          |
           | SioDSR      | Port     |          |          |          |
           | SioDTR      | Port     | Cmd      |          |          |
           | SioEmpty    | Port     |          |          |          |
           | SioError    | Code     |          |          |          |
           | SioFIFO     | Port     | LevelCode|          |          |
           | SioFlow     | Port     | Tics     |          |          |
           | SioGetc     | Port     | Tics     |          |          |
           | SioGets     | Port     | BufSeg   | BufOfs   | BufLen   |
           | SioGetDiv   | Port     |          |          |          |
           | SioInfo     | Cmd      |          |          |          |
           | SioIRQ      | Port     | IRQcode  |          |          |
           | SioLine     | Port     |          |          |          |
           | SioLoopBack | Port     |          |          |          |
           | SioModem    | Port     | Mask     |          |          |
           | SioParms    | Port     | Parity   | StopBits | DataBits |
           | SioPorts    | NbrPorts | FirstPort|StatusReg | Code     |
           | SioPutc     | Port     | Ch       |          |          |
           | SioPuts     | Port     | BufSeg   | BufOfs   | BufLen   |
           | SioRead     | Port     | Reg      |          |          |
           | SioReset    | Port     | BaudCode |          |          |
           | SioRI       | Port     |          |          |          |
           | SioRTS      | Port     | Cmd      |          |          |
           | SioRxBuf    | Port     | BufSeg   | SizeCode |          |
           | SioRxClear  | Port     |          |          |          |
           | SioRxQue    | Port     |          |          |          |
           | SioTimer    |          |          |          |          |
           | SioSetDiv   | Port     | Divisor  |          |          |
           | SioTxBuf    | Port     | BufSeg   | SizeCode |          |
           | SioTxClear  | Port     |          |          |          |
           | SioTxFlush  | Port     |          |          |          |
           | SioTxQue    | Port     |          |          |          |
           | SioUART     | Port     | Address  |          |          |
           | SioUnGetc   | Port     | Ch       |          |          |
           +-------------+----------+----------+----------+----------+











     PCL4PB Reference Manual                                   Page 24

                               Error Code Summary


      +------+--------------------------------------------------------+
      | Code |  Description                                           |
      +------+--------------------------------------------------------+
      |   0  |  No error.                                             |
      |  -1  |  Timeout waiting for I/O.                              |
      |  -2  |  Port not enabled. Call SioReset first.                |
      |  -3  |  No buffer available. Call SioRxBuf first.             |
      |  -4  |  No such port. Expect 0 to MaxPort. (COM1 = 0)         |
      |  -5  |  Expected 'S', 'C', or 'R' as 2nd argument.            |
      |  -6  |  Expected 'A', 'C', or 'D' as 2nd argument.            |
      |  -7  |  Bad parity code specified. Expected 0 to 7.           |
      |  -8  |  Bad stop bits code specified. Expected 0 or 1.        |
      |  -9  |  Bad wordlength code specified. Expect 0 to MaxPort.   |
      | -10  |  Bad buffer size code specified. Expected 0 to 11.     |
      | -11  |  Bad baud rate code. Expected 0 to 9.                  |
      | -12  |  Loopback test fails.                                  |
      | -13  |  UART undefined.                                       |
      | -14  |  Missing or bad UART. (no UART hardware ?)             |
      | -15  |  Port already enabled.                                 |
      | -16  |  ISR (interrupt) already in use.                       |
      | -17  |  No such IRQ. (Should be 2 to 7)                       |
      | -18  |  ISR limit (maximum of 4 PC IRQs) exceeded.            |
      | |19  |  Shareware screen cannot be displayed.                 |
      | -20  |  TX buffer is full.                                    |
      +-+----+--------------------------------------------------------+






























     PCL4PB Reference Manual                                   Page 25

                               Code Examples


      SioRxBuf() Example

      DIM Buffer(256+16) AS BYTE
      DIM BufSeg AS WORD
      BufSeg = 1 + VARSEG(Buffer(0)) + (VARPTR(Buffer(0))\16)
      RC = SioRxBuf(Port,BufSeg,SizeCode);

      DigiBoard Example (PC/8)

      'use 0x140 for odd IRQs & 0x141 for even IRQs
      RC = SioPorts(8,COM1,0x140,DIGIBOARD);
      FOR I = COM1 TO COM16
        'set DigiBoard UART addresses
        RC = SioUART(i,0x100+8*i);
        'set DigiBoard for IRQ5
        RC = SioIRQ(I,IRQ5);
      NEXT I

      BOCA Board Example (BB2016)

      'use base port + 7
      RC = SioPorts(16,COM1,0x100+7,BOCABOARD);
      FOR I = COM1 TO COM16
        'set BOCA UART addresses
        RC = SioUART(i,0x100+8*i);
        'set BOCA for IRQ5
        RC = SioIRQ(I,IRQ5);
      NEXT I

      Also be sure to take a look at the example code programs.

      Transmit Alphabet 'A..Z' using SioPuts

      DIM Alpha(26) AS BYTE
      DIM OfsAlpha AS WORD
      DIM SegAlpha AS WORD
      OfsAlpha = VARPTR(Alpha(0))
      SegAlpha = VARSEG(Alpha(0))
      FOR I = 1 TO 26
        Alpha = 65 + I
      NEXT I
      ' transmit entie buffer
      Code = SioPuts(Port,SegAlpha,OfsAlpha,26)












     PCL4PB Reference Manual                                   Page 26


