The Microcom MNP Library
                          (Microsoft C Version)
     
     
     
                           PROGRAMMER'S MANUAL
     
     
     
     
     
     
     
     
     
     
     
     
     
     
                                Version 1.0
     
                             December 15, 1987
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
                              Microcom, Inc.
                          1400 Providence Highway
                            Norwood, MA 02062





     
     
     The Microcom MNP Library and MNP are trademarks of Microcom, Inc.
     Microsoft and MS-DOS are trademarks of Microsoft Corporation.  
     IBM is a registered trademark of International Business Machines.
     
     
     This manual is not subject to copyright and may be freely copied.
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     Questions relating to the Microcom MNP Library should be directed to
     Microcom at:
     
                              Microcom, Inc.
                       15303 Ventura Blvd., Suite 900
                          Sherman Oaks, CA 91403
                  Voice: (818)986-4212  Fax: (818)986-4214






     
     1. INTRODUCTION
     
          The Microcom MNP Library is a set of subroutines which implement the
     stream mode of the link protocol in Microcom Networking Protocol (MNP).
     This mode of the MNP link protocol is appropriate for interworking with MNP
     error-correcting modems or with other software implementations which use
     the Microcom MNP Library or other compatible software.
     
          This version of the library provides a set of C and assembly
     language routines which are designed to be easily integrated into an
     application program written in C and compiled using the Microsoft C
     compiler (version 4.0).  Through the use of these routines, an
     application is able to perform error-free data communications over a
     physical-connection, such as one established on the public switched
     telephone network.
     
          These MNP Library subroutines are especially for the IBM Personal
     Computer family (and compatibles) under PCDOS (MS-DOS).  Hardware
     facilities for asynchronous communications are required.





     2. LIBRARY MODULES
     
          The Microcom MNP LIbrary is supplied in one of two forms, object
     library only and object library with source.  The source version is de-
     scribed in more detail in a file ('readme.doc') supplied as part of the
     source version distribution.
     
          In the case of the object library only form, the distribution diskette
     contains one file, mnp.lib, which includes the various object modules
     which make up the MNP Library.
     
          When building the executable form of a particular application, the
     mnp.lib file should be specified if the application calls any MNP sub-
     routine described in this document.  The manner in which library modules
     are specified for inclusion varies according to the linkage editor
     employed in building the application program run module.





     3. LINK MANAGEMENT
     
          In general, the MNP link follows the life of the normal physical-
     connection.  Immediately after the physical-connection is made (e.g. after
     a modem first reports carrier detected), the application must attempt the
     establishment of the Link via the MNPCONNECT subroutine.  MNP-capable
     modems which answer the incoming telephone call, for example, must receive
     the Link establishment sequence within 4 seconds of physical-connection
     establishment.  If a link is not attempted within this period, such modems
     may fall back to a normal connection and it will not be possible to provide
     a reliable connection on that particular call.
     
          Link termination, performed via the MNPDISCONNECT call, should
     immediately precede termination of the physical-connection, i.e. right
     before hanging up the telephone.  Note that the Link is active for the
     entire duration of the physical-connection.
     
          During the data phase of the Link (i.e. after establishment but before
     termination), the Link must be kept running by allowing the Link code to
     execute periodically.  Any of the data phase calls, namely MNPSEND,
     MNPRECEIVE, MNPSTATUS, and MNPBREAK, will accomplish this.  One of these
     routines must be called every 250ms or so which means that the Link code
     gets a chance to run about 4 times per second.  The absolute interval is
     not critical and it may be possible to reduce the frequency as well and
     still get reasonable performance.  Polling the Link code, however, must
     occur with a predictable frequency otherwise the Link may be lost.  When
     the Link is lost, an MNP error-correcting modem may clear the call.
     
          When a Link is in progress, all line I/O is performed via the
     appropriate MNP call rather than by using other C mechanisms.  It 
     may be the case, however, that the com port opened elsewhere in the
     application, must remain open.
     
          Data sent and received on the Link will be "chunked" depending on the
     number of bytes which happen to be sent in a single data message.  The
     maximum amount in a single message is 64 bytes.  This "chunking" is not
     noticeable to the sender but can be perceived by the data receiver.
     Strings of data may be split over more than one data message and some
     messages may have to be sent more than once when there is noise on the
     connection.  Retransmission can be seen by the application as an
     interruption, possibly in the middle of some data string.  The application
     should be examined to see if there are any cases involving timing
     dependencies which could be adversely effected by this kind of 
     irregularity in the data flow.





     4. LINK INTERFACE SUBROUTINES
     
     4.1  Link Establishment - MNPCONNECT
     
          MNPCONNECT is used to establish a Link.  It is called after the
     physical-connection has been established.  It can take up to 5 seconds
     for an MNPCONNECT call to complete.
     
          MNPCONNECT has the following parameters:
     
               RATE - an integer which indicates the speed of the
                      physical-connection, as follows:
     
                          1 = 110 bps
                          2 = 300 bps
                          4 = 1200 bps
                          5 = 2400 bps
     
                      [Note: Other speeds are not supported in this
                       version of the Microcom MNP Library.]
     
               FORMAT - an integer which indicates the data format,
                        as follows:
     
                         0 = 8 data bits, no parity