💾 Archived View for gemini.spam.works › mirrors › textfiles › computers › DOCUMENTATION › lwxm.txt captured on 2022-06-12 at 06:35:00.
-=-=-=-=-=-=-
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