


                         Personal Communications Library

                             For the C/C++ Language


                                     (PCL4C)


                               REFERENCE MANUAL



                                   Version 6.2
                                 January 28, 1999



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



                               Copyright (C) 1999
                               All rights reserved



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


                             Voice : 256-881-4630
                               FAX : 256-880-0925
                             email : info@marshallsoft.com
                               FTP : ftp.marshallsoft.com/marshallsoft
                               web : www.marshallsoft.com


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



      MARSHALLSOFT is a registered trademark of MarshallSoft Computing.





     PCL4C 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
                 SioGetDiv.................................11
                 SioGets...................................11
                 SioInfo...................................12
                 SioIRQ....................................12
                 SioLine...................................13
                 SioLoopBack...............................13
                 SioModem..................................14
                 SioParms..................................14
                 SioPorts..................................15
                 SioPutc...................................15
                 SioPuts...................................16
                 SioRead...................................16
                 SioReset..................................17
                 SioRI.....................................17
                 SioRTS....................................18
                 SioRxBuf..................................18
                 SioRxClear................................19
                 SioRxQue..................................19
                 SioSetDiv.................................20
                 SioTimer..................................20
                 SioTxBuf..................................21
                 SioTxClear................................21
                 SioTxFlush................................22
                 SioTxQue..................................22
                 SioUART...................................23
                 SioUnGetc.................................23
              Function Summary.............................24
              Error Code Summary...........................25
              Code Examples................................26







     PCL4C Reference Manual                                    Page 2

      Introduction

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

      1.  Negative values for error conditions. See the next to 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


      +---------------------------------------------------------------+
      | int Code;                 /* MUST be 'int', not 'char' */     |
      |                                                               |
      | Code = SioFunction( );    /* any PCL4C function */            |
      | if(Code<0)                                                    |
      |   {/* error returned */                                       |
      |    SioError(Code);        /* SioError prints error text */    |
      |    SioDone(Port);         /* always call SioDone last */      |
      |    exit(1);                                                   |
      |   }                                                           |
      | /* no errors */                                               |
      | ...your application code...                                   |
      |                                                               |
      +---------------------------------------------------------------+


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

      You may also wish to examine the TERM.C example program in the
      Personal Protocol Library for C (PPL4C).

      For additional information, refer to the PCL4C User's Manual
      (PCL4C_U.TXT) and to the Serial Communications Manual (ASYNC.TXT).
      Also examine the PCL4C.H include file where library constants are
      defined.

      Lastly, note that the shareware versions of all our libraries are
      limited to 4 ports (COM1 through COM4), but that the registered
      version can use 20 ports (COM1 through COM20).









     PCL4C Reference Manual                                    Page 3

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

      Syntax int SioBaud(int Port,int BaudCode)
             /* Port:      Port selected (COM1 - 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.

               Code   Rate    Name          Code   Rate   Name
                 0       0    [User]          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

             Entry 0 above is for the user selectable baud rate. See
             function SioSetDiv.

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

       Other  SioReset, SioSetDiv








      +-------------+-------------+---------------------------------------+
      |  SioBrkKey  |  Returns non|0 if ^BREAK was pressed.               |
      +-------------+-------------+---------------------------------------+

      Syntax int SioBrkKey(void)

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

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

       Other SioBrkSig








     PCL4C Reference Manual                                    Page 4

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

      Syntax int SioBrkSig(int Port,char Cmd)
             /* Port:  Port selected (COM1 thru COM20) */
             /*  Cmd:  ASSERT ('A'), CANCEL ('C'), or DETECT ('D')*/

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

             SioBrkSig is often used by one side to signal the other that
             an error condition has occurred.

      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 int SioCTS(int Port)
             /* 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.

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





     PCL4C Reference Manual                                    Page 5

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

      Syntax int SioDCD(int Port)
             /* 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 int SioDelay(int Tics)
             /* 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



















     PCL4C Reference Manual                                    Page 6

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

      Syntax int SioDone(int Port)
             /* Port: Port selected (COM1 thru COM20) */

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

             Also note that SioDone de-references the transmit and receive
             buffers set up by 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)
             if they were allocated by malloc (or fmalloc).

       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 int SioDSR(int Port)
             /* Port: Port selected (COM1 thru COM20) */

      Remark The SioDSR function is used to read the Data Set Ready (DSR)
             modem status bit. The DSR line is typically used by the serial
             device (such as a modem) to indicate that it is connected.

      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










     PCL4C Reference Manual                                    Page 7

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

      Syntax int SioDTR(int Port,char Cmd)
             /* 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.  The 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 PCL4C.H) 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 int SioEmpty(int Port)
             /* 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.










     PCL4C Reference Manual                                    Page 8

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

      Syntax int SioError(int Code)
             /* Code: PCL4C error code */

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

      Return zero.

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

      Syntax int SioFIFO(int Port,int Level)
             /*  Port: Port selected (COM1 thru COM20) */
             /* Level: FIFO level code (see below) */

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


             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 PCL4CP library
             with TX interrupts enabled. Refer to the PCL4C 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.
              0 : No FIFO. (8250 or 16450)
              1 : 16550 FIFO level set (16 byte FIFOs).
              2 : 16650 FIFO level set (32 byte FIFOs).
              3 : 16750 FIFO level set (64 byte FIFOs).








     PCL4C Reference Manual                                    Page 9

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

      Syntax int SioFlow(int Port,int Tics)
             /* Port: Port selected (COM1 thru COM20) */
             /* Tics: # tics before timeout */

      Remark The SioFlow function is used to enable or disable hardware
             flow control.  Hardware flow control uses RTS and CTS to
             control data flow between the modem and the computer. Refer to
             the Serial Communications Manual (ASYNC.TXT) for a
             discussion of flow control. To enable hardware flow control,
             call SioFlow with Tics > 0.

             "Tics" is the number of timer tics (18.2 / sec) 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 and SioPuts


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

      Syntax int SioGetc(int Port,int Tics)
             /* 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.





     PCL4C Reference Manual                                    Page 10

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

      Syntax int SioGetDiv(int Port)
             /* Port: Port selected (COM1 thru COM20) */


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

             Baud  Divisor    Baud  Divisor    Baud  Divisor

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

             or by use of the general 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 SioParms.



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

      Syntax int SioGets(int Port,char *Buffer,int Length)
             /* Port: Port selected (COM1 thru COM20) */
             /* Buffer: Character buffer */
             /* Length: Length of Buffer (# of requested bytes) */

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

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

       Other SioUnGetc and SioGetc.






     PCL4C Reference Manual                                    Page 11

      +-------------+-----------------------------------------------------+
      |   SioInfo   |  Return PCL4C library information.                  |
      +-------------+-----------------------------------------------------+

      Syntax int SioInfo(char Cmd)
             /* Cmd: Command (see below) */

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

      Return (Cmd description)
                'V' : Version [as hex byte XY means version X.Y]
                'I' : TRUE if library compiled with TX interrupts enabled.
                'M' : Memory model (0=small,1=compact,2=medium,3=large)
                'P' : TRUE if 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 int SioIRQ(int Port,intIRQcode)
             /* 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, you will not need
             to call SioIRQ. You should 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
             PCL4C 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.



     PCL4C Reference Manual                                    Page 12

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

      Syntax int SioLine(int Port)
             /* 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  = Framing 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 int SioLoopBack(int Port)
             /* 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
             defective. Many UARTs must be reset after running a loopback
             test.

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














     PCL4C Reference Manual                                    Page 13

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

      Syntax int SioModem(int Port, int Mask)
             /* 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(int Port,int Parity,int StopBits,int DataBits)
             /* Port:     Port selected (COM1 - COM20) */
             /* Parity:   Parity code [0,1,2] */
             /* StopBits: Stop bits code [0,1] */
             /* DataBits: Word length code [0,1,2,3] */

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

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

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

       Other SioReset.

     PCL4C Reference Manual                                    Page 14

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

      Syntax int SioPorts(int Ports,int FirstPort,int Status,int Code)
             /* Ports:     Total number of ports */
             /* FirstPort: First DigiBoard or BOCA port */
             /* Status:    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 PCL4C Users Manual for more information on the
             DigiBoard and BOCA board.  Many other multiport boards 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 int SioPutc(int Port,char Ch)
             /* 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 PCL4C 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 SioPuts, SioFlow, and SioTxFlush.


     PCL4C Reference Manual                                    Page 15

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

      Syntax int SioPuts(int Port,char *Buffer,int Length)
             /* 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 int SioRead(int Port,int Reg)
             /* 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 UART
             contents.

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

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

       Other SioLine and SioModem.





     PCL4C Reference Manual                                    Page 16

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

      Syntax int SioReset(int Port,int BaudCode)
             /* 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 PCL4C. SioReset uses the
             parity, stop bits, and word length value previously set if
             SioParm was called, otherwise the default values (see SioParm)
             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 specifying 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 "PCL4C.H" 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.
             -14 : Bad or missing UART. Hardware may not be present.
             -15 : Port already enabled. SioReset was already called.
             -16 : Interrupt already in use.
             >=0 : Port has been reset. Return value is line status.

       Other SioBaud, SioParms, SioRxBuf, SioTxBuf, SioDone & SioUART.


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

      Syntax int SioRI(int Port)
             /* 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.




     PCL4C Reference Manual                                    Page 17

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

      Syntax int SioRTS(Port, char Cmd)
             /* 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 int SioRxBuf(int Port,int Selector,SizeCode)
             /* Port:     Port selected (COM1 thru COM20) */
             /* Selector: Receive buffer segment [selector for PM] */
             /* SizeCode: Buffer size code */

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

                Size Code       Buffer Size    PCL4C.H Name
                   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.


     PCL4C Reference Manual                                    Page 18

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

      Syntax int SioRxClear(int Port)
             /* 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 int SioRxQue(int Port)
             /* 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.




















     PCL4C Reference Manual                                    Page 19

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

      Syntax int SioSetDiv(int Divisor)
             /* Divisor: User baud rate divisor */

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

                 BaudRate = 115200 / Divisor

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

                 SioSetDiv(4); SioBaud(Port,BaudUser);

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

      Return >0 : Previous user baud rate divisor.

       Other SioGetDiv.




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

      Syntax long SioTimer(void)

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

       Other SioDelay

















     PCL4C Reference Manual                                    Page 20

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

      Syntax int SioTxBuf(int Port,int Selector,int SizeCode)
             /* Port:     Port selected (COM1 thru COM20) */
             /* Selector: Receive buffer segment [selector in PM] */
             /* SizeCode: Buffer size code */


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

                Size Code       Buffer Size    PCL4C.H Name
                   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 SioRxBuf, SioReset and Code Examples.

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

      Syntax int SioTxClear(int Port)
             /* Port: Port selected (COM1 thru COM20) */

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

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

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

       Other SioTxFlush and SioTxQue.





     PCL4C Reference Manual                                    Page 21

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

      Syntax int SioTxFlush(int Port)
             /* Port: Port selected (COM1 thru COM20) */

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

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

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

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

      Other SioTxQue.


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

      Syntax int SioTxQue(int Port)
             /* Port: Port selected (COM1 thru COM20) */

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

             This function is not used unless the transmitter interrupts
             are enabled.  Refer to the PCL4C Users Manual for information
             on transmitter (TX) interrupts.

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

       Other SioTxFlush.










     PCL4C Reference Manual                                    Page 22

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

      Syntax int SioUART(int Port,int Address)
             /* 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 PCL4C 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 int SioUnGetc(int Port,char Ch)
             /* 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.

















     PCL4C Reference Manual                                    Page 23

                          Function Summary



      +-------------+----------+----------+----------+----------+
      | Function    |   Arg1   |   Arg2   |   Arg3   |   Arg4   |
      +-------------+----------+----------+----------+----------+
      | SioBaud     | Port     | BaudCode |          |          |
      | SioBrkKey   |          |          |          |          |
      | SioBrkSig   | Port     | Cmd      |          |          |
      | SioCTS      | Port     |          |          |          |
      | SioDCD      | Port     |          |          |          |
      | SioDelay    | Tics     |          |          |          |
      | SioDone     | Port     |          |          |          |
      | SioDSR      | Port     |          |          |          |
      | SioDTR      | Port     | Cmd      |          |          |
      | SioEmpty    | Port     |          |          |          |
      | SioError    | Code     |          |          |          |
      | SioFIFO     | Port     | LevelCode|          |          |
      | SioFlow     | Port     | Tics     |          |          |
      | SioGetc     | Port     | Tics     |          |          |
      | SioGetDiv   | Port     |          |          |          |
      | SioGets     | Port     | Buffer   | Length   |          |
      | SioInfo     | Cmd      |          |          |          |
      | SioIRQ      | Port     | IRQcode  |          |          |
      | SioLine     | Port     |          |          |          |
      | SioLoopBack | Port     |          |          |          |
      | SioModem    | Port     | Mask     |          |          |
      | SioParms    | Port     | Parity   | StopBits | DataBits |
      | SioPorts    | NbrPorts | FirstPort| StatusReg| Code     |
      | SioPutc     | Port     | Ch       |          |          |
      | SioPuts     | Port     | Buffer   | Length   |          |
      | SioRead     | Port     | Reg      |          |          |
      | 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       |          |          |
      +-------------+----------+----------+----------+----------+










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





























     PCL4C Reference Manual                                    Page 25

                             Code Examples



      SioRxBuf / SioTxBuf Example


      int BufSize = 1024;
      int SizeCode = Size1024;
      char far *Ptr;
      int BufSeg;
      ...
      /* allocate receive buffer + 16 bytes */
      Ptr = (char far *) _fmalloc(BufSize+16);
      BufSeg = FP_SEG(Ptr) + ((FP_OFF(Ptr)+15)>>4);
      /* pass receive buffer segment to PCL4C */
      SioRxBuf(Port,BufSeg,SizeCode);
      /* allocate transmit buffer + 16 bytes */
      Ptr = (char far *) _fmalloc(BufSize+16);
      BufSeg = FP_SEG(Ptr) + ((FP_OFF(Ptr)+15)>>4);
      /* pass transmit buffer segment to PCL4C */
      SioTxBuf(Port,BufSeg,SizeCode)


      DigiBoard Example


      /* use 0x140 for odd IRQs & 0x141 for even IRQs */
      SioPorts(8,COM1,0x140,DIGIBOARD);
      for(i=COM1;i<=COM8;i++)
        {/* set DigiBoard UART addresses */
         SioUART(i,0x100+8*i);
         /* set DigiBoard for IRQ5 */
         SioIRQ(i,IRQ5);
        }


      BOCA Board Example


      /* use base port + 7 */
      SioPorts(16,COM1,0x100+7,BOCABOARD);
      for(i=COM1;i<=COM16;i++)
        {/* set BOCA Board UART addresses */
         SioUART(i,0x100+8*i);
         /* set DigiBoard for IRQ5 */
         SioIRQ(i,IRQ5);
        }










     PCL4C Reference Manual                                    Page 26

