



      LWXM(tm) - LITECOMM (tm) WINDOWED XMODEM ENGINE
		 for Datalight and Turbo C


			  -CONTENTS-






INTRODUCING LWXM. . . . . . . . . . . . . . . . . . . . .  1

  DIFFERENCES BETWEEN XMODEM AND WXMODEM. . . . . . . . .  1

  PROTOCOL FUNDAMENTALS . . . . . . . . . . . . . . . . .  2
    THE TRANSMISSION BLOCK. . . . . . . . . . . . . . . .  2
    THE INTER-COMPUTER DIALOG . . . . . . . . . . . . . .  3

THE WLXM ENGINE . . . . . . . . . . . . . . . . . . . . .  3

  OVERVIEW. . . . . . . . . . . . . . . . . . . . . . . .  4

  MAJOR ENGINE COMPONENTS . . . . . . . . . . . . . . . .  5

  NOTES AND WARNINGS. . . . . . . . . . . . . . . . . . .  6
    MODIFICATIONS . . . . . . . . . . . . . . . . . . . .  6
    PARITY AND DATA BITS. . . . . . . . . . . . . . . . .  6
    INTERNAL TIMER FUNCTION . . . . . . . . . . . . . . .  6
    BUFFER SIZE RESTRICTION . . . . . . . . . . . . . . .  7
    XON-XOFF CONTROL. . . . . . . . . . . . . . . . . . .  7

  USER-ACCESSABLE DATA. . . . . . . . . . . . . . . . . .  8

PROGRAMMERS REFERENCE . . . . . . . . . . . . . . . . . .  8

  ENGINE-RELATED FUNCTIONS. . . . . . . . . . . . . . . .  9
    lwxrrec . . . . . . . . . . . . . . . . . . . . . . . 10
    lwxtrec . . . . . . . . . . . . . . . . . . . . . . . 12






















      LWXM(tm) - LITECOMM (tm) WINDOWED XMODEM ENGINE
		 for Datalight and Turbo C


	   DIFFERENCES BETWEEN XMODEM AND WXMODEM





This is  not  intended to  be  a strict  tutorial  on either
XMODEM or Windowed XMODEM (WXMODEM). We assume that you have
already read,  digested,  and understood  the documentataion
provided for the LXM (XMODEM)  engine.  If not, your reading
should begin there.

The  xmodem  protocol,  while  very  popular  and a  defacto
standard does have some built-in deficiencies.  At least one
of these has been addressed by a variant,  that of the block
checking  used  in  the original  protocol.  But some  other
deficiencies also exist.  Chief among these deficiencies are
the  amount   of   time  required   to  'turn   around'  the
transmission line  after  each block  is sent to  permit the
receiver  to  acknowledge successful  receipt of  the block.
This  turn-around   time  is   further  complicated  by  the
relatively short block length,  and as a result,  the number
of times this  turn-around occurs  while transferring a file
of any substantial size.

A second area of concern  for those who study communications
protocols is the  relative ease  with which xmodem can loose
synchronism between the sender and receiver,  permitting the
protocol  to   be  fooled.   Several  approaches  have  been
developed  within  the  xmodem  framework  to  address  this
problem,  but these must be viewed  as work-around's that do
not really correct the problem, but rather mask the symptoms
of the problem.

Finally,  xmodem   does  does	perform  well  over  certain
packet-based networks,  such as TELENET.  This is  largely a
result of the  the network's speed,  and the use of XON-XOFF
flow control. Most xmodem implimentations, ours included, to
not respond well to what the sender perceives to be spurious
characters on  the line,  the XON  and XOFF.  In some cases,
xmodem will not function at all. In others, there may be the
needless  retransmission  of  blocks because  of the  way in
which the XON and XOFF are handled.







      CopyRight (c) 1987, Information Technology, Ltd.
INTRODUCING LWXM					Page 1





      LWXM(tm) - LITECOMM (tm) WINDOWED XMODEM ENGINE
		 for Datalight and Turbo C


		   PROTOCOL FUNDAMENTALS








THE TRANSMISSION BLOCK


