+-------------------------------------------------------------------------+
!                                                                         !
!                 Lightning House Software Co. presents:                  !
!                         *** XModem protocol ***                         !
!                                                                         !
+-------------------------------------------------------------------------+

The XModem protocol in general:
-------------------------------
The XModem protocol is generally a simple way to transfer data files with
minimum errors which may occur due to line static charges etc. The XModem
protocol takes a file and cuts it into blocks. Each block is 128 bytes, and
every block has some data added to it like block number and checksum bytes.

A look at XModem's blocks:
--------------------------
Well, there arrises the question: what if the receiving computer gets
garbage before beginning transmission or block? Well, XModem defines one
character, SOH (01h), as the beginning-of-block sign. This char will be
referred to as SOH (Start Of Header). Any information sent before
the SOH is ignored. After this byte, (the SOH), the sender sends the block
number, beginning with one, as one byte, and after it, a complemenr byte.
(255-Block #). If the block number is greater than 255 it wraps around back
to zero.
 After the SOH, Block # and 255-Block #, 128 bytes of data are sent which
preceed the checksum (CKSM) byte.

A block should look like this:

-------------------------------------------------
!     !      !          !                !      !
! SOH ! Bl # ! 255-Bl # ! 128 data bytes ! CKSM !
!1    !1     !1         !128             !1     !
-------------------------------------------------
(The numbers on the bottom represent the number of bytes.)

The CheckSum byte:
------------------
The CKSM byte comes to find if an error has occured. The CKSM is calculated
by adding together all the 128 bytes of data, and taking the low byte.
(like doing: cksm = sum AND 255. Thus taking the lowest 8 bits.) If the
CKSM calculated by the receiver is compared to the one sent, and found
wrong a NAK is sent by the receiver to Negatively AcKnowledge the block,
and to ask for retransmission of the block.

Other Errors:
-------------
If the block count on the receiving side does not match the one on the
sending side, a retransmission is requested by sending NAK. If again the
count does not match, but the block # of the previous block is identical to
the one on the retransmitted block, then the transmission is aborted by the
CANcel byte being sent to the sender after the CKSM byte is received. The
CAN char is equivalent to CTRL-X.
 If the block number received, and the inverted block number (255-b#), do
not match, a retransmission is requested by the NAK character.
 If the receiver gets a CAN while waiting for NAK on the beginning of a
block, transmission is aborted.

EOT - End Of Transmission:
--------------------------
When the sender gets to the end of his file, he sends nulls, Hex 00, to
fill the 128 byte block, and calculates the CKSM with the nulls. After this
block the sender sends an EOT char CTRL-D and ends the transmission.

ACKnowledge char:
-----------------
The ACK char Hex 06 is sent when a block sent matches the block count,
CKSM bytes match, inverted and uninverted block # bytes match and receiver
can do his I/O correctly. This means that if everything is OK, the receiver
sends ACK to ACKnowledge the block or EOT or CAN.
If the receiver cannot continue receiving, for any reason what so ever, he
sends the CAN char and CANcels the transmission.

So what does the receiver do?
-----------------------------
The receiver receives the block, checks for the above errors, and
ACKnowledges or Negatively AcKnowledges the transmission. Also the
receiving program should take notice that the sender does not CANcel the
transmission or that his side is OK. If his side is not able of receiving
the information, he must CANcel the transmissio.

XModem CRC:
-----------
The CRC XModem protocol is almost identical. It has only two changes:
1) The ability to send long blocks of 1024 bytes, by using the STX char as
   beginning-of-block sign. [STX = CHR$(2)].
2) The CKSM is not a single byte but two bytes, calculated by a polynomial
   function.
The CRC XModem is recognized by the receiver's sending "C" [CHR$(67)]
instead of NAK as sign of "ready-to-receive".

A diagram of an XModem checksum protocol session (including an error):
----------------------------------------------------------------------

 SENDER                                      RECEIVER
--------                                    ----------
                                               NAK - to signal ready.
SOH 01 FE Data[128] CKSM
                                               ACK - to ACKnowledge.
SOH 02 FD Data[128] CKSM
                                               NAK - block wrong.
SOH 02 FD Data[128] CKSM
                                               ACK
SOH 03 FC Data[128] CKSM
                                               ACK
SOH 04 FB Data[100]+[28 nulls] CKSM
                                               ACK
EOT
                                               ACK
--------------------------------------------------------------------------
CANcel char on the sender's side can come instead of the SOH and be ACK'd.
On the receiver's side, it can come instead of the ACK and be ACK'd by the
sender.

/************************************************************************\
*                                                                        *
*   This has been another presentation of Lightning House Software Co.   *
*                                                                        *
\************************************************************************/
