pcl4w.usr

C语言通讯程序库windows版

                              Personal Communications Library

                                       For Windows


                                         (PCL4W)



                                      USERS MANUAL





                                       Version 1.01

                                       Feb 21, 1994




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




                                   Copyright (C) 1994
                                   All rights reserved



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

                                   Voice 205-881-4630
                                   FAX   [phone]
                                   BBS   205-880-9748

























             PCL4W Users Manual                                                Page 1
                                   C O N T E N T S





              Chapter                                                   Page

              1.0 Introduction................................................3
                  1.1 User Support............................................4
                  1.2 A Typical Application...................................5
                  1.3 Installation............................................6
              2.0 Library Organization........................................7
                  2.1 Configuration...........................................7
                  2.2 Initialization & Termination............................7
                  2.3 Modem Control & Status..................................8
                  2.4 Serial I/O..............................................8
                  2.5 Error Detection.........................................9
                  2.6 General Support.........................................9
              3.0 Library Overview...........................................10
                  3.1 Dynamic Link Libraries.................................10
                  3.2 DOS Protected Mode Interface...........................10
                  3.3 Memory Models..........................................10
                  3.4 Using the Library......................................10
                  3.5 Example Programs.......................................11
                  3.6 Making the Library.....................................11
              4.0 Talking to Your Modem......................................12
                  4.1 Modem Standards........................................12
                  4.2 Flow Control...........................................13
                  4.3 Modem Initialization...................................14
              5.0 Problems...................................................15
              6.0 Serial Communications......................................16
                  6.1 Communications Basics..................................16
                  6.2 Standard Port Addresses................................17
                  6.3 Running 3 or 4 Ports Concurrently......................18
                  6.4 Using the DigiBoard....................................19
                  6.5 Transmitter Interrupts.................................20
                  6.6 RS232 Signals..........................................21
                  6.7 National INS8250, INS16450, and INS16550 UARTs.........22
                  6.8 Register Summary.......................................23
              7.0 Example Programs...........................................25
                  7.1 SIMPLE.C...............................................25
                  7.2 TERM.C.................................................26
              8.0 Legal Issues...............................................27
                  8.1 Registration...........................................27
                  8.2 License................................................28
                  8.3 Warranty...............................................28
              9.0 Summary....................................................29
                  9.1 Revision History.......................................29
                  9.2 Function Summary.......................................29
                  9.3 Further Reading........................................29
             10.0 Other MarshallSoft Computing products for C................30
                 10.1 The Personal Communications Library for C..............30
                 10.2 The LZW Data Compression Library for C.................30
                 10.3 The EMS Expanded Memory Library for C..................30












             PCL4W Users Manual                                                Page 2
              1.0 Introduction


              The  Personal  Communications Library for Windows (PCL4W) is an asynchronous
              communications dynamic link library (DLL) for software developers using  the
              Microsoft  Windows  7.0  (or  higher)  compiler  and  Windows  3.1  Software
              Development Kit (SDK) or the Borland 3.1  (or  higher)  windows  development
              environment.  A 80386 machine or higher is recommended.


              o 30+ communications functions.
              o Supports the high performance INS16550 UART.
              o Supports the PC/4 and PC/8 DigiBoard.
              o Supports hardware (RTS/CTS) flow control.
              o Interrupt driven receiver & (optionally) transmitter.
              o Supports 300 baud to 115,200 baud.
              o Supports COM1 through COM4 (through COM10 with DigiBoard).
              o Adjustable queues from 8 bytes to 32 KB.
              o Control-BREAK error exit.
              o 18 communications error conditions trapped.
              o Allows 4 ports to run concurrently (10 with DigiBoard).
              o Complete modem control & status.
              o Written in assembly language for small size & high speed.
              o Terminal program featuring ASCII (with XON/XOFF), XMODEM,
                YMODEM, & YMODEM-G.


              Why should you buy PCL4W? Consider the following:

                 COMPLETE  -  PCL4W is complete since it provides absolute control of the
                              serial ports (including the high performance INS16550).

                  COMPACT  -  PCL4W is very compact at less than 6 KB.  Your  application
                              doesn't carry a lot of excess code.

                     FAST  -  PCL4W is fast.  It will run at 115200 baud on all 80386 and
                              up machines.

                  SUPPORT   - If  you  get  stuck,   you will talk to the programmer that
                              wrote the code, not a person hired to answer the phone.

                      BBS  -  A user support BBS is available (2400 to 9600 baud, N81) in
                              order to provide immediate support as necessary.

               NEWSLETTER  -  One year  subscription  to  the  MSC  newsletter discussing
                              communications problems and solutions (published quarterly).

                    PRICE  -  You get PCL4W for a very reasonable price !

                 UPGRADES  -  Once  you  buy  PCL4W, you can always update to the most recent
                              version for a very reasonable cost.

               COMPATIBLE  -  PCL4W  is  call  for call compatible with the MSDOS based
                              version PCL4C except for two functions in which delay  times
                              are no longer necessary.


              Our goal is to provide a robust serial communications library that that  you
              and your customers can depend upon.








             PCL4W Users Manual                                                Page 3
              1.1 User Support


              We want you to be successful in developing your applications using PCL4W! We
              depend on our customers to let us know what they need  in  a  communications
              library.   This  means we are committed to providing the best communications
              library that we can. If you have any suggestions or comments, please let  us
              know.

              If you are having a problem using PCL4W, call us at 205-881-4630 between 1PM
              and  9PM CST Monday, Wednesday, and Friday; 5PM to 9PM Tuesday and Thursday;
              1PM to 5PM Saturdays, or FAX us at the same telephone number at any time (24
              hours).  You can also call at other times and leave a message, and call back
              later for a reply.  However, we can only answer questions  with  respect  to
              using the PCL4W library.  We cannot help you program your application.

              You may also call our User Support BBS (2400 to 9600 baud, no parity, 8 data
              bits,  1  stop  bit)  at 205-880-9748 and leave a message (address it to the
              SYSOP).  We will usually have a reply ready for you within 24 hours.

              The BBS  is  available  24  hours  per  day  except  at  2  PM  Sundays  for
              maintenanace. All files are in standard ZIP format. The BBS will contain the
              latest  shareware  version  of  all MarshallSoft products as well as related
              files such as:

                   BUGS.ZIP  --  Bug report.
                   NEWS.ZIP  --  Latest news regarding our products.

              The MarshallSoft  Computing,  Inc.   newsletter  "Comm  Talk"  is  published
              quarterly.  It discusses various communications problems and solutions using
              PCL4W  as  well  as related information. Registered users receive a one year
              complimentary subscription  when  first  registering  and  for  each  update
              purchased.

              Of  course,  you can always write to us. You should receive a reply within a
              week or so. Please don't mail hardware without first talking to us.

              We  recommend  the following steps if you believe that you have discovered a
              bug in the library:

              (1) Create the smallest, simpliest test program  possible  that  demonstates
              the problem.

              (2)  Document  your  exact  machine  configuration  and  what error the test
              program demonstates.

              (3) Upload the example source to our user support BBS or mail us a disk.

              If  the  problem can be solved with an easy work-around, we will publish the
              work-around.  If the problem requires a modification to the library, we will
              make the change and make the modified library  available  to  our  customers
              without charge.















             PCL4W Users Manual                                                Page 4
              1.2 A Typical Application


              In  general, there are two classes of applications that use a communications
              library like PCL4W -- those that use a modem to connect to the outside world
              and those that connect directly to a peripheral device. In  either  case,  a
              typical   application  program  using  PCL4W  might  consist  of  3  phases:
              initialization, execution, and  termination.   The  following  code  segment
              assumes a knowledge of the windows API.

              In  the  following code sgment, SioRxBuf is called to set up the a 1024 byte
              receive buffer; SioParms is called to set up the parity, stop bit count, and
              word length; SioReset is called to set the baud rate to 9600 and  reset  the
              UART (Univeral Asynchronous Receiver / Transmitter).


                   case WM_CREATE:
                      /* initialization */
                      SioRxBuf(Port,RxBuffer,Size1024);
                      SioParms(Port,NoParity,OneStopBit,WordLength8);
                      SioReset(Port,Baud9600);


              If you are using the version of  the  library  with  transmitter  interrupts
              enabled  (PCL4W2.LIB),  then  SioTxBuf()  must  be  called  to  set  up  the
              transmitter buffer. The transmit buffer must be distinct  from  the  receive
              buffer.


                   case WM_CREATE:
                      /* initialization */
                      SioRxBuf(Port,TxBuffer,Size1024);
                      SioTxBuf(Port,RxBuffer,Size1024);
                      SioParms(Port,NoParity,OneStopBit,WordLength8);
                      SioReset(Port,Baud9600);


              Characters can be  transmitted  and  received  once  the  required  port  is
              initialized.   Before leaving your application, SioDone is called to restore
              the prior state of the serial communications  system.   Forgetting  to  call
              SioDone  before  exiting your application will leave the interrupt system in
              an unusable state and the machine will have to be re-booted.


                   case WM_DESTROY:
                      /* termination */
                      SioDone(Port);