WXMODEM  transmission  blocks  closely   mirror  the  xmodem
standard with several important distinctions. To improve the
ability of WXMODEM  to handle false  blocks or false Ends of
Transmission (EOT),  an additional character  has been added
to the block,  SYN.  To successfully recognize the begiining
of a block,  the receiving program must successfully get one
or more SYN characters followed  by the traditional SOH used
by xmodem.

While the  addition of  a synchronizing character helps,  it
does  not  completely  eliminate   the  possibility  of  the
receiver  or  sender  being  fooled,  resulting  in  aborted
transmission or  premature End  of File conditions.  To help
correct these problems, WXMODEM requires that all characters
in a block that might  cause confusion be escaped.  That is,
WXMODEM  uses  a  technique  long  popular  in  the  area of
synchronous  communications  called transparency.  Using the
approach, certain data characters that might cause confusion
when they appear in  a data block  are altered and sent in a
special way that  can be  recognized easily by the receiver.
In WXMODEM these characters are SYN, XON, XOFF, and DLE.  To
send any of these characters as part of the data,  including
the block  check,  WXMODEM requires  that  the character  be
preceeded by a DLE,  and that a value of 64 (0x40)  be added
to  the  actual  character  by   the  sender.  The  receiver
recognizes the leading DLE, removes it from the data stream,
and subtracts 64 (0x40) from the character that follows. The
problem of EOT confusion is  addressed by a requirement that
two consectutive  EOT's  be received  to be recognized  as a
true End of File condition.

But perhaps the most unique design element in WXMODEM is the
way in which  it address the  line turn-around delay that we
discussed  earlier.   WXMODEM  does   not  require   that  a
transmitted block be acknowledged immediately.  Rather,  the
sender will continue  to transmit  data until upto  4 blocks


      CopyRight (c) 1987, Information Technology, Ltd.
INTRODUCING LWXM					Page 2





      LWXM(tm) - LITECOMM (tm) WINDOWED XMODEM ENGINE
		 for Datalight and Turbo C


have been sent before it (the sender)  will stop to wait for
an  acknowledgment.  And  the  receiver is  not required  to
acknowledge  each  block individually,  only the  last block
that  was   successfully  received,   although  the  WXMODEM
description in fact suggests that all blocks be acknowledged
explicitly.  The effect is that the sender can pause briefly
between blocks before starting  to send again.  The duration
of the pause should only be long enough to determine whether
there is any incoming acknowledgment to be handled. There is
no timeout interval as in  xmodem until the 'window closes',
i.e. the sender has sent 4 unacknowledged blocks.




THE INTER-COMPUTER DIALOG


Rather than re-invent the wheel,  we have included a copy of
the WXMODEM description, as developed by Peter Boswell. This
document  is  in  the file  WXMODEM.DOC for  those  who wish
further information on the subject.




























      CopyRight (c) 1987, Information Technology, Ltd.
THE WLXM ENGINE						Page 3





      LWXM(tm) - LITECOMM (tm) WINDOWED XMODEM ENGINE
		 for Datalight and Turbo C


			  OVERVIEW





The design of  the WLXM engine  closely mirrors that  of the
original LXM engine,  giving both capability and flexibility
in the  use  of communications protocols.  Indeed,  the WLXM
engine employs many of the same  kernel routines used by our
LXM engine.  As with LXM, virtually any application can have
access to this  xmodem enhancement,  without being religated
to simply transferring files.





































      CopyRight (c) 1987, Information Technology, Ltd.
THE WLXM ENGINE						Page 4





      LWXM(tm) - LITECOMM (tm) WINDOWED XMODEM ENGINE
		 for Datalight and Turbo C


		  MAJOR ENGINE COMPONENTS





The  WLXM  engine  consists,  primarily  of  two  functions,
lwxrrec and lwxtrec,  receive a record and transmit a record
respectively.  As with LXM, these two functions 'understand'
the wxmodem internally.  Due to the nature  of the protocol,
and unlike xmodem,  they share the responsibility for proper
operation with the  host program,  yet provide about  99 per
cent of the required housekeeping.

