File Archive

 
Output of file : MNPB.DOC contained in archive : MNP-QB.ZIP

@x1CB










The Microcom MNP Library
(Microsoft QuickBASIC 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
(818)986-4212






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 assembly language
routines which are designed to be easily integrated into an application
program written in BASIC and compiled using the Microsoft QuickBASIC
compiler (version 1.02 or 2.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 manual addendum supplied as part of the source
version distribution.

In the case of the object library only form, the distribution diskette
contains one file, mnpb.lib, which includes the various object modules
which make up the MNP Library.

When building the executable form of a particular application, the
mnpb.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 the BASIC COM file mechanism.
The BASIC COM file, however, 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
3 = 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
1 = 7 data bits, even parity
2 = 7 data bits, odd parity
3 = 7 data bits, mark parity
4 = 7 data bits, space parity

[Note: In this Library version, once the Link
is established, it is not possible to change
format.]

PORT - an integer which indicates the communications
port, as follows:

1 = COM1
2 = COM2

[Note: This Library version does not support
other comm ports. Also, COM2 cannot be speci-
fied if no COM1 is present in the system.]

MODE - an integer which indicates the role in link
establishment, as follows:

0 = link initiator (caller)
1 = link accepter (answerer)






RETCODE - an integer returned to the caller which
indicates the result of the link
establishment attempt, as follows:

0 = success (link established)

-64 - failure, no additional info
-65 - failure, timeout (no remote response)
-66 - failure, physical-connection lost
(carrier lost)
-70 - failure, incompatible MNP
-72 - failure, remote protocol error

[Note: -70 and -72 should never occur.]


MNPCONNECT is called as follows:

CALL MNPCONNECT(RATE,FORMAT,PORT,MODE,RETCODE)





4.2 Link Termination - MNPDISCONNECT

MNPDISCONNECT has two functions, to send the appropriate protocol
message to the other side to indicate Link termination and to reset the PC
interrupt environment. MNPDISCONNECT must always be called if MNPCONNECT
had been called previously. This is so even for establishment failure or
for loss of the physical-connection (i.e. carrier lost).

MNPDISCONNECT has no parameters. It is called as follows:

CALL MNPDISCONNECT





4.3 Send Data - MNPSEND

MNPSEND is called to copy data to be sent on the Link from the
application into the MNP transmit buffer.

MNPSEND has parameters as follows:

SNDBUF$ - the BASIC string from which transmit data
is to be copied.

BUFLEN - an integer which indicates the maximum
number of data bytes which can be copied
from SNDBUF$.

RETCODE - an integer returned to the caller which
indicates the number of bytes copied from
SNDBUF$ or a Link error condition, as follows:

positive int = number of bytes copied from
SNDBUF$. 0=no bytes copied

-64 = link terminated, retransmission limit
exceeded
-65 = link terminated, unable to send
-66 = link terminated, carrier lost
-67 = link terminated, remote disconnected

MNPSEND is called as follows:

CALL MNPSEND(SNDBUF$,BUFLEN,RETCODE)





4.4 Receive Data - MNPRECEIVE

MNPRECEIVE is called to copy data received on the Link into the
application. MNPRECEIVE transfers all available data up to the size of the
application buffer. MNPRECEIVE returns immediately if no data is
available.

MNPRECEIVE has the following parameters:

RCVBUF$ - the BASIC string into which received
data is to be copied. This string must
be created by the application to be as
long as the value of BUFLEN.

BUFLEN - an integer which indicates the maximum
number of data bytes which can be copied
into RCVBUF$

RETCODE - an integer returned to the caller which
indicates the number of bytes copied into
RCVBUF$ or a Link error condition, as follows:

positive int = number of bytes copied into
RCVBUF. 0=no bytes available.

-64 = link terminated. retransmission limit
exceeded
-65 = link terminated, unable to send
-66 = link terminated, carrier lost
-67 = link terminated, remote disconnected

MNPRECEIVE is called as follows:

CALL MNPRECEIVE(RCVBUF$,BUFLEN,RETCODE)





4.5 Link Status - MNPSTATUS

MNPSTATUS is called to return to the application the status of the
Link and to read parameters which indicate the availability of received
data or the ability to enqueue data for transmission.

MNPSTATUS has parameters as follows:

PSTATUS - an integer which indicates the condition of
the physical-connection, as follows:

0 = not connected (carrier not present)
1 = connected (carrier present)

LSTATUS - an integer which indicates the condition of
Link, as follows:

0 = link not established (i.e. link
terminated)
1 = link established

SCOUNT - an integer which indicates the number of
bytes free in the Link send buffer. This is
the number of bytes which can be completely
copied to the Link transmit code via an
MNPSEND call.

RCOUNT - an integer which indicates the number of
received data bytes which are available to
be copied into the application via MNPRECEIVE

ALLSENT - an integer which indicates whether or not
all data passed to the Link code has been
successfully sent and acknowledged, as
follows:

0 = all data not sent
1 = all data sent


MNPSTATUS is called as follows:

CALL MNPSTATUS(PSTATUS,LSTATUS,SCOUNT,RCOUNT,ALLSENT)





4.6 Send Signal - MNPBREAK

MNPBREAK is called to send a signal to the remote DTE. When the
remote side is an MNP error-correcting modem, an MNPBREAK call causes the
remote modem to send a break signal (continuous spacing) to its attached
DTE.

MNPBREAK employs the MNP Link Protocol's reliable attention
mechanism in 'destructive mode'. That is, when MNPBREAK is called, the
Link is reset and any data pending transmission on the link is discarded as
is any received data which has not been read via the MNPRECEIVE subroutine.
Data may also be discarded at the remote side of the Link.

MNPBREAK has one parameter as follows:


RETCODE - an integer returned to the caller which
indicates the result of the MNPBREAK call
or a Link error condition, as follows:

0 = break initiated

-64 = link terminated, retransmission limit
exceeded
-65 = link terminated, unable to send
-66 = link terminated, carrier lost
-67 = link terminated, remote disconnected
-75 = break not supported (remote did not
negotiate attention support for this
Link)
-76 = previous break still in progress


MNPBREAK is called as follows:

CALL MNPBREAK(RETCODE)



[Note that the MNP Library does not support receipt of the MNP
attention message and hence it is assumed that MNPBREAK will only be
employed when the remote side of the connection is an MNP error-correcting
modem.]





5. SAMPLE PROGRAM

A demonstration program is provided on the distribution diskette in
the file testb.exe. A listing of this program follows in the next pages.

'==========================================================================
'
' MNP INTERFACE TEST PROGRAM
'
' This test program is a simple terminal emulator which
' exercises the assembly language routines which interface
' QuickBASIC to the MNP library.
'
' - G. Pearson, September 1986
'
'==========================================================================

'----- Data declarations
defint a-z

'----- Initialize
rbuflen=80 ' make receive buffer be a
rcvbuf$=string$(rbuflen,32) ' a blank string of right
' length

'----- Display herald screen
cls ' clear screen
print "-------------------------------------------------------------------"
print
print " MNP Link Demonstration Program"
print
print " This simple terminal emulation program demonstrates the use"
print " of the Microcom MNP Library to provide error-free data"
print " com munications."
print
print
print " Hit any key to begin..."
print
print "-------------------------------------------------------------------"

startloop:
if inkey$="" then goto startloop
print

'----- Get user parameter selections
' Comm port number...
parms:
input "Enter comm port number (1/2)";port$
if (port$="1" or port$="2") then goto parms1 _
else goto parms






' Port speed...
parms1:
input "Enter port speed (300/1200/2400)";spd$
if (spd$="300" or spd$="1200" or spd$="2400") then goto parms2 _
else goto parms1

' Telephone number...
parms2:
input "Enter telephone number of MNP remote";number$
if number$="" then goto parms2

'----- Open comm file
opncom:
open "com"+port$+":"+spd$+",n,8,1,cs,ds,cd" as #1

'----- Initialize modem (Hayes 2400-compatible assumed)
a$=""
print #1,"ATE0Q0V0" ' no cmd echo,result codes,
' numeric codes
for i=1 to 1000:next i ' let cmds get out...
close #1 ' trash modem response
open "com"+port$+":"+spd$+",n,8,1,cs,ds,cd" as #1 ' re-open modem

'----- Dial MNP-capable remote and wait for connect
print ' inform user
print "dialing "+number$+"..."
print #1,"ATDT"+number$ ' send dial string to modem
print "-- waiting for physical-connection establishment..."
connwait: ' wait for modem or user abort
if (inkey$<>"") then goto xitpgm ' any user input will abort...
if loc(1)=0 then goto connwait
a$=input$(1,#1) ' get modem response code
if (a$<>"1") then goto connwait ' wait till connect or user abort
print "physical-connection established."

'----- Initiate Link
startlink:
for i=1 to 10000:next i ' let line settle...
print "-- starting link..." ' pass line speed
rate=5 ' assume 2400 bps
if (spd$="1200") then rate=4 ' adjust for other speeds...
if (spd$="300") then rate=2
format=1 ' assume 7 bits, even parity
if (port$="1") then port=1 else port=2 ' pass comm port number
mode=0 ' caller is link initiator
call mnpconnect(rate,format,port,mode,retcode) ' try for link
if retcode<>0 then goto xitpgm ' just quit if failure

'----- Link established. Notify user and wait to continue.
print
print "***** Link established. Hit any key to continue... *****"





'----- Now wait for user input before starting terminal emulation.
' Note that the application must poll the link code while waiting
' in order to keep the link alive.
startwait:
call mnpstatus(pstatus,lstatus,scount,rcount,allsent)
if pstatus=0 then print "carrier lost":goto xitpgm
if lstatus=0 then print "link lost":goto xitpgm
if inkey$="" then goto startwait

'----- Start terminal emulation with a clear screen and tell the
' user how to terminate the program.
cls
print "Begin terminal emulation. A slash (/) will exit program."

'----- Data phase of Link
mainloop:
retcode=0
call mnpstatus(pstatus,lstatus,scount,rcount,allsent)
if (pstatus=0) then print "carrier lost":goto xitpgm
b$=inkey$
if (b$="") then goto getcomm
if (b$="/") then goto xitpgm

sndagain:
call mnpsend(b$,len(b$),retcode)
if (retcode<0) then _
print "link failed on send": _
goto xitpgm
if (retcode<>len(b$)) then goto sndagain
retcode=0

getcomm:
if (rcount>0) then call mnpreceive(rcvbuf$,rbuflen,retcode)
if (retcode<0) then _
print "link failed on receive": _
goto xitpgm
if (retcode>0) then print using "&";left$(rcvbuf$,retcode);
goto mainloop

'----- Exit
xitpgm:
print
print "-- disconnecting link..."
call mnpdisconnect
print
print "end of test program"
close
system