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 #include 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 #include 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