The lwxrrec  function  receives one  or more records  from a
companion system.  The host program merely handles,  in what
ever  way  appropriate,  blocks  of   data  that  have  been
received,  and can optionally monitor the  flow of data from
the companion system.  Lwxrrec assumes the responsibilty for
synchronizing with  the companion  system and  for correctly
maintaining the flow  of information,  including the correct
handing of the windowing of  information that is an integral
pat of the protocol.  Unlike its companion  function in LXM,
however,  there  is  little latitude  available to  the host
program in terms of selecting operating parameters, e.g. the
block  checking  method.  These   parameters  are  generally
defined by the protocol and cannot be alterred.

Lwxtrec performs  in  a like  fashion when the  host program
wants to send one or more records. The host program has only
to present the record to be transmited, and lwxtrec does the
rest.  The   lwxtrec  module   assumes  responsibility   for
establishing synchronization  with  the receiving  computer.
Due  to  the nature  of the  windowing protocol,  and unlike
xmodem, the host program must also respond to retransmission
requests by resetting  itself to resend  as many as four (4)
previously transmitted blocks.  A look at the sample program
will show one possible approach to meeting this requirement.
Lwxtrec also terminates  the transmisssion,  when told to do
so by the host program,  and permits the  host to optionally
monitor the data flow.









      CopyRight (c) 1987, Information Technology, Ltd.
THE WLXM ENGINE						Page 5





      LWXM(tm) - LITECOMM (tm) WINDOWED XMODEM ENGINE
		 for Datalight and Turbo C


		     NOTES AND WARNINGS








MODIFICATIONS


The  LWXM  engine  is closely  integrated with  the LiteComm
ToolBox. While there is every likelyhood that the engine can
be  modified  to  function   with  other  similar  packages,
Information  Technology,  Ltd.,  can only  support  the LWXM
engine when used with either the LiteComm ToolBox.




PARITY AND DATA BITS


The wxmodem protocol is an 8-bit protocol. That is to say it
neither recognizes  nor  tolerates parity checking,  i.e.  7
data bits  plus  a specified parity.  Since the  LWXM engine
cannot determine the current settings  for parity and number
of  data  bits,  the  responsibility  for  controlling these
settings rests with the host program. Before using either of
the key functions lwxrrec or lwxtrec,  the host program must
insure that the settings are no parity,  8 data bits,  using
the  comm_setup  function.  Upon  final  termination  of the
function,  the host program must reset these values to their
original settings, if necessary.




INTERNAL TIMER FUNCTION


Both  lwxrrec  and  lwxtrec  employ a  hardware-based timing
function  that  connects  directly  to the  normal real-time
clock vector 0x1C; The Turbo C version of this function also
establishes an special routine, using the atexit() function,
to insure that this vector  is re-established at is original
setting when program termination occurs. This is not true of


      CopyRight (c) 1987, Information Technology, Ltd.
THE WLXM ENGINE						Page 6





      LWXM(tm) - LITECOMM (tm) WINDOWED XMODEM ENGINE
		 for Datalight and Turbo C


the Datalight version however.

The Datalight  library  does not,  at present,  have an like
atexit().  While every effort  has been made,  for Datalight
users,  to insure  that the  vector is properly reset,  this
plan may  be  tharwted by  abornal termination  of  the host
program resulting in a  subsequent system crash.  The safest
method to  Datalight  user's to employ  would be to  use the
lc_clrclock()  function before host program termination.  As
an  alternate	approach,  Datalight   users  may   want  to
investigate  STEVE'S   LIBRARY  designed   for  Datalight  C
users's.  This  excellent  library does  have an  equivalent
function to TURBO's atexit().



BUFFER SIZE RESTRICTION


The LiteComm ToolBox permits you a  great deal of freedom in
tailoring the  communications handler  to meet your specific
requirements.  We must caution you,  however,  that when you
are using the LWXM engine, the minimum buffer sizes required
by the comm_opn  function are  not adequate to support LWXM,
particularly when  transmitting records  at either  low baud
rates,  or on the new generation of high-speed (above 6 MHz)
processors.

