



                          Personal Communications Library

                                   For Pascal


                                    (PCL4P)



                              REFERENCE MANUAL



                                  Version  6.2

                                January 28, 1999



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


                               Copyright (C) 1998
                               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.



     PCL4P 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
              Example Code..........................................25







     PCL4P Reference Manual                                    Page 2

                             Introduction


      This manual lists all the PCL4P 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

         +--------------------------------------------------------+
         |  RetCode := SioFunction();    (* any PCL4P function *) |
         |  if RetCode < 0 then begin                             |
         |    RetCode := SioError(RetCode);                       |
         |    (* ...do some stuff... *)                           |
         |    end;                                                |
         +--------------------------------------------------------+


      For more examples, examine each of the example programs provided
      (MINIMAL.PAS, SIMPLE.PAS, DOOR.PAS, SELFTEST.PAS, etc.) in
      the distribution archive.

      You may also wish to examine the TERM.PAS example program in the
      Personal Protocol Library for PascalC (PPL4P).

      For additional information, refer to the PCL4P User's Manual
      (PCL4P_U.TXT) and to the Serial Communications Manual (ASYNC.TXT).
      Also examine PCL4P.PAS where library constants are defined.  Examine
      PCL4P16.PAS for the protected mode version.



















     PCL4P Reference Manual                                    Page 3

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

      Syntax function SioBaud(Port,BaudCode:Integer):Integer;
             (* Port: Port selected [COM1 thru COM20] *)
             (* 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.

             The user baud rate "BaudUser" is set by SioSetDiv.

              Code   Rate    Name             Code   Rate   Name
                0    User    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.
            >= 0 : OK

      Other  SioReset, SioSetDiv, and SioGetDiv.








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

      Syntax function SioBrkKey:Integer;

      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 <> 0 : Control-BREAK was pressed.
                0 : Control-BREAK was NOT pressed.

       Other SioBrkSig









     PCL4P Reference Manual                                    Page 4

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

      Syntax function SioBrkSig(Port:Integer;Cmd:Char):Boolean;
              (* Port: Port selected [COM1 thru COM20] *)
              (*  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
             PCL4P.PAS and PCL4P16.PAS. See TERM.PAS 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:Integer):Integer;
             (* 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.




     PCL4P Reference Manual                                    Page 5

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

      Syntax function SioDCD(Port:Integer):Integer;
             (* 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:Integer):Integer;
             (* 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).  Be careful calling SioDelay since it
             will not return until the specified delay has occurred.

      Return zero.

       Other SioTimer















     PCL4P Reference Manual                                    Page 6

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

      Syntax function SioDone(Port:Integer):Integer;
             (* 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 dereferences the transmit and receive
             buffers set up by SioRxBuf and SioTxBuf.  However, it does NOT
             free the transmit and receive buffers.  It is good practice to
             free the transmit and receive buffers (after calling SioDone).

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

       Other SioReset.








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

      Syntax function SioDSR(Port:Integer):Integer;
             (* Port: Port selected [COM1 thru COM20] *)

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

      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








     PCL4P Reference Manual                                    Page 7

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

      Syntax function SioDTR(Port:Integer;Cmd Char):Integer;
             (* Port: Port selected [COM1 thru COM20] *)
             (* Cmd:  DTR command (SET, CLEAR, or READ) *)

      Remark The SioDTR function controls the Data Terminal Ready (DTR) bit
             in the modem control register. Tje DTR line is typically used
             by your program to tell the serial device that you are
             connected.  DTR should always be set when communicating with a
             modem. Commands (defined in PCL4P.PAS) 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:Integer):Integer;
             /* 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.










     PCL4P Reference Manual                                    Page 8

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

      Syntax function SioError(Code:Integer):Integer;
             (* Code: PCL4P error code *)

      Remark The SioError function displays the error in text corresponding
             to the error code returned from a PCL4P 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/16550/16750).   |
      +-------------+-----------------------------------------------------+

      Syntax function SioFIFO(Port,Level:Integer):Integer;
             (*  Port: Port selected [COM1 thru COM20] *)
             (* Level: FIFO level code (see below) *)

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

             For example, if the FIFO level is set to 8, then the 16550
             UART will not generate an interrupt until 8 bytes have been
             received. This reduces the number of interrupts generated.  In
             order to take advantage of the TX FIFO, use the PCL4P library
             with TX interrupts enabled (PCL4PY.OBJ). Refer to the PCL4P
             Users's Manual for more information.

             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.
              1 : 16550 FIFO level set (16 byte FIFOs).
              2 : 16650 FIFO level set (32 byte FIFOs).
              3 : 16750 FIFO level set (64 byte FIFOs).
              0 : FIFO level not set (UART is a 8250 or 16450).







     PCL4P Reference Manual                                    Page 9

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

      Syntax function SioFlow(Port,Tics:Integer)
             (* Port: Port selected [COM1 thru COM20] *)
             (* Tics: # tics before TX times out *)

      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 / second) before a call
             to SioPutc or SioPuts will time out because CTS was not set
             and transmitter interrupts are disabled.

             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. Flow control is disabled after
             resetting a port.  To explicitly disable hardware flow
             control, call SioFlow with Tics = -1.

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

       Other SioPutc


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

      Syntax function SioGetc(Port,Tics:Integer):Integer;
             (* Port: Port selected [COM1 thru COM20] *)
             (* 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'.
             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.





     PCL4P Reference Manual                                    Page 10

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

      Syntax function SioGets(Port:Integer;Buffer:PChar;
                                Length:Integer):Integer
             (* Port: Port selected [COM1 thru COM20] *)
             (* Buffer: Character buffer *)
             (* 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.

             PChar is defined in PCL4P.PAS and PCL4P16.PAS.

      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 SioUnGetc and SioGetc.




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

      Syntax function SioGetDiv(Port:Integer):Integer;
             (* Port: Port selected [COM1 thru COM20] *)

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

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

             Other baud rates can be computed from the formula

                 BaudRate = 115200 / Divisor

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

       Other SioSetDiv and SioBaud.





     PCL4P Reference Manual                                    Page 11

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

      Syntax function SioInfo(Cmd:Char):Integer;
             (* Cmd: See table below *)

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

      Return (Cmd : description)

             'V' : Version [as hex byte XY where means version X.Y]
             'I' : TRUE if library compiled with TX interrupts enabled.
             'P' : TRUE if library compiled for protected mode.
             '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:Integer):Integer;
             (* Port:    Port selected [COM1 thru COM20] *)
             (* 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
             PCL4P User's Manual for additional 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.


     PCL4P Reference Manual                                    Page 12

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

      Syntax function SioLine(Port:Integer):Integer;
             (* 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.

      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:Integer):Integer;
             (* Port: Port selected [COM1 thru COM20] *)

      Remark SioLoopBack makes use of the built in loopback test capability
             of the INS8250 family UART.  Normally SioLoopBack will never
             need to be called unless you suspect that your UART is bad.
             Many 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.

















     PCL4P Reference Manual                                    Page 13

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

      Syntax function SioModem(Port,Mask:Integer):Integer;
             (* Port: Port selected [COM1 thru COM20] *)
             (* 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 int  SioParms(Port,Parity,StopBits,DataBits:Integer):Integer;
             (* Port:     Port selected [COM1 thru COM20] *)
             (* Parity:   Parity code *)
             (* StopBits: Stop bits code *)
             (* DataBits: Word length code *)

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

             Parity code    : NoParity, OddParity, EvenParity, MarkParity,
                              and SpaceParity.
             StopBits codes : OneStopBit, TwoStopBits.
             DataBits codes : WordLength7, WordLength8.

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

       Other SioReset.


     PCL4P Reference Manual                                    Page 14

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

      Syntax function SioPorts(NbrPorts,FirstPort,StatusReg,Code:Integer)
                             :Integer;
             (* NbrPorts:  Total number of ports *)
             (* FirstPort: First DigiBoard or BOCA port *)
             (* StatusReg: DigiBoard Status Register *)
             (* 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) ].

             Refer to the PCL4P Users Manual for more information on the
             DigiBoard and BOCA board. Many other multiport board are
             functionally equivalent to either the DigiBoard or BOCA board.

      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:Integer;Ch:Char):Integer;
             (* Port: Port selected [COM1 thru COM20] *)
             (* Ch:   Character to send *)

      Remark The SioPutc function transmits one character.
             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.

             If transmitter interrupts are enabled, SioPutc returns an
             error if the transmit buffer is already full.  Otherwise the
             byte is placed in the transmit buffer, awaiting transmission
             by the PCL4P interrupt service routine. If transmitter
             interrupts are not enabled, the byte is loaded directly into
             the UART transmit buffer.

      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)
            -20 : Transmit buffer already full (TX interrupts enabled).

       Other SioGetc and SioFlow.


     PCL4P Reference Manual                                    Page 15

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

      Syntax function SioPuts(Port:Integer;Buffer:PChar;
                                Length:Integer):Integer
             (* Port: Port selected [COM1 thru COM20] *)
             (* Buffer: Character buffer *)
             (* Length: Length of Buffer *)

      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, SioFlow, and SioTxFlush.



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

      Syntax function SioRead(Port,Reg:Integer):Integer;
             (* Port: Port selected [COM1 thru COM20] *)
             (* 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 UARTs.

             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 SioLine and SioModem.




     PCL4P Reference Manual                                    Page 16

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

      Syntax function SioReset(Port,BaudCode:Integer):Integer;
             (* Port:     Port selected [COM1 thru COM20] *)
             (* BaudCode: Baud code or -1 *)

      Remark The SioReset function initializes the selected serial port.
             SioReset should be called after calling SioParm and SioRxBuf
             but before making any other calls to PCL4P.  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.  See SioBaud
             or see "PCL4P.PAS for a list of the baud rate codes.

      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.
            >=0 : Port has been reset. Return value is line status.

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


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

      Syntax function SioRI(Port:Integer):Integer;
             (* Port: Port selected [COM1 thru COM20] *)

      Remark The SioRI function is used to read the Ring Indicator (RI)
             modem status bit. Also see SioModem.

      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.





     PCL4P Reference Manual                                    Page 17

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

      Syntax function SioRTS(Port:Integer;Cmd:Char):Integer;
             (* Port: Port selected [COM1 thru COM20] *)
             (* 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 most 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. Refer to the Serial
             Communications Manual for a discussion of flow control.

                  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,Selector,SizeCode:Integer):Integer;
             (*     Port: Port selected [COM1 thru COM20] *)
             (*  Segment: Receive buffer segment *)
             (* SizeCode: Buffer size code *)

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

                  Size Code       Buffer Size    PCL4P.PAS
                     4            128 bytes      Size128
                     5            256 bytes      Size256
                     6            512 bytes      Size512
                     7           1024 bytes      Size1024 or Size1K
                     8           2048 bytes      Size2048 or Size2K
                     9           4096 bytes      Size4096 or Size4K
                    10           8192 bytes      Size8192 or Size8K
                    11          16384 bytes      Size16384 or Size16K
                    12          32768 bytes      Size32768 or Size32K

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

       Other SioReset and Code Examples.


     PCL4P Reference Manual                                    Page 18

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

      Syntax function SioRxClear(Port:Integer):Integer;
             (* 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 SioRxClear after
             resetting a port in order to delete any spurious characters.

             Note that this function was renamed from SioRxFlush in
             version 5.1.

      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:Integer):Integer;
             (* 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.
             =0 : RX queue is empty.
             >0 : Number of bytes in RX queue.

       Other SioRxClear.

















     PCL4P Reference Manual                                    Page 19

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

      Syntax function SioSetDiv(Divisor:Integer):Integer;
             (* 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,

                 Code := SioSetDiv(4);
                 Code := SioBaud(Port,BaudUser);

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

      Return >0 : Previous user baud rate divisor.

       Other SioGetDiv, SioBaud.


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

      Syntax function SioTimer:LongInt;

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

       Other SioDelay


















     PCL4P Reference Manual                                    Page 20

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

      Syntax function SioTxBuf(Port,Selector,SizeCode:Integer):Integer;
             (*     Port: Port selected [COM1 thru COM20] *)
             (*  Segment: Transmit buffer segment *)
             (* SizeCode: Buffer size code *)

      Remark The SioTxBuf function passes the address selector and size of
             the transmit buffer to PCL4P, provided that you will link with
             a PCL4P library with transmitter interrupts enabled. SioTxBuf
             must be called before SioReset.

                  Size Code       Buffer Size    PCL4P.PAS
                     4            128 bytes      Size128
                     5            256 bytes      Size256
                     6            512 bytes      Size512
                     7           1024 bytes      Size1024 or Size1K
                     8           2048 bytes      Size2048 or Size2K
                     9           4096 bytes      Size4096 or Size4K
                    10           8192 bytes      Size8192 or Size8K
                    11          16384 bytes      Size16384 or Size16K
                    12          32768 bytes      Size32768 or Size32K

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

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

       Other SioRxBuf, SioReset and Code Examples.


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

      Syntax function SioTxClear(Port:Integer):Integer;
             (* 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 will
             link with a PCL4P 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.

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

       Other SioTxQue.


     PCL4P Reference Manual                                    Page 21

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

      Syntax function SioTxFlush(Port:Integer):Integer;
             (* 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 the transmission of all data in the
             transmitter queue.

             Note that this function will not return until the transmitter
             queue is empty.

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

       Other SioTxQue.





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

      Syntax function SioTxQue(Port:Integer):Integer;
             (* 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
             will link with a PCL4P library with transmitter interrupts
             enabled.

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

      Return -2 : Port not enabled. Call SioReset first.
             -4 : No such port. Expect 0 to MaxPort.
             >=0: Number bytes in transmit queue.

       Other SioTxFlush.












     PCL4P Reference Manual                                    Page 22

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

      Syntax function SioUART(Port,Address:Integer):Integer;
             (* Port:    Port selected [COM1 thru COM20] *)                           int Port;     (* COM1 to COM4 *)
             (* 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 PCL4P 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:Integer;Ch:Char):Integer;
             (* Port: Port selected [COM1 thru COM20] *)
             (* 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.















     PCL4P Reference Manual                                    Page 23

                               Function Sumary


           40 functions

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









     PCL4P 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 15)                      |
      | -18  |  ISR limit (maximum of 4 PC IRQs) exceeded.            |
      | |19  |  Shareware screen cannot be displayed.                 |
      | -20  |  TX buffer is full.                                    |
      +-+----+--------------------------------------------------------+

                          Code Examples

      DigiBoard Example

      (*** Custom Configuration: DigiBoard PC/8 ***)
      WriteLn('[ Configuring for DigiBoard PC/8 (IRQ5) ]');
      SioPorts(8,COM1,$140,DIGIBOARD);
      for Port := COM1 to COM8 do
        begin
          (* set DigiBoard UART addresses *)
          SioUART(Port,$100+8*Port);
          (* set DigiBoard IRQ *)
          SioIRQ(Port,IRQ5);
        end;

      BOCA Board Example

      (*** Custom Configuration: BOCA BB2016 ***)
      WriteLn('[ Configuring for BOCA Board BB2016 (IRQ15) ]');
      SioPorts(20,COM5,$107,BOCABOARD);
      for Port := COM5 to COM20 do
        begin
          (* set BOCA Board UART addresses *)
          SioUART(Port,$100+8*Port);
          (* set BOCA Board IRQ *)
          SioIRQ(Port,IRQ15);
        end;


     PCL4P Reference Manual                                    Page 25

