


                                      - 1 -



                         XMODEM/YMODEM PROTOCOL REFERENCE
                     A compendium of documents describing the

                                XMODEM and YMODEM

                             File Transfer Protocols




                      This document was formatted 10-14-88.







                             Edited by Chuck Forsberg









                This file may be redistributed without restriction
                        provided the text is not altered.

                     Please distribute as widely as possible.

                           Questions to Chuck Forsberg





                               Omen Technology Inc
                          The High Reliability Software
                            17505-V Sauvie Island Road
                              Portland Oregon 97231
                            VOICE: 503-621-3406 :VOICE
      TeleGodzilla BBS: 503-621-3746 Speed 19200(Telebit PEP),2400,1200,300
                              CompuServe: 70007,2304
                                    GEnie: CAF
                        UUCP: ...!tektronix!reed!omen!caf














                                      - 2 -



    1.  TOWER OF BABEL

    A "YMODEM Tower of Babel" has descended on the microcomputing community
    bringing with it confusion, frustration, bloated phone bills, and wasted
    man hours.  Sadly, I (Chuck Forsberg) am partly to blame for this mess.

    As author of the early 1980s batch and 1k XMODEM extensions, I assumed
    readers of earlier versions of this document would implement as much of
    the YMODEM protocol as their programming skills and computing environments
    would permit.  This proved a rather naive assumption as programmers
    motivated by competitive pressure implemented as little of YMODEM as
    possible.  Some have taken whatever parts of YMODEM that appealed to them,
    applied them to MODEM7 Batch, Telink, XMODEM or whatever, and called the
    result YMODEM.

    Jeff Garbers (Crosstalk package development director) said it all: "With
    protocols in the public domain, anyone who wants to dink around with them
    can go ahead." [1]

    Documents containing altered examples derived from YMODEM.DOC have added
    to the confusion.  In one instance, some self styled rewriter of history
    altered the heading in YMODEM.DOC's Figure 1 from "1024 byte Packets" to
    "YMODEM/CRC File Transfer Protocol".  None of the XMODEM and YMODEM
    examples shown in that document were correct.

    To put an end to this confusion, we must make "perfectly clear" what
    YMODEM stands for, as Ward Christensen defined it in his 1985 coining of
    the term.

    To the majority of you who read, understood, and respected Ward's
    definition of YMODEM, I apologize for the inconvenience.

    1.1  Definitions

    ARC     ARC is a program that compresses one or more files into an archive
            and extracts files from such archives.

    XMODEM  refers to the file transfer etiquette introduced by Ward
            Christensen's 1977 MODEM.ASM program.  The name XMODEM comes from
            Keith Petersen's XMODEM.ASM program, an adaptation of MODEM.ASM
            for Remote CP/M (RCPM) systems.  It's also called the MODEM or
            MODEM2 protocol.  Some who are unaware of MODEM7's unusual batch
            file mode call it MODEM7.  Other aliases include "CP/M Users'
            Group" and "TERM II FTP 3".  The name XMODEM caught on partly
            because it is distinctive and partly because of media interest in


    __________

     1. Page C/12, PC-WEEK July 12, 1987




    Chapter 1







    X/YMODEM Protocol Reference    June 18 1988                              3



            bulletin board and RCPM systems where it was accessed with an
            "XMODEM" command.  This protocol is supported by every serious
            communications program because of its universality, simplicity,
            and reasonable performance.

    XMODEM/CRC replaces XMODEM's 1 byte checksum with a two byte Cyclical
            Redundancy Check (CRC-16), giving modern error detection
            protection.

    XMODEM-1k Refers to the XMODEM/CRC protocol with 1024 byte data blocks.

    YMODEM  Refers to the XMODEM/CRC (optional 1k blocks) protocol with batch
            transmission as described below.  In a nutshell, YMODEM means
            BATCH.

    YMODEM-g Refers to the streaming YMODEM variation described below.

    True YMODEM(TM) In an attempt to sort out the YMODEM Tower of Babel, Omen
            Technology has trademarked the term True YMODEM(TM) to represent
            the complete YMODEM protocol described in this document, including
            pathname, length, and modification date transmitted in block 0.
            Please contact Omen Technology about certifying programs for True
            YMODEM(TM) compliance.

    ZMODEM  uses familiar XMODEM/CRC and YMODEM technology in a new protocol
            that provides reliability, throughput, file management, and user
            amenities appropriate to contemporary data communications.

    ZOO     Like ARC, ZOO is a program that compresses one or more files into
            a "zoo archive".  ZOO supports many different operating systems
            including Unix and VMS.























    Chapter 1







    X/YMODEM Protocol Reference    June 18 1988                              4



    2.  YMODEM MINIMUM REQUIREMENTS

    All programs claiming to support YMODEM must meet the following minimum
    requirements:

       + The sending program shall send the pathname (file name) in block 0.

       + The pathname shall be a null terminated ASCII string as described
         below.

         For those who are too lazy to read the entire document:

            + Unless specifically requested, only the file name portion is
              sent.

            + No drive letter is sent.

            + Systems that do not distinguish between upper and lower case
              letters in filenames shall send the pathname in lower case only.


       + The receiving program shall use this pathname for the received file
         name, unless explicitly overridden.

       + When the receiving program receives this block and successfully
         opened the output file, it shall acknowledge this block with an ACK
         character and then proceed with a normal XMODEM file transfer
         beginning with a "C" or NAK tranmsitted by the receiver.

       + The sending program shall use CRC-16 in response to a "C" pathname
         nak, otherwise use 8 bit checksum.

       + The receiving program must accept any mixture of 128 and 1024 byte
         blocks within each file it receives.  Sending programs may
         arbitrarily switch between 1024 and 128 byte blocks.

       + The sending program must not change the length of an unacknowledged
         block.

       + At the end of each file, the sending program shall send EOT up to ten
         times until it receives an ACK character.  (This is part of the
         XMODEM spec.)

       + The end of a transfer session shall be signified by a null (empty)
         pathname, this pathname block shall be acknowledged the same as other
         pathname blocks.

    Programs not meeting all of these requirements are not YMODEM compatible,
    and shall not be described as supporting YMODEM.

    Meeting these MINIMUM requirements does not guarantee reliable file



    Chapter 2







    X/YMODEM Protocol Reference    June 18 1988                              5



    transfers under stress.  Particular attention is called to XMODEM's single
    character supervisory messages that are easily corrupted by transmission
    errors.



















































    Chapter 2







    X/YMODEM Protocol Reference    June 18 1988                              6



    3.  WHY YMODEM?

    Since its development half a decade ago, the Ward Christensen modem
    protocol has enabled a wide variety of computer systems to interchange
    data.  There is hardly a communications program that doesn't at least
    claim to support this protocol.

    Advances in computing, modems and networking have revealed a number of
    weaknesses in the original protocol:

       + The short block length caused throughput to suffer when used with
         timesharing systems, packet switched networks, satellite circuits,
         and buffered (error correcting) modems.

       + The 8 bit arithmetic checksum and other aspects allowed line
         impairments to interfere with dependable, accurate transfers.

       + Only one file could be sent per command.  The file name had to be
         given twice, first to the sending program and then again to the
         receiving program.

       + The transmitted file could accumulate as many as 127 extraneous
         bytes.

       + The modification date of the file was lost.

    A number of other protocols have been developed over the years, but none
    have displaced XMODEM to date:

       + Lack of public domain documentation and example programs have kept
         proprietary protocols such as Blast, Relay, and others tightly bound
         to the fortunes of their suppliers.

       + Complexity discourages the widespread application of BISYNC, SDLC,
         HDLC, X.25, and X.PC protocols.

       + Performance compromises and complexity have limited the popularity of
         the Kermit protocol, which was developed to allow file transfers in
         environments hostile to XMODEM.

    The XMODEM protocol extensions and YMODEM Batch address some of these
    weaknesses while maintaining most of XMODEM's simplicity.

    YMODEM is supported by the public domain programs YAM (CP/M),
    YAM(CP/M-86), YAM(CCPM-86), IMP (CP/M), KMD (CP/M), rz/sz (Unix, Xenix,
    VMS, Berkeley Unix, Venix, Xenix, Coherent, IDRIS, Regulus).  Commercial
    implementations include MIRROR, and Professional-YAM.[1] Communications







    Chapter 3







    X/YMODEM Protocol Reference    June 18 1988                              7



    programs supporting these extensions have been in use since 1981.

    The 1k block length (XMODEM-1k) described below may be used in conjunction
    with YMODEM Batch Protocol, or with single file transfers identical to the
    XMODEM/CRC protocol except for minimal changes to support 1k blocks.

    Another extension is the YMODEM-g protocol.  YMODEM-g provides batch
    transfers with maximum throughput when used with end to end error
    correcting media, such as X.PC and error correcting modems, including 9600
    bps units by TeleBit, U.S.Robotics, Hayes, Electronic Vaults, Data Race,
    and others.

    To complete this tome, edited versions of Ward Christensen's original
    protocol document and John Byrns's CRC-16 document are included for
    reference.

    References to the MODEM or MODEM7 protocol have been changed to XMODEM to
    accommodate the vernacular.  In Australia, it is properly called the
    Christensen Protocol.


    3.1  Some Messages from the Pioneer

    #: 130940 S0/Communications 25-Apr-85  18:38:47
    Sb: my protocol
    Fm: Ward Christensen 76703,302 [2]
    To: all

    Be aware the article[3] DID quote me correctly in terms of the phrases
    like "not robust", etc.

    It was a quick hack I threw together, very unplanned (like everything I
    do), to satisfy a personal need to communicate with "some other" people.

    ONLY the fact that it was done in 8/77, and that I put it in the public
    domain immediately, made it become the standard that it is.







    __________________________________________________________________________

     1. Available for IBM PC,XT,AT, Unix and Xenix

     2. Edited for typesetting appearance

     3. Infoworld April 29 p. 16




    Chapter 3







    X/YMODEM Protocol Reference    June 18 1988                              8



    I think its time for me to

    (1) document it; (people call me and say "my product is going to include
    it - what can I 'reference'", or "I'm writing a paper on it, what do I put
    in the bibliography") and

    (2) propose an "incremental extension" to it, which might take "exactly"
    the form of Chuck Forsberg's YAM protocol.  He wrote YAM in C for CP/M and
    put it in the public domain, and wrote a batch protocol for Unix[4] called
    rb and sb (receive batch, send batch), which was basically XMODEM with
       (a) a record 0 containing filename date time and size
       (b) a 1K block size option
       (c) CRC-16.

    He did some clever programming to detect false ACK or EOT, but basically
    left them the same.

    People who suggest I make SIGNIFICANT changes to the protocol, such as
    "full duplex", "multiple outstanding blocks", "multiple destinations", etc
    etc don't understand that the incredible simplicity of the protocol is one
    of the reasons it survived to this day in as many machines and programs as
    it may be found in!

    Consider the PC-NET group back in '77 or so - documenting to beat the band
    - THEY had a protocol, but it was "extremely complex", because it tried to
    be "all things to all people" - i.e. send binary files on a 7-bit system,
    etc.  I was not that "benevolent". I (emphasize > I < ) had an 8-bit UART,
    so "my protocol was an 8-bit protocol", and I would just say "sorry" to
    people who were held back by 7-bit limitations.  ...

    Block size: Chuck Forsberg created an extension of my protocol, called
    YAM, which is also supported via his public domain programs for UNIX
    called rb and sb - receive batch and send batch.  They cleverly send a
    "block 0" which contains the filename, date, time, and size.
    Unfortunately, its UNIX style, and is a bit weird[5] - octal numbers, etc.
    BUT, it is a nice way to overcome the kludgy "echo the chars of the name"
    introduced with MODEM7.  Further, chuck uses CRC-16 and optional 1K
    blocks.  Thus the record 0, 1K, and CRC, make it a "pretty slick new
    protocol" which is not significantly different from my own.

    Also, there is a catchy name - YMODEM.  That means to some that it is the
    "next thing after XMODEM", and to others that it is the Y(am)MODEM


    __________

     4. VAX/VMS versions of these programs are also available.

     5. The file length, time, and file mode are optional.  The pathname and
        file length may be sent alone if desired.




    Chapter 3







    X/YMODEM Protocol Reference    June 18 1988                              9



    protocol.  I don't want to emphasize that too much - out of fear that
    other mfgrs might think it is a "competitive" protocol, rather than an
    "unaffiliated" protocol.  Chuck is currently selling a much-enhanced
    version of his CP/M-80 C program YAM, calling it Professional Yam, and its
    for the PC - I'm using it right now.  VERY slick!  32K capture buffer,
    script, scrolling, previously captured text search, plus built-in commands
    for just about everything - directory (sorted every which way), XMODEM,
    YMODEM, KERMIT, and ASCII file upload/download, etc.  You can program it
    to "behave" with most any system - for example when trying a number for
    CIS it detects the "busy" string back from the modem and substitutes a
    diff phone # into the dialing string and branches back to try it.











































    Chapter 3







    X/YMODEM Protocol Reference    June 18 1988                             10



    4.  XMODEM PROTOCOL ENHANCEMENTS

    This chapter discusses the protocol extensions to Ward Christensen's 1982
    XMODEM protocol description document.

    The original document recommends the user be asked whether to continue
    trying or abort after 10 retries.  Most programs no longer ask the
    operator whether he wishes to keep retrying.  Virtually all correctable
    errors are corrected within the first few retransmissions.  If the line is
    so bad that ten attempts are insufficient, there is a significant danger
    of undetected errors.  If the connection is that bad, it's better to
    redial for a better connection, or mail a floppy disk.


    4.1  Graceful Abort

    The YAM and Professional-YAM X/YMODEM routines recognize a sequence of two
    consecutive CAN (Hex 18) characters without modem errors (overrun,
    framing, etc.) as a transfer abort command.  This sequence is recognized
    when is waiting for the beginning of a block or for an acknowledgement to
    a block that has been sent.  The check for two consecutive CAN characters
    reduces the number of transfers aborted by line hits.  YAM sends eight CAN
    characters when it aborts an XMODEM, YMODEM, or ZMODEM protocol file
    transfer.  Pro-YAM then sends eight backspaces to delete the CAN
    characters from the remote's keyboard input buffer, in case the remote had
    already aborted the transfer and was awaiting a keyboarded command.


    4.2  CRC-16 Option

    The XMODEM protocol uses an optional two character CRC-16 instead of the
    one character arithmetic checksum used by the original protocol and by
    most commercial implementations.  CRC-16 guarantees detection of all
    single and double bit errors,  all errors with an odd number of error
    bits, all burst errors of length 16 or less, 99.9969% of all 17-bit error
    bursts, and 99.9984 per cent of all possible longer error bursts.  By
    contrast, a double bit error, or a burst error of 9 bits or more can sneak
    past the XMODEM protocol arithmetic checksum.

    The XMODEM/CRC protocol is similar to the XMODEM protocol, except that the
    receiver specifies CRC-16 by sending C (Hex 43) instead of NAK when
    requesting the FIRST block.  A two byte CRC is sent in place of the one
    byte arithmetic checksum.

    YAM's c option to the r command enables CRC-16 in single file reception,
    corresponding to the original implementation in the MODEM7 series
    programs.  This remains the default because many commercial communications
    programs and bulletin board systems still do not support CRC-16,
    especially those written in Basic or Pascal.

    XMODEM protocol with CRC is accurate provided both sender and receiver



    Chapter 4                                     XMODEM Protocol Enhancements







    X/YMODEM Protocol Reference    June 18 1988                             11



    both report a successful transmission.  The protocol is robust in the
    presence of characters lost by buffer overloading on timesharing systems.

    The single character ACK/NAK responses generated by the receiving program
    adapt well to split speed modems, where the reverse channel is limited to
    ten per cent or less of the main channel's speed.

    XMODEM and YMODEM are half duplex protocols which do not attempt to
    transmit information and control signals in both directions at the same
    time.  This avoids buffer overrun problems that have been reported by
    users attempting to exploit full duplex asynchronous file transfer
    protocols such as Blast.

    Professional-YAM adds several proprietary logic enhancements to XMODEM's
    error detection and recovery.  These compatible enhancements eliminate
    most of the bad file transfers other programs make when using the XMODEM
    protocol under less than ideal conditions.


    4.3  XMODEM-1k 1024 Byte Block

    Disappointing throughput downloading from Unix with YMODEM[1] lead to the
    development of 1024 byte blocks in 1982.  1024 byte blocks reduce the
    effect of delays from timesharing systems, modems, and packet switched
    networks on throughput by 87.5 per cent in addition to decreasing XMODEM's
    3 per cent overhead (block number, CRC, etc.).

    Some environments cannot accept 1024 byte bursts, including some networks
    and minicomputer ports.  The longer block length should be an option.

    The choice to use 1024 byte blocks is expressed to the sending program on
    its command line or selection menu.[2] 1024 byte blocks improve throughput
    in many applications.

    An STX (02) replaces the SOH (01) at the beginning of the transmitted
    block to notify the receiver of the longer block length.  The transmitted
    block contains 1024 bytes of data.  The receiver should be able to accept
    any mixture of 128 and 1024 byte blocks.  The block number (in the second
    and third bytes of the block) is incremented by one for each block
    regardless of the block length.

    The sender must not change between 128 and 1024 byte block lengths if it
    has not received a valid ACK for the current block.  Failure to observe                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   