When you use  the LWXM engine,  the transmit buffer  must be
set at a minimum 528 bytes to avoid buffer overflow. This is
the  theoretical  minimum  size   that  is  supportable.  In
practice,  we urge you  to set  the transmit buffer  size to
1024 bytes to avoid any possibility of overflow.




XON-XOFF CONTROL


If  your  host  program  employs  the XON-XOFF  functions in
LiteComm,  no special actions is  required to use LWXM.  The
windowed xmodem protocol, and LWXM, are tolerant of XON-XOFF
usage.






      CopyRight (c) 1987, Information Technology, Ltd.
THE WLXM ENGINE						Page 7





      LWXM(tm) - LITECOMM (tm) WINDOWED XMODEM ENGINE
		 for Datalight and Turbo C


		    USER-ACCESSABLE DATA





Within LWXM,  certain variables  have been  defined as being
globally  available.  The  host   program  may  examine  the
contents of  these  variables at  any time to  determine the
current state of the LWXM engine. The correct definitions of
these variable  is  contained in  litexm.h.  Except as noted
below, the host program must NOT alter the contents of these
variables.

_abort_flag - This  is the  only variable of  the group
   that may be altered by the host program. The flag is
   checked periodically  by  the engine  functions.  If
   _abort_flag  has  a  value  of  1,  the function  in
   progress will be cancelled  automatically by sending
   a CAN instruction to  the companion system.  See the
   WSCE.C sample  program  for an  example of  how this
   flag may be set.

rec - This variable contains the current record (block)
   number  being   processed.  In   the  event   of  an
   uncorrectable error, rec would contain the number of
   the expected  block.  In the  case  of a  successful
   transmission or reception,  rec is the number of the
   block sent or received.  The value contained in this
   variable,  reduced modulo  256,  provides the  block
   number  required  by the  wxmodem protocol  and must
   NEVER be disturbed.


















      CopyRight (c) 1987, Information Technology, Ltd.
PROGRAMMERS REFERENCE					Page 8





      LWXM(tm) - LITECOMM (tm) WINDOWED XMODEM ENGINE
		 for Datalight and Turbo C


		  ENGINE-RELATED FUNCTIONS





The following pages  document the  LWXM engine  functions as
currently implimented.  They follow,  in style  and content,
the documentation for the LiteComm ToolBox itself.

Use the  following  pages as  an addendum  to  your LiteComm
documentation.






































      CopyRight (c) 1987, Information Technology, Ltd.
PROGRAMMERS REFERENCE					Page 9





      LWXM(tm) - LITECOMM (tm) WINDOWED XMODEM ENGINE
		 for Datalight and Turbo C


	+---------------------------------------+
	|					|
	|	     FUNCTION lwxrrec		|
	|					|
	+---------------------------------------+



SUMMARY

#include <litexm.h>
#include <litecomm.h>

int lwxrrec(port, buff)

     unsigned port;
     unsigned char *buff;

DESCRIPTION

     Receive a 128 byte record from the companion system. If
     necessary, establish synchroniztion with the companion
     system.

     The port parameter is the same as used throughout the
     LiteComm ToolBox.

     Buff should be a pointer to a 128 byte record. All record
     characters are received into this area, and, if the area is
     too small, LWXM will overwrite adjacent data without warning.


EXAMPLE

     See the accompanying program WSCE for an example of lwxrrec
     usage.

RETURN VALUES

     Lwxrrec may return several values, as defined in the
     litexm.h file. Each return value should cause the host
     program to respond in specific ways.

	  SUCCESS - A record has been successfully received into
		the buff area. Host program process the record
		and calls lwxrrec again.

	  RETRIES - The maximum number of attempts to receive a


      CopyRight (c) 1987, Information Technology, Ltd.
