PCjs Machines

Home of the original IBM PC emulator for browsers.


PC-SIG Diskette Library (Disk #2695)

[PCjs Machine "ibm5170"]

Waiting for machine "ibm5170" to load....


                      C Communications Library ( CCL )
                               Version 1.0
                              14 January 1991
                            Copyright (C) 1991
                              By MarshallSoft
                            All rights reserved
                                PO Box 4543
                             Hunstville, AL 35815
                               (205) 881-4630
                                                               Page 1
                             Table of Contents
          Chapter                                     Page
          Serial COM Ports.............................5
          National INS8250 UART........................7
          Revision History.............................7
          Using the Library............................8
             Compiling & Linking.......................9
          Library Reference...........................11
          Error Code Summary..........................33
                                                               Page 2
          The  C  Communications  Library  (  CCL  ) is  an  asynchronous
          communications  library   designed   for   experienced   software
          developers  programming  in  Microsoft  C  or  Turbo  C.   An IBM
          PC/XT/AT or compatible is required.  The CCL features:
          o  16 communications functions + 6 support functions.
          o  Receiver is interrupt driven.
          o  Runs from 300 baud to 115,200 baud.
          o  Supports COM1, COM2, COM3, and COM4.
          o  Adjustable receive queues from 8 bytes to 16 KB.
          o  Control-BREAK error exit.
          o  11 comm error conditions trapped.
          o  Supports all memory models.
          o  Allows 2 ports to run concurrently.
          o  Complete modem control & status.
          o  Written in hand optimized assembly language.
          o  Low overhead & very reliable !
          A typical application program  using  CCL  might  look  like  the
          following code outline:
          | #include "ccl.h"                                      |
          |                                                       |
          | char far buffer[1024];                                |
          | main()                                                |
          | {                                                     |
          |  SioRxBuf(Port,Buffer,Size1024);                      |
          |  SioParms(Port,NoParity,OneStopBit,SevenDataBits);    |
          |  SioReset(Port,Baud2400);                             |
          |                                                       |
          |  ...application code...                               |
          |                                                       |
          |  SioDone(Port);                                       |
          | }                                                     |
          A   simple   terminal  emulator  program CALLPGM.C is provided in
          source code form as an example  of  the  use  of  CCL  functions.
          CALLPGM  can  be  used  to  call  up  bulletin  board services or
          mainframe computers.
          If you find any problems with the  C  Communications  Library  or
          have  any  suggestions  for improvement, please call or write.  A
          Pascal version of CCL ( to be called PCL ) may  be  available  if
          demand warrants.
          Custom versions of CCL can be developed for special needs. Custom
          communication packages can also be developed. Call for prices.
                                                               Page 3
          The  shareware  version  of  CCL.LIB  is provided so that you may
          personally determine the usefulness of the product for  yourself.
          If you can use CCL.LIB, please register your use with us.
                PO Box 4543
                Huntsville, AL
          Please  pay  by  check  in  US  dollars.  Payment  must accompany
          purchase orders. Print the file CCL.INV if an invoice is  needed.
          The registered package is $35 postpaid and includes:
          o  CCL.LIB   C Communications Library - without shareware screen.
          o  CCL.ASM   C Communications Library source code.
          o  CCL.DOC   C Communications Library documentation file.
          o  XMODEM.C  Source for the XMODEM file transfer code.
          o  YMODEM.C  Source for the YMODEM file transfer code.
          o  LZW.C     Source for Lempel-Ziv-Welch file compression code.
          o  CRC.C     Source for cyclic redundancy check code.
          o  CALLPGM.C Source for terminal emulator. Uses XMODEM & YMODEM.
          o  Backbone bound printed users manual.
          o  Telephone support for one year.
          o  All future updates are $10
          CCL.ASM  is  the  source code for the library. The source code is
          copyrighted by MarshallSoft. The user is granted a license to use
          the CLL object code in his own application only. CLL.ASM  is  not
          shareware and may not be sold or given away to anyone.
          XMODEM.C  is  an  implementation  of the industry standard XMODEM
          protocol, including XMODEM/1K ( uses 1K blocks ) and XMODEM/CRC (
          uses CRCs instead of checksums ). Virtually every bulletin  board
          offers XMODEM file transfer.
          YMODEM.C  is  basically  XMODEM/CRC/1K  with the  file  name  and
          length   encoded in the first block. Thus, the receiver knows the
          file  length  and  filename.  YMODEM  is also widely available on
          bulletin board services.
          LZW.C   is   an   implementation  of  the  Lempel-Ziv-Welch  file
          compression algorithm.  It  is  used  in  many  file  compression
          utilities available today. LZW can compress file to as much as 40
          percent of their original size.
          CRC.C is an implementation of the 16 bit Cyclic Redundancy  Check
          algorithm   as   specified   by  the  Comsultative  Committee  in
          International Telegraphy and Telephoney ( CCITT ). It is used  in
          XMODEM/CRC  and  in  YMODEM. It will detect 99.99 percent of data
          The  registered user will receive the  latest  version  of CCL by
          return  mail.   A  5.25"  diskette  is  provided  unless  a  3.5"
          diskette is requested when ordering.
                                                               Page 4
                             Serial COM Ports
          IBM  PC  compatible  computers can have up to four serial  ports.
          The  BIOS  table  located  at address 40:0000 has room  for  four
          communication  port  addresses: COM1 to COM4. During boot up, the
          COM1 and COM2 addresses are placed in the  BIOS  table  providing
          that  the  hardware  is present. Unfortunately, the COM3 and COM4
          addresses are not placed in the table in  many  IBM  compatibles.
          This  can  be  corrected by using DEBUG to assemble the following
          program SETCOM3 which should be added to the  AUTOEXEC.BAT  file.
          When  executed,  this  program  will place the standard COM3 port
          address 03E8 in the BIOS table. For COM4, change 03E8 to 02E8 and
          [0004] to [0006].
                   PUSH DS
                   MOV AX,0040
                   MOV DS,AX
                   MOV AX,03E8
                   MOV [0004],AX
                   POP DS
                   MOV AX,4C00
                   INT 21
          If you have never used DEBUG, refer  to  your  MSDOS  manual  for
          detailed instructions.
                                                               Page 5
          RS-232    is    the   name  of the serial data interface standard
          used  to  connect  computers  to  modems.   Most  IBM  compatible
          computers are built with at least one serial port and use  either
          DB9 ( 9 pin ) or DB25 ( 25 pin ) connectors.
          A summary of these pins and  their  function  follows.  For  more
          detailed information, refer to one of the many books dealing with
          RS-232 interfacing.
          Signal Ground         Pin 7 (DB25),  Pin 5 (DB9)
          The  SG line is used as the common signal ground, and must always
          be connected.
          Transmit Data         Pin 2 (DB25),  Pin 3 (DB9)
          The TX line is used to carry data from the computer to the modem.
          Receive Data          Pin 3 (DB25),  Pin 2 (DB9)
          The RX line is used to carry data from the modem to the computer.
          Data Terminal Ready   Pin 20 (DB25), Pin 4 (DB9)
          The  DTR line is used by the computer to signal the modem that it
          is ready.
          Data Set Ready        Pin 6 (DB25),  Pin 6 (DB9)
          The DSR line is used by the modem to signal the computer that  it
          is ready.
          Request to Send       Pin 4 (DB25),  Pin 7 (DB9)
          The   RTS  line  is used to "turn the line around" in half duplex
          modems, but is not necessary in full duplex modems.
          Clear to Send         Pin 5 (DB25),  Pin 8 (DB9)
          The CTS line, like the RTS line, in not necessary in full  duplex
          Data Carrier Detect    Pin 8 (DB25),  Pin 1 (DB9)
          The DCD line is used by the modem to signal the computer  that  a
          data carrier signal is present.
          Ring Indicator         Pin 22 (DB25), Pin 9 (DB9)
          The RI line is asserted when a 'ring' occurs.
                                                               Page 6
                             National INS8250
          The   C   Communications   Library   is  based  on  the  standard
          National INS8250 UART. The 8250  consists  of  6  register  ports
          based at the following standard addresses:
          COM1 = 3F8H  COM2 = 2F8H  COM3 = 3E8H  COM4 = 2E8H
          If  you are not familiar with the INS8250, several good books are
          available.  Although  a knowledge of the 8250 is not necessary to
          use CCL, a general  knowledge  of  the  theory  of  operation  of
          Univeral  Asynchronous  Receiver  /  Transmitters  (  UARTs  ) is
          Offset R/W  Register
            0       R/W   Receiver ( read ) / Transmitter ( write )
            1       R/W   Interrupt Enable
            2       R     Interrupt Identification
            3       R/W   Data Format ( Line Control )
            4       R/W   RS-232 ( Modem ) Control
            5       R/W   Line Status
            6       R/W   RS-232 ( Modem ) Status
                             Revision History
          Version 1.0 -- 14 January 1991 -- original release.
          The  user  of this software assumes all liability for its use. In
          no case shall MarshallSoft be liable for any  damages,  including
          any incidental or consequential damages.
                                                               Page 7
                             Using the Library
          The first thing  to  do  is  to  copy  all  the  files  from  the
          CCL distribution disk to a working disk, and put the original CCL
          distribution disk in a safe place.
          The  C  Communications  Library  is  provided   as   the  library
          file  CCL.LIB.   It  has  been  tested  with both Microsoft C and
          Turbo C compilers.  CCL.LIB may be used with  any  memory  model.
          However, your application must be certain to include CCL.H and to
          specifically declare the receive buffers as FAR ( see SioRxBuf ).
          Please examine the CCL.H file. Note that COM1 is defined as  port
          zero,  not  port  one. The user must assume the responsibilty for
          passing  the  correct  information  when  calling  CCL functions.
          Function prototypes are not provided in CCL since some earlier  C
          compilers  don't support them. However, the CCL.H file can easily
          be modified to provide them if so desired.
          For   an   example   of  CCL  use,  examine the terminal emulator
          program  CALLPGM.C.   It  uses  most every CCL function. The user
          should compile CALLPGM.C and link with CCL.LIB as a test  of  the
          If  you  have  two  computers, then you can connect them together
          with a null  modem  cable  and  run  CALLPGM  on  both  machines.
          Whatever  is typed on one machine should appear on the other, and
          vice versa. Depending on the design  of  the  null  modem  cable,
          CALLPGM.C  may  need  to be modified so that it does not wait for
          DSR & CTS. This is clearly documented in the CALLPGM.C code.
          If you have a modem, then use CALLPGM to  call  up  any  bulletin
          board  system  (  BBS  ).  There  are  many  free BBSs around the
          country. Look in any issue of "Computer Shopper" (  available  in
          bookstores,  computer shops, and many grocery stores ) for a list
          of current systems.
          CCL functions can be called from any language  supporting  the  C
          language  calling  convention  and FAR arrays and functions.  See
          your compiler manual.
                                                               Page 8
                             Compiling and Linking
          CCL  has  been  tested with both Microsoft C and Turbo C. Other C
          compilers may work as well provided that they recognize  the  FAR
          Any  memory model can be used with CCL since all functions in CCL
          are declared as  FAR.  Recall  that  the  receive  buffer  (  see
          function SioRxBuf ) must also be declared as FAR.  If  two  ports
          are  to  be  run  simultaneously, be sure to use seperate receive
          Registered users may  wish  to  assemble  CLL.ASM.  Use  the  /MX
          switch  in  order to disable automatic conversion from lower case
          to upper case.  If the /MX switch  is  not  used,  then  all  CLL
          function  references in C code must be in upper case. To assemble
          using the Microsoft assembler:
          MASM CCL /MX;
          Then make CCL.OBJ into a library file:
          When compiling with the Microsoft compiler, use the /Ze switch to
          enable  recognition of the FAR keyword. To compile and link using
          Microsoft C:
          MSC -Ze TE;
          To compile and link using Turbo C:
                                                               Page 9
          If you cannot get your application to run properly, first compile
          and run  the  terminal  emulator  program   CALLPGM  provided  on
          your distribution disk.
          If  CALLPGM  runs  correctly,  then  you  have made a programming
          mistake in your  application.   MarshallSoft  cannot  debug  your
          application,  especially  over  the telephone!  However, consider
          each of the  following  when  searching  for  an  error  in  your
          1.  Have you included the file CCL.H in your application ?
          2.  Have  you declared your receive buffer to be FAR ? Your code
              should include something like:
                        char far Buffer[1024];
          3.  Is your receive buffer large enough ? If  you  are  using  1K
              data  blocks in YMODEM, then your receive buffer should be 1K
              or more.
          4.  Have you selected too high a baud rate ?  Always  start  with
              the   slowest   baud   rate.   If  only one COM port is being
              run, you should be able to run at 38400 baud.
          5.  Are  you  attempting  to  run  another  application  in  the
              background  ?  Try running without any other programs running
              in the background.
          6.  If  you  are  running  two COM ports simultaneously, are you
              using seperate receive buffers ? ( you should )
          7.  Did SioReset return a zero value ? If not, then you must call
              SioReset again. See CALLPGM.C for an example.
          If   CALLPGM  does  not  run,  then  either  there  is a physical
          connection problem or your computer isn't as  compatible  as  you
          thought!  Registered users can always call (205) 881 - 4630 after
          5 PM CST Monday through Friday for help.
                                                               Page 10
                             Library Reference
          The remainder of this manual list all the  CCL  functions.  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 ***/
          int code;     /* MUST be 'int', not 'char' */
          code = SioFunction(); /* any CCL function */
                                                               Page 11
          Sets the baud rate of the selected port.
          int SioBaud(Port,BaudCode)
          int Port;             /* Port selected (COM1,COM2,COM3,or COM4) */
          int BaudCode;         /* Baud code */
          The  SioBaud  function  sets  the baud rate without resetting the
          port. It is used to change the baud rate after calling SioReset.
          Baud Code        Baud Rate        CLL.H Name
             0                 300            Baud300
             1                 600            Baud600
             2                1200            Baud1200
             3                2400            Baud2400
             4                4800            Baud4800
             5                9600            Baud9600
             6               19200            Baud19200
             7               38400            Baud38400
             8               57600            Baud57600
             9              115200            Baud115200
           -2 : Port not enabled. Must call SioReset first.
           -4 : Bad port selected. Value must be 0 to 3.
          -11 : Bad baud rate code. See above code values.
          #include "ccl.h"
          /* do auto baud detect */
                        {puts("Baud rate detected");
                         ...do something here...
                                                               Page 12
          Return non-zero if the Control-BREAK key was pressed.
          int SioBrkKey()
          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 form a polling loop.  Don't mix this
          function up with SioBrkSig.
           0 : Control-BREAK was pressed.
          !0 : Control-BREAK was not pressed.
          #include "ccl.h"
          int c;
                        {puts("User typed Contrl-BREAK");
                        {c = SioKeyRead();
                 c = SioGetc(Port,0);
                 if(c!=-1)  SioCrtWrite(c);
                                                               Page 13
          Asserts, cancels, or detects  BREAK signal.
          int SioBrkSig(Port,Cmd)
          int Port;             /* Port selected (COM1,COM2,COM3,or COM4) */
          char Cmd;             /* 'A','C', or 'D' */
          The  SioBrkSig  function controls the BREAK bit in the line status
          register. The legal commands are:
              'A' to assert BREAK
              'C' to cancel BREAK
              'D' to detect BREAK
          See CALLPGM.C for an example of the use of SioBrkSig.
           -2 : Port not enabled. Must call SioReset first.
           -4 : Bad port selected. Value must be 0 to 3.
           -6 : Illegal command. Expected 'A', 'C', or 'D'.
           >0 : BREAK signal detected ( READ only )
          /* Assert BREAK for 1 second */
          /* Detect BREAK */
                {puts("BREAK signal detected");
                 /* do some more stuff */
                                                               Page 14
          Write character to the screen.
          int SioCrtWrite(ch)
          char ch;              /* character to write */
          The  SioCrtWrite  function  uses  the  BIOS  to  write  a  single
          character to the screen at the current cursor location.
          SioCrtWrite is faster than a call to the C library and  for  this
          reason is included in CCL.
          #include "ccl.h"
          if( (c = SioGetc(COM1,18)) != -1)
                {/* echo to screen */
                                                               Page 15
          Set, clear, or read the Data Terminal Ready ( DTR ) bit.
          int SioDTR(Port,Cmd)
          int Port;             /* Port selected (COM1,COM2,COM3,or COM4) */
          char Cmd;             /* command */
          The  SioDTR function controls the Data Terminal Ready ( DTR ) bit
          in the modem control register. Commands used are:
                'S'  to set DTR ( ON )
                'C'  to clear DTR ( OFF )
                'R'  to read DTR
           -2 : Port not enabled. Must call SioReset first.
           -4 : Bad port selected. Value must be 0 to 3.
           -5 : Not one of 'S', 'C', or 'R'.
            0 : DTR is OFF (READ Command).
           >0 : DTR is ON (READ Command).
          #include "ccl.h"
          /* turn DTR on for modem */
                                                               Page 16
          Delays one or more tics.
          int SioDelay(tics)
          int tics;                     /* # tics */
          The  SioDelay  function  is used to delay one or more timer tics,
          where each timer tic is approximately 55 milliseconds ( 18 to the
          second ). See SioTimer also.
          #include "ccl.h"
          SioDelay(5*18);               /* delay 5 seconds */
                                                               Page 17
          Terminates further serial processing.
          int SioDone(Port)
          int Port;             /* Port selected (COM1,COM2,COM3,or COM4) */
          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.
           -2 : Port not enabled. Must call SioReset first.
           -4 : Bad port selected. Value must be 0 to 3.
          #include "ccl.h"
          /* terminate processing for COM3 */
                                                               Page 18
          Displays error in text.
          int SioError(Code)
          int Code;          /* Error code returned from a CCL function */
          The   SioError  function displays the error in text corresponding
          to   the  error  code.  During  development  of  a communications
          application, it is a good idea to always test return  codes,  and
          print out their descriptions with SioError.
          #include "ccl.h"
          code = SioReset(Port,Baud4800);
          if(code<0) SioError(code);
                                                               Page 19
          Reads the next character from the serial line.
          int SioGetc(Port,Tics)
          int Port;             /* COM1 to COM4 */
          int Tics;             /* # timer tics */
          The SioGetc function reads 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 tics  to  the
          To specify no waiting, call SioGetc with Tics = 0.
           -2 : Port not enabled. Must call SioReset first.
           -4 : Bad port selected. Value must be 0 to 3.
           -1 : If timed out.
           >0 : Character read.
          #include "ccl.h"
          int c;   /* MUST be 'int', not 'char' !!! */
          if( (c=SioGetc(COM1,1)) != -1) printf("Character is '%c'\n", c);
          else puts("Timed out");
                                                               Page 20
          Detects if keyboard has been pressed.
          int SioKeyPress()
          The   SioKeyPress function uses the BIOS to test the keyboard for
          a key press.
          if( SioKeyPress())
                 /* do something */
                                                               Page 21
          Reads the keyboard.
          int SioKeyRead()
          The SioKeyRead function uses the BIOS to read the keyboard.  Will
          wait until a character is typed.
          SioKeyRead is faster than using the C library.
          character typed.
                 c = SioKeyRead();
                                                               Page 22
          Reads the line status register.
          int SioLine(Port)
          int Port;             /* Port selected (COM1,COM2,COM3,or COM4) */
          The   SioLine  function  reads  the  line  status  register.  The
          individual bit masks are as follows:
          0x20  = Transmitter Buffer Empty.
          0x10  = Break detected.
          0x08  = Framming error.
          0x04  = Parity error.
          0x02  = Overrun error.
          0x01  = Data ready.
          The above are documented in the file CCL.H.
          -2 : Port not enabled. Must call SioReset first.
          -4 : Bad port selected. Value must be 0 to 3.
          >0 : Line status ( rightmost byte of word ).
          #include "ccl.h"
          int rc;
          rc = LineStatus(Port);
          if(rc & (FramingError|ParityError|OverrunError))
                {if(rc & FramingError) puts("Framing Error");
                 if(rc & ParityError)  puts("Parity Error");
                 if(rc & OverrunError) puts("Overrun Error");
          else puts("No error");
                                                               Page 23
          Reads the modem status register.
          int SioModem(Port)
          The SioModem function   reads   the   modem   register.  The  bit
          definitions are as follows:
                Bit    CCL.H Name   Function
                 7      DCD         Data Carrier Detect
                 6      RI          Ring Indicator
                 5      DSR         Data Set Ready
                 4      CTS         Clear To Send
                 3      DeltaDCD    Delta DCD   ( DCD has changed )
                 2      DeltaRI     Delta RI    ( RI has changed )
                 1      DeltaDSR    Delta DSR   ( DSR has changed )
                 0      DeltaCTS    Delta CTS   ( CTS has changed )
          Bits 4 through 7 represent the absolute state of their respective
          RS-232 inputs. Bits 0 through 3 repesent a change in the state of
          their respective RS-232 inputs since last read.
          The  above definitions are also in the CCL.H file for use by your
          application program.
          -2 : Port not enabled. Must call SioReset first.
          -4 : Bad port selected. Value must be 0 to 3.
          >0 : Modem status ( rightmost byte of word ).
          /* any change in DCD or CTS ? */
              {status = SioModem(Port,DCD|CTS);
               if(delta&DeltaDCD) {if(status&DCD) c='T'; else c='F';
               if(delta&DeltaCTS) {if(status&CTS) c='T'; else c='F';
                                                               Page 24
          Sets parity, stop bits, and word length.
          int SioParms(Port,ParityCode,StopBitsCode,WordLengthCode)
          int Port;             /* Port selected (COM1,COM2,COM3,or COM4) */
          int ParityCode;       /* parity code [0,1,2] */
          int StopBitsCode;     /* stop bits code  [0,1] */
          int WordLengthCode;   /* word length code [0,1,2,3] */
          The   SioParms  function  sets  the  parity,  stop bits, and word
          length.  If the default parity ( none ), stop bits ( 1 ), or word
          length ( 8 ) is not acceptable,  then  they  can  be  changed  by
          calling  SioParms.  SioParms can be called either before or after
          calling SioReset. See file CCL.H.
                           Value      Description    CLL.H Name
              ParityCode:   *0        no parity      NoParity
                             1        odd parity     OddParity
                             2        even parity    EvenParity
              StopBitsCode:  *0       1 stop bit     OneStopBit
                              1       2 stop bits    TwoStopBits
              WordLengthCode: 0       5 data bits    FiveDataBits
                              1       6 data bits    SixDataBits
                              2       7 data bits    SevenDataBits
                             *3       8 data bits    EightDataBits
          * = Default
           -2 : Port not enabled. Must call SioReset first.
           -4 : Bad port selected. Value must be 0 to 3.
           -7 : Bad parity code selected. Value must be 0 to 2.
           -8 : Bad stop bits code. Value must be 0 or 1.
           -9 : Bad word length code. Value must be 0 to 3.
          #include "ccl.h"
                                                               Page 25
          Transmit a character over a serial line.
          int SioPutc(Port,c)
          int Port;             /* Port selected (COM1,COM2,COM3,or COM4) */
          char c;               /* character to send */
          The SioPutc function transmits one character  over  the  selected
          serial line.
          -2 : Port not enabled. Must call SioReset first.
          -4 : Bad port selected. Value must be 0 to 3.
          #include "ccl.h"
          char crc;
          char buffer[128];
          crc = 0;
                {crc = crcupdate( buffer[i], crc);
                 SioPutc(Port, buffer[i]);
                                                               Page 26
          Sets, clears, or reads the Request  to  Send ( RTS ) bit.
          int SioRTS(Port,Cmd)
          int Port;             /* COM1 to COM4 */
          char Cmd;             /* command */
          The  SioRTS  function controls the Request to Send ( RTS ) bit in
          the modem control register. Commands are as follows:
                     'S'  set RTS ( ON )
                     'C'  clear RTS ( OFF )
                     'R'  read RTS
          -2 : Port not enabled. Must call SioReset first.
          -4 : Bad port selected. Value must be 0 to 3.
          -5 : Command is not one of 'S', 'C', or 'R'.
           0 : RTS is OFF (READ Command).
          >0 : RTS is ON  (READ Command).
          #include "ccl.h"
          /* turn on RTS for modem */
                                                               Page 27
          Initialize a serial port for processing.
          int SioReset(Port,BaudCode)
          int Port;             /* Port selected (COM1,COM2,COM3,or COM4) */
          int BaudCode;         /* baud code */
          The  SioReset  function  initializes  the  selected  serial port.
          SioReset should be called after calling SioParm and SioRxBuf  but
          before  making  any other calls to CCL. 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.
          See SioBaud for a list of the baud rate codes, or see "CCL.H".
           -4 : Bad port selected. Value must be 0 to 3.
          -11 : Bad baud rate code selected. Value must be 0 to 9.
          #include "ccl.h"
          char far Buffer[128];
          int rc;
          rc = SioReset(Com1,Baud38400);
          if(rc==0) puts("RESET ok");
          else if(rc<0) SioError(rc);
                {if(rc&OverrunError) puts("Overrun Error");
                 if(rc&ParityError) puts("Parity Error");
                 if(rc&FramingError) puts("Framing Error");
                 if(rc&BreakDetected) puts("Break Detected");
                                                               Page 28
          Sets up receive buffers.
          int  SioRxBuf(Port,Buffer,SizeCode)
          int Port;             /* Port selected (COM1,COM2,COM3,or COM4) */
          char far *Buffer;     /* Receive buffer */
          int  SizeCode;        /* Buffer size code */
          The  SioRxBuf function passes the address and size of the receive
          buffer to CCL. Recall that CCL requires a receive buffer for each
          port in simultaneous operation  since  the  receive  function  is
          interrupt  driven.  SioRxBuf passes the receive buffer to CCL for
          both the primary ( COM1/COM3 ) and secondary ( COM2/COM4 ) ports.
          It must be called before any incoming characters can be received.
          SioRxBuf should be called before SioReset. Buffer size codes  are
          listed in "CCL.H".
          Size Code       Buffer Size    CLL.H Name
              0              8 bytes        Size8
              1             16 bytes        Size16
              2             32 bytes        Size32
              3             64 bytes        Size64
              4            128 bytes        Size128
              5            256 bytes        Size256
              6            512 bytes        Size512
              7           1024 bytes        Size1024
              8           2048 bytes        Size2048
              9           4096 bytes        Size4096
             10           8192 bytes        Size8192
             11          16384 bytes        Size16384
           -2 : Port not enabled. Must call SioReset first.
           -4 : Bad port selected. Value must be 0 to 3.
          -10 : Bad buffer size code. Value must be between 0 and 11.
          #include "ccl.h"
          char far RxBuf[128];
          SioRxBuf( COM1, RxBuf, 128);
                                                               Page 29
          To flush the receive buffer associated with the specified port.
          int SioRxFlush(Port)
          int Port;             /* Port selected (COM1,COM2,COM3,or COM4) */
          The  SioRxFlush  function  will  delete  any  characters  in  the
          receive  buffer  for  the  specified  port.  After execution, the
          receive  buffer  will  be empty. Call SioRxBuf after resetting  a
          port in order to delete any spurious characters.
           -2 : Port not enabled. Must call SioReset first.
           -4 : Bad port selected. Value must be 0 to 3.
          #include "ccl.h"
          char far buffer[1024];
          /* setup receive buffer & reset port */
          /* flush any spurious character */
          /* ready for serial processing ! */
                                                               Page 30
          Returns the number of characters in the receive queue.
          int SioRxQue(Port)
          int Port;             /* Port selected (COM1,COM2,COM3,or COM4) */
          The SioRxQue function will return the  number  of  characters  in
          receive queue. It can be used to implement XON/XOFF flow control.
           -2 : Port not enabled. Must call SioReset first.
           -4 : Bad port selected. Value must be 0 to 3.
          #include "ccl.h"
          #define XON 0x11
          #define XOFF 0x13
          int count;
          char last = XON;
          char far Buffer[128];
          /* implement XON / XOFF */
          count = SioRxQue(COM1);
                 last = XOFF;
                 last = XON;
                                                               Page 31
          Returns    the    number   of   system clock tics since midnight.
          long SioTimer()
          The SioTimer function will return the number of system clock tics
          since midnight, at 18.2065 tics  per  second.  This  function  is
          usefull for timeing various functions. Also see SioDelay.
          timer tics
          #include "ccl.h"
          long time;
          time = SioTimer();
          /* do some stuff */
          printf("Elasped time = %ld tics\n", SioTimer() - time );
                                                               Page 32
                             Error Code Summary
          Code        Description
            0          No error.
           -1          Timeout waiting for input. Only returned by SioGetc.
           -2          Port not enabled. Must call SioReset first.
           -3          No buffer available. Must call SioRxBuf before
                       calling SioReset.
           -4          Bad port specified. Must be 0 to 3. Recall that COM1
                       is port 0, COM2 is port 1, etc.
           -5          Expected 'S', 'C', or 'R' as second argument.
           -6          Expected 'A', 'C', or 'D' as second argument.
           -7          Bad parity code specified. Must be 0 to 7.
           -8          Bad stop bits code specified. Must be 0 or 1.
           -9          Bad wordlength code specified. Must be 0 to 3.
          -10          Bad buffer size code specified. Must be 0 to 11.
          -11          Bad baud rate code. Must be 0 to 9.
                                                               Page 33


Disk No: 2695
Disk Title: C Communications Library
PC-SIG Version:    S1

Program Title: C Communications Library
Author Version: 1.0
Author Registration: $35.00
Special Requirements: C compiler and modem.

The C COMMUNICATIONS LIBRARY is an asynchronous communications library
designed for experienced software developers programming in Microsoft C
or Turbo C.

Sixteen communications functions as well as six support functions are

Included are:

~ Set Baud Rate for a selected port

~ Monitor CTRL-BREAK key

~ Write Char to screen,

~ Set/Clear/Read the data terminal ready bit

~ Delay

~ Terminate selected port

~ ...and many more

Communications rates from 300 to 115,200 baud are supported.  The
Receive queues are adjustable from 8 bytes to 16KB.  All four ports,
COM1 through COM4, are supported.  (Most libraries only provide support
for COM1 and COM2.)  Additionally, two ports can be run concurrently.

The C COMMUNICATIONS LIBRARY provides complete modem control and status.

Eleven different communications errors can be trapped and reported.
There is even support for the CTRL-BREAK error exit.  The library
supports all memory models and was written in optimized assembly
language for small size and fast speed.

The source code for a simple terminal emulator program is provided as an
example of the use of the library functions.  This sample program can be
used to call up bulletin board services and mainframe computers, or even
to build a specialized communications interface for your application.

The C COMMUNICATIONS LIBRARY can be called from any language that
supports the C-language calling convention and FAR arrays and functions.

1030D East Duane Avenue
Sunnyvale  Ca. 94086
(408) 730-9291
(c) Copyright 1991 PC-SIG, Inc.

Directory of PC-SIG Library Disk #2695

 Volume in drive A has no label
 Directory of A:\

CCL      LIB      6144   1-12-91   7:53p
CCL      DOC     49449   1-12-91   8:09p
CCL      H        1856   1-10-91   9:18p
CCL      INV      1072   1-11-91   7:48p
CALLPGM  C        5052   1-13-91   9:07a
PREVIEW  EXE      7347   4-18-91   1:15p
GO       BAT       105   7-26-91   1:17a
FILE2695 TXT      1828   7-25-91  12:22a
        8 file(s)      72853 bytes
                       85504 bytes free