



                          Personal Communications Library

                                   For Pascal


                                    (PCL4P)



                              REFERENCE MANUAL



                                  Version  6.1

                                 March 23, 1998



                         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
                 SioError............................................8
                 SioFIFO.............................................9
                 SioFlow.............................................9
                 SioGetc............................................10
                 SioGets............................................10
                 SioGetDiv..........................................11
                 SioInfo............................................11
                 SioIRQ.............................................12
                 SioLine............................................12
                 SioLoopBack........................................13
                 SioModem...........................................13
                 SioParms...........................................14
                 SioPorts...........................................14
                 SioPutc............................................15
                 SioPuts............................................15
                 SioRead............................................16
                 SioReset...........................................16
                 SioRI..............................................17
                 SioRTS.............................................17
                 SioRxBuf...........................................18
                 SioRxClear.........................................18
                 SioRxQue...........................................19
                 SioSetDiv..........................................19
                 SioTimer...........................................20
                 SioTxBuf...........................................20
                 SioTxClear.........................................21
                 SioTxFlush.........................................21
                 SioTxQue...........................................22
                 SioUART............................................22
                 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;                                                |
         +--------------------------------------------------------+


      Examine PCL4P.PAS for a listing of constants, functions, and
      procedures. Examine PCL4P16.PAS for the protected mode version.

      For more examples, examine each of the example programs in the
      distribution zip-file.

























     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 RS-232 User's Manual (RS-232.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).

      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 SioRxQue and SioTxQue.

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








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












     PCL4P Reference Manual                                    Page 8

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

             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.

             Levels: FIFO_OFF, LEVEL_1ST, LEVEL_2ND, LEVEL_3RD, LEVEL_4TH.

      Return -2 : Port not enabled. Call SioReset first.
             -4 : No such port.  Expect 0 to MaxPort.
             >0 : FIFO level set (1 if 16550, 2 if 16650, 3 if 16750).
              0 : FIFO level not set (UART is a 8250 or 16450).

      +------------+------------------------------------------------------+
      |   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 RS-232 User's Manual 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 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. 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



     PCL4P Reference Manual                                    Page 9

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






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








     PCL4P Reference Manual                                    Page 10

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







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





     PCL4P Reference Manual                                    Page 11

      +-------------+-----------------------------------------------------+
      |    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.  That is,
             SioIRQ maps an IRQ 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.


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


     PCL4P Reference Manual                                    Page 12

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






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








     PCL4P Reference Manual                                    Page 13

      +-------------+-----------------------------------------------------+
      |  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 codes : 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.



      +-------------+-----------------------------------------------------+
      |  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) ].

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

       Other SioUART, SioIRQ, and Code Examples.


     PCL4P Reference Manual                                    Page 14

      +-------------+-----------------------------------------------------+
      |   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 (there are separate
             versions of the library for transmitter interrupts enabled),
             then the byte is placed in the transmit buffer, awaiting
             transmission by the PCL4P 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.


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


     PCL4P Reference Manual                                    Page 15

      +-------------+-----------------------------------------------------+
      |   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 PCL4P User's Manual 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.

      +-------------+-----------------------------------------------------+
      |  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
             for a list of the baud rate codes, or see "PCL4P.PAS".

      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.


     PCL4P Reference Manual                                    Page 16

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




      +-------------+-----------------------------------------------------+
      |    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 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 User's Manual for a discussion of flow control.
             Commands (defined in PCL4P.PAS) 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.







     PCL4P Reference Manual                                    Page 17

      +------------+------------------------------------------------------+
      |  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 to PCL4P.  Recall that PCL4P requires a
             receive buffer for each port in simultaneous operation since
             the receive function is interrupt driven.  It must be called
             before any incoming characters can be received. SioRxBuf must
             be called before SioReset.  Buffer size codes are listed in
             PCL4P.PAS and PCL4P16.PAS.

                  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.




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



     PCL4P Reference Manual                                    Page 18

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

       Other SioRxFlush.











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




     PCL4P Reference Manual                                    Page 19

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








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






     PCL4P Reference Manual                                    Page 20

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




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













     PCL4P Reference Manual                                    Page 21

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








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








     PCL4P Reference Manual                                    Page 22

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


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


                          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