PROGRAMMERS REFERENCE					Page 10





      LWXM(tm) - LITECOMM (tm) WINDOWED XMODEM ENGINE
		 for Datalight and Turbo C


		single record has been exceeded. Lwxrrec
		automatically cancels the session. Host program
		should handle in an appropriate manner, e.g. issue
		an error message.

	  ERR (-1) - Lwxrrec has detected that the host program
		has requested cancellation of transmissions
		through the _abort_flag setting (see below) or a
		fatal record sequence has occurred, e.g. a block
		number has been skipped. Lwxrrec automatically
		cancels the session.

	  CAN - The sending program has requested cancellation.
		Host program should handle in a fashion similar to
		RETRIES.

	  EOT - The sending program has no more data to transmit.
		Lwxrrec acknowledges the EOT message
		automatically. Host program handles like an end-
		of-file condition.

	  TOUT - Lwxrrec failed to establish synchronization with
		the sending program while waiting to receive the
		SYN SOH character combination at the start of the
		block. The session is automatically cancelled.

	  DUPSEQ - The block just received is a duplicate of the
		preceeding block. The host program should ignore
		the data contained within the block, then call
		lwxrrec to proceed with data transfer.




















      CopyRight (c) 1987, Information Technology, Ltd.
PROGRAMMERS REFERENCE					Page 11





      LWXM(tm) - LITECOMM (tm) WINDOWED XMODEM ENGINE
		 for Datalight and Turbo C


	+---------------------------------------+
	|					|
	|	      FUNCTION lwxtrec		|
	|					|
	+---------------------------------------+



SUMMARY

#include <litexm.h>
#include <litecomm.h>

int lwxtrec(port, buff, nrec)

     unsigned port;
     unsigned char *buff;
     int	   *nrec;

DESCRIPTION

     Transmit a 128 byte record to the companion system. If
     necessary, establish synchroniztion with the companion
     system before transmitting.

     The port parameter is the same as used throughout the
     LiteComm ToolBox.

     Buff should be a pointer to a 128 byte record to be sent to
     the companion system. This is not a typical, null-terminated
     string as usually found in C. All 128 bytes, starting at
     the pointer will be transmitted. It is the responsibility
     of the host program to provide any padding that might be
     required to satisfy the 128 byte requirement.

     Nrec is a POINTER to an integer, and is used by lwxtrec to
     communicate special requirements to the host program. If
     lwxtrec returns a value of SUCCESS, then nrec will be
     significant if the host program has indicated end of file by
     calling lwxtrec with nrec set to a value of -1.  In this case,
     a returned value of -1 indicates that end-of-file has been
     acknowledged by the companion system.

     If lwxtrec returns a value of RESEND, then nrec will
     contain the block number of the 128 byte block where
     retransmission is to be started.  It is the responsibility
     of the host program to reposition itself by whatever
     means is appropriate to permit retransmission to occur as


      CopyRight (c) 1987, Information Technology, Ltd.
PROGRAMMERS REFERENCE					Page 12





      LWXM(tm) - LITECOMM (tm) WINDOWED XMODEM ENGINE
		 for Datalight and Turbo C


     indicated.  See WSCE for one possible approach.

     Due to its special nature, nrec should be initialized to a
     value of zero before the first call to lwxtrec.  The host
     program may examine, but must never modify, the contents
     of nrec.

EXAMPLE

     See the accompanying program WSCE for an example of lwxtrec
     usage.

RETURN VALUES

     Lwxtrec may return several values, as defined in the
     litexm.h file. Each return value should cause the host
     program to respond in specific ways.

	  SUCCESS - The record has been successfully sent from
		the buff area. Host program either calls lwxtrec
		with the next record to transmit, or with nrec set
		to a value of -1 to indicate End of Transmisson
		to the companion system.

	  RETRIES - The maximum number of attempts to send a
		single record has been exceeded. Lwxtrec
		automatically cancels the session. Host program
		should handle in an appropriate manner, e.g. issue
		an error message.

	  RESEND - The companion system has requested that all
		or a portion of a window be re-sent.  The nrec
		variable contains the block number at which re-
		transmission is to commence.

	  ERR (-1) - Lwxtrec has detected that the host program
		has requested cancellation of transmissions
		through the _abort_flag setting (see below).

	  CAN - The receiving program has requested cancellation.
		Host program should handle in a fashion similar to
		RETRIES.








      CopyRight (c) 1987, Information Technology, Ltd.
PROGRAMMERS REFERENCE					Page 13

