[Search for users] [Overall Top Noters] [List of all Conferences] [Download this site]

Conference 7.286::atarist

Title:Atari ST, TT, & Falcon
Notice:Please read note 1.0 and its replies before posting!
Moderator:FUNYET::ANDERSON
Created:Mon Apr 04 1988
Last Modified:Tue May 06 1997
Last Successful Update:Fri Jun 06 1997
Number of topics:1433
Total number of notes:10312

216.0. "Xmodem Protocol" by PANGLS::BAILEY () Tue Sep 06 1988 21:24

    Does anybody have a description of the Xmodem protocol, or some
    source that implements it which I can get a copy of
    
    Thanks,
    
    Steph
T.RTitleUserPersonal
Name
DateLines
216.1PNO::SANDERSBa belaganaWed Sep 07 1988 13:297
        The next reply includes the C source to vms XMODEM.  I copied it
        out of one of the Amiga users directory.  I'll try to dig up an
        electronic copy of the XModem, XModem-CRC and YModem
        documentation later on this week.
        
        Bob
216.2XModem.cPNO::SANDERSBa belaganaWed Sep 07 1988 13:301009
/**************************** xmodem.c *********************************
*
* This program sends/rcvs files to the terminal using the XMODEM protocol.
* To run the program, it must be installed as a foriegn command.
* Type the name of the program followed by the mode and name of the file you
* wish to send (or receive) to begin the file transfer.  The program will wait
* to receive a NAK before starting the first sector (sector 1).
*
* Example:
*
*   $ xmodem :== $disk:[dir]xmodem
*   $ set term/eight			    - need eight bit transfers
*   $ xmodem -r	 foo.bar		    - receive a file
*   $ xmodem -s	 foo.bar		    - send a file
*   $ xmodem -ir foo.bar		    - image mode receive
*   $ xmodem -is foo.bar		    - image mode send
*   $ xmodem -cr foo.bar		    - receive text file using <CR>
*					      instead of <LF> as terminator.
*
* The program has a 60 second time-out limit when waiting for input. 
* If the time-out limit is exceeded, the program will abort.
*
* The program will also abort if a ^X (control-X) is received between packets
*
**********************************************************************/

/*

Environment:  VAX/VMS (or ULTRIX if you define it)

Author:	    Peter Sichel	 Creation date: 23-Dec-1983
Rewrite:    Dave Wecker		 Creation date: 04-JUL-1986

Modified:

9-Jan-1984  PAS  Fixed numerous bugs in initial version, and
		 added time-out testing on input.
26-Jun-1986 AVD  Added time estimate of transfer.

860704	DBW	Merged into one program, added image mode, got rid of ^Z
		got it to run on ULTRIX
860708	DBW	Added <CR> <LF> switch, automatic /eight/nobroad and auto baud

*/

/********************** Operating system defs ***********************/

#define VMS	1	/* Are we running under VMS? */
#define ULTRIX	0	/* Are we running under ULTRIX? */

/********************************************************************/

#if	VMS
#include stdio		/*  Definitions for standard I/O  */
#include stat
#include ssdef		/*  Define system service status values  */
#include descrip	/*  Macros for descriptor definition  */
#include iodef		/*  QIO function code definitions  */
#include ttdef		/*  terminal characteristics  */
#include tt2def		/*  extended terminal characteristics */
#include file		/*  File mode definitions */

#else

#include <stdio.h>
#include <sgtty.h>
#include <signal.h>
#include <fcntl.h>
#include <sys/ioctl.h>
#include <sys/types.h>
#include <sys/file.h>
#include <sys/stat.h>
#endif

/*  D e c l a r e   f u n c t i o n s  */

#if VMS
int LIB$GET_EF ();	/*  get event flag  */
int LIB$FREE_EF ();

#else
#define	SS$_TIMEOUT -1

#endif

int read_sector ();	/*  read in next sector from file */
int write_sector ();	/*  write next sector to file */


/*  M o d u l e   W i d e   s t o r a g e  */

static int
    tpichan,            /*  terminal port input channel      */
    tpochan,		/*  terminal port output channel     */
    tpi_ef,             /*  terminal port input event flag   */
    tpo_ef,		/*  terminal port output event flag  */
    mode,		/*  mode of operation		     */
    speed,		/*  baud rate of terminal	     */
    fildes,		/*  file descriptor		     */
    eol;		/*  end of line character to use     */

FILE *src_ptr;          /*  file pointer for send file  */
struct stat sbuf;

#if VMS
static $DESCRIPTOR(terminal_port,"SYS$INPUT");
static int  oterm_attr[3],nterm_attr[3];
static struct {
       short status;
       short offset;
       short termlen;
       short term;
       } input_iosb;
static struct {
       short status;
       unsigned char xmit_baud;
       unsigned char rcv_baud;
       unsigned char crfill;
       unsigned char lffill;
       unsigned char parity;
       unsigned char unused;
       } sensemode_iosb;

#else
struct sgttyb	ostate,nstate;	/* terminal state */

#endif

/*  literal special character definitions  */
#define   CR     0x0D
#define   LF     0x0A
#define   SOH    0x01
#define   EOT    0x04
#define   ACK    0x06
#define   NAK    0x15
#define   CAN    0x18
#define   CTLZ   0x1A

#define MAXLINE 256
#define RETRY_LIMIT 10

/* Operational modes */
#define MDNONE	0
#define MDSEND	1
#define	MDRCV	2
#define MDSR	3
#define MDIMAGE	4
#define MDSENDI	5
#define MDRCVI	6
#define MDSRI	7


main (argc,argv)

int argc;
char *argv[];

    {

    int  i,j,curstat, nrec;


    mode = MDNONE; i = 0; eol = LF;
    while (++i < argc) {
	if (argv[i][0] != '-') break;
	for (j=1; argv[i][j] != 0; j++) {
	    switch (argv[i][j]) {
		case 'r':
		case 'R':
		mode |= MDRCV;
		break;

		case 's':
		case 'S':
		mode |= MDSEND;
		break;

		case 'c':
		case 'C':
		eol = CR;
		break;

		case 'i':
		case 'I':
		mode |= MDIMAGE;
		break;

		default:
		return(usage());
		}
	    }
	}
    if (argc != 3 || (mode & MDSR) == MDSR || (mode & MDSR) == MDNONE)
	return(usage());

    /*  assign channel for terminal port I/O  */

#if VMS
    curstat = SYS$ASSIGN (&terminal_port, &tpichan, 0, 0) ;
    if (curstat != SS$_NORMAL)
	{
	fprintf (stderr,"\n%% Unable to assign terminal port input channel.");
	set_nopassall(tpichan);
	exit (curstat);
	}
    curstat = SYS$ASSIGN (&terminal_port, &tpochan, 0, 0) ;
    if (curstat != SS$_NORMAL)
	{
	fprintf (stderr,"\n%% Unable to assign terminal port output channel.");
	set_nopassall(tpichan);
	exit (curstat);
	}

    /*  allocate event flags for terminal port I/O  */

    curstat = LIB$GET_EF (&tpi_ef) ;
    if (curstat != SS$_NORMAL)
	{
	fprintf (stderr,"\n%% Unable to allocate terminal port input event flag.");
	set_nopassall(tpichan);
	exit (curstat);
	}

    curstat = LIB$GET_EF (&tpo_ef) ;
    if (curstat != SS$_NORMAL)
	{
	fprintf (stderr,"\n%% Unable to allocate terminal port output event flag.");
	set_nopassall(tpichan);
	exit (curstat);
	}

#endif

    if ((mode & MDRCV) != 0) {

#if VMS
	if (mode == MDRCV)
	    fildes = creat (argv[2], 0666, "rfm=var", "rat=cr");
	else
	    fildes = creat (argv[2], 0666, "rfm=fix", "mrs=128");
#else
        fildes = creat(argv[2],0666);
#endif

	if (fildes == -1) {
	    fprintf(stderr,"\n Unable to open receive file: %s\n", argv[2]);
	    return (1);
	    }
	if (mode == MDRCV) src_ptr = fdopen (fildes, "w");
	fprintf(stderr,"\n Ready to receive file: %s\n",argv[2]);
	}
    else {
	src_ptr = fopen (argv[2],"r");

	/* test if open successful */
	if (src_ptr == NULL) {
	    fprintf(stderr,"\n Unable to open send file: %s\n", argv[2]);
	    return (1);
	    }

	/* print how long we think it might take */
	if (fstat(fileno(src_ptr), &sbuf) < 0) {
	    perror("fstat");
	    return (1);
	    }
	nrec = (sbuf.st_size / 128) + 1;

	/* get the current baud rate */
	set_passall(tpichan);
	set_nopassall(tpichan);
	fprintf(stderr,
	    "%s: %d records, %d minutes transfer time at %d baud\n",
		argv[2], nrec, nrec / (speed/27), speed);

	if (mode == MDSENDI) {
	    fclose(src_ptr);
#if VMS
	    fildes = open (argv[2], O_RDONLY, "rfm=fix", "mrs=128");
#else
	    fildes = open (argv[2], O_RDONLY);
#endif
	    if (fildes == -1) {
		fprintf(stderr,"\n Unable to open receive file: %s\n", argv[2]);
		return (1);
		}
	    }
	}

    /*
    * send/rcv file
    */

    fprintf(stderr,"\nType a ^X (control-X) to cancel the transfer\n\n");
    set_passall(tpichan);

    if ((mode & MDSEND) != 0) send();
    else		      rcv();

    set_nopassall(tpichan);

    if (mode == MDRCV) {
	/* flush record buffer */
	write_sector(src_ptr, 0);
	fclose(src_ptr);
	}
    else if (mode == MDRCVI) {
	close(fildes);
	}

    /*  free event flags, and deallocate I/O channel  */
#if VMS
    LIB$FREE_EF (&tpi_ef);
    LIB$FREE_EF (&tpo_ef);
    SYS$DASSGN (tpichan);
    SYS$DASSGN (tpochan);
    return SS$_NORMAL;
#endif
    }	/*  end of MAIN routine  */

/**************************************************
*
* send - send file using XMODEM protocol
*
* returns 0, prints message on error
*
***************************************************/
send()
    {
    int  curstat, gstat, ichar, i;
    int  time_out;
    int  checksum;
    int  error_count;
    int  sector_number;
    char sector_buffer[130];


    /* get first sector from file */
    sector_number = 1;
    error_count = 0;
    time_out = 60;
    curstat = read_sector (src_ptr, sector_buffer);

    /* wait for NAK to begin file transfer */
    ichar = 0;
    while (ichar != NAK) {
	gstat = tp_getc (&ichar, tpichan, tpi_ef, time_out);
	if (gstat == SS$_TIMEOUT) {
	    fprintf (stderr, "\r\n*** timeout\r\n");
	    return(0);
	    }
	if (ichar == CAN) {
	    fprintf (stderr, "\r\n*** CANcelled by user\r\n");
	    return(0);
	    }
	}
    /* loop to send entire file */
    while (!curstat) {
	tp_putc (SOH, tpochan, tpo_ef);
	tp_putc (sector_number, tpochan, tpo_ef);
	tp_putc ((~sector_number & 0xFF), tpochan, tpo_ef);

	checksum = 0;
	for (i=0; i<128; i++) {
	    tp_putc (sector_buffer[i], tpochan, tpo_ef);
	    checksum += sector_buffer[i];
	    checksum &= 0xFF;
	    }
	tp_putc (checksum, tpochan, tpo_ef);

	/* get response */
	gstat = tp_getc (&ichar, tpichan, tpi_ef, time_out);
	if (gstat == SS$_TIMEOUT) {
	    fprintf (stderr, "\r\n*** timeout\r\n");
	    return(0);
	    }

	switch (ichar) {

	    case NAK:
	    error_count += 1;
	    if (error_count > 10) {
		fprintf (stderr, "\r\n*** Too many errors detected");
		return (0);
		}
	    break;

	    case ACK:
	    error_count = 0;
	    /* advance sector count */
	    sector_number += 1;
	    sector_number &= 0xFF;
	    /* read next sector */
	    curstat = read_sector (src_ptr, sector_buffer);
	    break;

	    case CAN:
	    fprintf (stderr, "\r\n*** CANcelled by user\r\n");
	    return(0);

	    default:
	    ; /* ignore */
	    /*fprintf (stderr, "\r\n***** Spurious response");*/
	    }
	}   /* end while not EOF */


    /* end of file, send EOT and wait for ACK */
    ichar = 0;
    while (ichar != ACK) {
	tp_putc (EOT, tpochan, tpo_ef);
	gstat = tp_getc (&ichar, tpichan, tpi_ef, 6);
	if (gstat == SS$_TIMEOUT) ichar = 0;
	if (ichar == CAN) {
	    fprintf (stderr, "\r\n*** CANcelled by user\r\n");
	    return(0);
	    }
	error_count += 1;
	if (error_count > 10) {
	    fprintf (stderr, "\r\n*** failed to acknowledge EOT");
	    break;
	    }
	}
    return(0);
    }

/******************************************************************
*
*  Read a 128 byte sector into sector buf.
*  If less than 128 characters are available, pad with NULs.
*  If end of file, return non-zero.
*
********************************************************************/
read_sector (src_ptr, sector_buffer)

FILE *src_ptr;
char *sector_buffer;

    {

    int i;
    char *curstat;
    int sec_count_filled;
    int sec_count_remaining;
    static int rec_count_used = 0;
    static int rec_count_remaining = 0;
    static char record_buffer[256];


    /* send an image mode sector */
    if (mode == MDSENDI) {
	i = read(fildes,sector_buffer,128);
	if (i <= 0) return(1);
	while (i < 128) sector_buffer[i++] = 0;
	return(0);
	}

    sec_count_filled = 0;

    /* do until we have a complete sector */
    while (sec_count_filled < 128) {

	/* first get any data left from previous record */

	/* record contains enough data to fill sector */
	sec_count_remaining = 128 - sec_count_filled;
	if (rec_count_remaining >= sec_count_remaining) {
	    strncpy (&sector_buffer[sec_count_filled],
		     &record_buffer[rec_count_used],
		      sec_count_remaining);
	    rec_count_used += sec_count_remaining;
	    rec_count_remaining -= sec_count_remaining;
	    return (0);
	    }
	/* record is not empty, but contains less than enough to fill sector */
	if (rec_count_remaining > 0) {
	    strncpy (&sector_buffer[sec_count_filled],
	    &record_buffer[rec_count_used],
	    rec_count_remaining);
	    sec_count_filled += rec_count_remaining;
	    rec_count_remaining = 0;
	    }

	/*  read next record from file  */
	curstat = fgets (record_buffer, MAXLINE, src_ptr);

	if (curstat == NULL) {
	    /*  end of file  */
	    if (sec_count_filled == 0) return (1);    /* EOF */
	    for (i=sec_count_filled; i<128; i++) {
		sector_buffer[i] = 0;
		}
	    return (0);
	    }
	rec_count_remaining = strlen (record_buffer);
	rec_count_used = 0;
	record_buffer[rec_count_remaining-1] = eol;
	}   /* end while */

    return (0);
    }

/**************************************
*
* rcv - receive file using xmodem protocol
*
***************************************/
rcv()
    {

    int  curstat, ichar, i;
    int  repeat;
    int  time_out;
    int  checksum;
    int  error_count;
    int  sector_number;
    char sector_buffer[130];


    sector_number = 1;
    error_count = 5;
    time_out = 10;
    ichar = 0;

    /* send NAK and wait for start of sector */
    tp_putc (NAK, tpochan, tpo_ef);
    /* loop to get entire file */
    while (ichar != EOT) {
	while (1) {    /* try to read a sector */

	    if (error_count > RETRY_LIMIT) {
		fprintf (stderr,
		    "\r\n*** Retry limit exceeded, transfer aborted");
		return(0);
		}
	    repeat = 0;
	    /* sync to SOH */

	    curstat = tp_getc (&ichar, tpichan, tpi_ef, time_out);
	    if (curstat == SS$_TIMEOUT) ichar = 0;
	    while ((ichar != SOH) && (ichar != EOT)) {

		if (ichar == CAN) {
		    fprintf (stderr, "\r\n*** CANcelled by user\n");
		    return(0);
		    }
		error_count += 1;
		if (error_count > RETRY_LIMIT) {
		    fprintf (stderr, "\n*** Retry limit exceeded, transfer aborted");
		    return(0);
		    }
		/* throw away current sector */
		while (curstat != SS$_TIMEOUT) {
		    curstat = tp_getc (&ichar, tpichan, tpi_ef, time_out);
		    }

		/* send NAK and wait for start of sector */
		tp_putc (NAK, tpochan, tpo_ef);
		curstat = tp_getc (&ichar, tpichan, tpi_ef, time_out);
		if (curstat == SS$_TIMEOUT) ichar = 0;
		}
	    if (ichar == EOT) {
		/* end of file */
		tp_putc (ACK, tpochan, tpo_ef);
		break;
		}


	    /*
	    *  r e c e i v e d   S O H
	    */

	    /* get sector number */
	    curstat = tp_getc (&ichar, tpichan, tpi_ef, time_out);
	    if (curstat == SS$_TIMEOUT) {
		error_count += 1;
		break;   /* resync to SOH */
		}

	    if (ichar != sector_number) {
		if (ichar != (sector_number - 1)) {
		    error_count += 1;
		    break;  /* resync to SOH */
		    }
		else repeat = 1;   /* accept repeat of last sector */
		}

	    /* get complement sector number */
	    curstat = tp_getc (&ichar, tpichan, tpi_ef, time_out);
	    if (curstat == SS$_TIMEOUT) {
		error_count += 1;
		break;   /* resync to SOH */
		}
	    if (ichar != (0xFF & ~sector_number)) {
		if (ichar != (0xFF & ~(sector_number - 1))) {
		    error_count += 1;
		    break;   /* resync to SOH */
		    }
		}


	    /* read in the sector data */
	    checksum = 0;
	    for (i=0; i<128; i++) {
		curstat = tp_getc(&sector_buffer[i],tpichan,tpi_ef,time_out);
		if (curstat == SS$_TIMEOUT) {
		    error_count += 1;
		    break;   /* resync to SOH */
		    }
		checksum += sector_buffer[i];
		checksum &= 0xFF;
		}

	    /* get checksum */
	    curstat = tp_getc (&ichar, tpichan, tpi_ef, time_out);
	    if (curstat == SS$_TIMEOUT) {
		error_count += 1;
		break;   /* resync to SOH */
		}
	    if (ichar != checksum) {
		error_count += 1;
		break;   /* resync to SOH */
		}

	    /* if not repeat of previous sector, store it */
	    if (!repeat) {
		write_sector (src_ptr, sector_buffer);
		sector_number += 1;
		sector_number &= 0xFF;
		error_count = 0;
		}

	    /* acknowledge sector */
	    tp_putc (ACK, tpochan, tpo_ef);

	    }   /* loop to try next sector */

	}    /* end while not EOT */

    return(1);
    }   /* end routine rcv */


/***********************************************************
*
*  Build complete records from 128 byte sectors,
*  and write them to the file specified by src_ptr.
*  If sector_buffer is zero, flush the record buffer.
*
************************************************************/
write_sector (src_ptr, sector_buffer)

FILE *src_ptr;
char *sector_buffer;

    {

    int curstat, i, temp;
    int sec_count_used;

    static int rec_count_used = 0;
    static char record_buffer[512];


    /* are we in image mode */
    if (mode == MDRCVI) {
	write(fildes,sector_buffer,128);
	return(1);
	}

    /* flush buffer ? */
    if (sector_buffer == 0) {
	if (rec_count_used == 0) return (0);
	record_buffer[rec_count_used] = 0;
	fprintf (src_ptr, "%s", record_buffer);
	return (1);
	}


    sec_count_used = 0;
    /* loop to process entire sector */
    while (sec_count_used < 128) {
	/* look for next record marker in sector buffer */
	for (i=sec_count_used; i<128; i++) {
	    if (sector_buffer[i] == eol) {
		/* transfer part of sector buffer to record buffer */
		temp = i - sec_count_used;
		strncpy (&record_buffer[rec_count_used],
		&sector_buffer[sec_count_used],
		temp);
		rec_count_used += temp;
		sec_count_used += temp + 1;

		/* add null to end of data in record buffer */
		record_buffer[rec_count_used] = 0;

		/* write out record buffer */
		fprintf (src_ptr, "%s\n", record_buffer);
		rec_count_used = 0;
		}
	    }

	/* add rest of sector buffer which is not a complete record
	to record buffer */
	if (sec_count_used < 128) {
	    /* transfer part of sector buffer to record buffer */
	    strncpy (&record_buffer[rec_count_used],
		     &sector_buffer[sec_count_used],
		     (128 - sec_count_used) );
	    rec_count_used += (128 - sec_count_used);
	    sec_count_used += (128 - sec_count_used);
	    }


	/* if record buffer is over 255 chars, write it out */
	if (rec_count_used > 255) {

	    /* add null to end of data in record buffer */
	    record_buffer[rec_count_used] = 0;

	    /* write out record buffer */
	    fprintf (src_ptr, "%s", record_buffer);
	    rec_count_used = 0;
	    }
	}   /* end while */

    return (0);
    }

/******************************************************
*
* Read single character from terminal port
*
********************************************************/
tp_getc (ichar, tpichan, tpi_ef, time_out)

int *ichar;		/* address of place to put character read */
int tpichan;            /* terminal port input channel */
int tpi_ef;		/* terminal input event flag */
int time_out;           /* read time-out in seconds */

    {
    int curstat,n,num;
    short int iosb[4];
    char charbuf[4];

#if VMS
    /*  read character from terminal port */
    curstat = SYS$QIOW (
    tpi_ef,			/*  efn     */
    tpichan,			/*  chan    */
    IO$_TTYREADALL + IO$M_NOECHO + IO$M_TIMED,
			        /*  func    */
    iosb,			/*  iosb    */
    0,				/*  astadr  */
    0,				/*  astprm  */
    &charbuf[0],		/*  p1      */
    1,               		/*  p2      */
    time_out,                   /*  p3      */
    0,
    0,
    0
    );

    if (curstat != SS$_NORMAL)
	{
	fprintf (stderr,"\n%% Problem reading character from terminal port.");
	set_nopassall(tpichan);
	exit (curstat);
	}

    *ichar = charbuf[0] & 0xFF;

    return (iosb[0]);    /* return iosb to indicate timeout condition */

#else /*ULTRIX */
    
    n = time_out;
    while (n-- > 0) {
	ioctl(0,FIONREAD,&num);
	if (num > 0) return(read(0,ichar,1));
	sleep(1);
	}
    *ichar = 0;
    return(SS$_TIMEOUT);

#endif
    }	/*  End of routine tp_getc  */


/****************************************************
*
* Write a single character to the terminal port
*
*****************************************************/
tp_putc (ichar, tpochan, tpo_ef)

int ichar;		/* character to putput */
int tpochan;		/* terminal port output channel */
int tpo_ef;             /* terminal port output event flag */

    {

    int curstat;

#if VMS
    /*  write character to terminal port  */
    curstat = SYS$QIOW (
    tpo_ef,			/*  efn     */
    tpochan,			/*  chan    */
    IO$_WRITEVBLK + IO$M_NOFORMAT,/*  func    */
    0,				/*  iosb    */
    0,				/*  astadr  */
    0,				/*  astprm  */
    &ichar,			/*  p1      */
    1,               		/*  p2      */
    0,
    0,
    0,
    0
    );

    if (curstat != SS$_NORMAL)
	{
	fprintf (stderr,"\n%% Problem writing character to terminal port.");
	set_nopassall(tpichan);
	exit (curstat);
	}

    return (curstat);

#else
    return(write(1,&ichar,1));
#endif
    }	/*  End of routine tp_putc  */
/****************************************
*
* Set terminal to PASSALL mode
*
****************************************/
set_passall (tpichan)

int tpichan;
    {

    int  curstat,i;

#if VMS
    /*  read terminal characteristic bits  */
    curstat = SYS$QIOW (
    0,				/*  efn     */
    tpichan,			/*  chan    */
    IO$_SENSEMODE,		/*  func    */
    &sensemode_iosb,		/*  iosb    */
    0,				/*  astadr  */
    0,				/*  astprm  */
    oterm_attr,			/*  p1      */
    12,               		/*  p2      */
    0,				/*  p3	    */
    0,
    0,
    0
    );

    if (curstat != SS$_NORMAL)
	{
	fprintf (stderr,
	    "\n%% Problem reading command terminal characteristics.");
	exit (curstat);
	}

    /*  modify terminal characteristics to include PASSALL  */
    for (i = 0; i < 3; i++) nterm_attr[i] = oterm_attr[i];
    nterm_attr[1] |= TT$M_PASSALL;
    nterm_attr[1] |= TT$M_EIGHTBIT;
    nterm_attr[1] |= TT$M_NOBRDCST;
    nterm_attr[1] &= ~(TT$M_HOSTSYNC | TT$M_READSYNC | TT$M_TTSYNC);
    nterm_attr[2] |= TT2$M_PASTHRU;

    /*  set terminal characteristic bits  */
    curstat = SYS$QIOW(
    0,				/*  efn     */
    tpichan,			/*  chan    */
    IO$_SETMODE,		/*  func    */
    &input_iosb,		/*  iosb    */
    0,				/*  astadr  */
    0,				/*  astprm  */
    nterm_attr,			/*  p1      */
    12,               		/*  p2      */
    0,
    0,
    0,
    0
    );
    if (curstat != SS$_NORMAL)
	{
	fprintf (stderr,
	    "\n%% Problem setting command terminal characteristics.");
	set_nopassall(tpichan);
	exit (curstat);
	}

    /* now fix up the sensed baud rate */
    switch (sensemode_iosb.xmit_baud) {
	case TT$C_BAUD_110:	speed = 110;	break;
	case TT$C_BAUD_1200:	speed = 1200;	break;
	case TT$C_BAUD_134:	speed = 134;	break;
	case TT$C_BAUD_150:	speed = 150;	break;
	case TT$C_BAUD_1800:	speed = 1800;	break;
	case TT$C_BAUD_19200:	speed = 19200;	break;
	case TT$C_BAUD_2000:	speed = 2000;	break;
	case TT$C_BAUD_2400:	speed = 2400;	break;
	case TT$C_BAUD_300:	speed = 300;	break;
	case TT$C_BAUD_3600:	speed = 3600;	break;
	case TT$C_BAUD_4800:	speed = 4800;	break;
	case TT$C_BAUD_50:	speed = 50;	break;
	case TT$C_BAUD_600:	speed = 600;	break;
	case TT$C_BAUD_7200:	speed = 7200;	break;
	case TT$C_BAUD_75:	speed = 75;	break;
	case TT$C_BAUD_9600:	speed = 9600;	break;
	default:		speed = 2400;	break;
	}

#else
    gtty(0, &ostate);
    gtty(0, &nstate);
    nstate.sg_flags |= RAW;
    nstate.sg_flags &= ~(ECHO|CRMOD);
    stty(0, &nstate);    

    /* now fix up the sensed baud rate */
    switch (ostate.sg_ospeed) {
	case B50:   speed = 50;	    break;
	case B75:   speed = 70;	    break;
	case B110:  speed = 110;    break;
	case B134:  speed = 134;    break;
	case B150:  speed = 150;    break;
	case B200:  speed = 200;    break;
	case B300:  speed = 300;    break;
	case B600:  speed = 600;    break;
	case B1200: speed = 1200;   break;
	case B1800: speed = 1800;   break;
	case B2400: speed = 2400;   break;
	case B4800: speed = 4800;   break;
	case B9600: speed = 9600;   break;
	default:    speed = 19200;  break;
	}

#endif
    }	/*  end of routine set_passall  */


/**********************************
*
* Set command terminal to NOPASSALL mode
*
************************************/
set_nopassall (tpichan)
int tpichan;
    {

    int  curstat;

#if VMS
    /*  set terminal characteristic bits  */
    curstat = SYS$QIOW (
    0,				/*  efn     */
    tpichan,			/*  chan    */
    IO$_SETMODE,		/*  func    */
    &input_iosb,		/*  iosb    */
    0,				/*  astadr  */
    0,				/*  astprm  */
    oterm_attr,			/*  p1      */
    12,               		/*  p2      */
    0,
    0,
    0,
    0
    );

    if (curstat != SS$_NORMAL)
	{
	fprintf (stderr,
	    "\n%% Problem setting command terminal characteristics.");
	exit (curstat);
	}

#else
    stty(0, &ostate);
#endif

    }	/*  end of routine set_passall  */

usage()
    {
    fprintf(stderr,"\nUsage: xmodem -[ic]{rs} file.ext\n");
    fprintf(stderr,"	i = image mode\n");
    fprintf(stderr,"	c = use <CR> instead of <LF> in text files\n");
    fprintf(stderr,"	r = receive file\n");
    fprintf(stderr,"	s = send file\n\n");
    fprintf(stderr,"REMEMBER:\n");
#if VMS
    fprintf(stderr,"	- $ XMODEM :== $DEV:[DIR]XMODEM\n");
    fprintf(stderr,"	- $ set term/speed=<baudrate>\n");
#else
    fprintf(stderr,"	- %% stty <baudrate>\n");
#endif
    fprintf(stderr,"	- turn off all special chars on a terminal server\n\n");
    return(1);
    }
216.3X,Y,Zmodem sources)PNO::SANDERSBa belaganaWed Sep 07 1988 19:058
        Of even more use may be the sources located at:
        
                Vthrax::Amiga$Public:vmszmodem.bck
        
        (I'm still looking for the documentation...)
        
        Bob
216.4File sizes. Just found it apropriatePILOU::ANDERSENRelocating my way home ?Thu Sep 08 1988 08:1929
$ backup/list vthrax::amiga$public:vmszmodem.bck/save
Listing of save set(s)

Save set:          VMSZMODEM.BCK
Written by:        KIP         
UIC:               [000200,000010]
Date:               9-AUG-1988 08:22:30.38
Command:           BACKUP *.* VMSZMODEM.BCK/SAVE
Operating system:  VAX/VMS version V5.0
BACKUP version:    V5.0
CPU ID register:   08000000
Node name:         _VTHRAX::
Written on:        _VTHRAX$DUA0:
Block size:        32256
Group size:        10
Buffer count:      3

[PUBLIC.AMIGA.TMP]RZ.C;1                                   63   7-JUL-1988 15:38
[PUBLIC.AMIGA.TMP]RZ.EXE;1                                131  24-MAY-1988 22:33
[PUBLIC.AMIGA.TMP]RZ.MAN;1                                 20   7-JUL-1988 13:00
[PUBLIC.AMIGA.TMP]SZ.C;1                                   75   7-JUL-1988 15:38
[PUBLIC.AMIGA.TMP]SZ.EXE;1                                147  24-MAY-1988 22:33
[PUBLIC.AMIGA.TMP]SZ.MAN;1                                 29   7-JUL-1988 13:00
[PUBLIC.AMIGA.TMP]VVMODEM.C;1                              13   7-JUL-1988 15:39

Total of 7 files, 478 blocks
End of save set

    
    
216.5PNO::SANDERSBa belaganaThu Sep 08 1988 19:1233
        You can also get a somewhat updated version of the posted
        Xmodem.c program from:
        
                Cvg""::Work1:[Campanella.kits]xmodem.bck
        
        The contents are listed below.
        
        Listing of save set(s)

Save set:          XMODEM.BCK
Written by:        CAMPANELLA  
UIC:               [000100,000027]
Date:               1-AUG-1988 16:02:29.68
Command:           BACKUP/LOG COMM$STANDARD*.*,COMM*.DOC,*.MMS [CAMPANELLA.KITS]XMODEM.BCK/SAVE/PROT=W:RE
Operating system:  VAX/VMS version V5.0
BACKUP version:    V5.0
CPU ID register:   08000000
Node name:         _HATRIK::
Written on:        _$1$DUA1:
Block size:        32256
Group size:        10
Buffer count:      3

[CAMPANELLA.APPLE.XMODEM]COMM$STANDARD_XMODEM.C;9          49  21-MAR-1988 12:51
[CAMPANELLA.APPLE.XMODEM]COMM$STANDARD_XMODEM.EXE;1       124  27-JUL-1988 09:32
[CAMPANELLA.APPLE.XMODEM]COMM$STANDARD_XMODEM.OBJ;1        18  27-JUL-1988 09:30
[CAMPANELLA.APPLE.XMODEM]COMM$SD_HACK_XMODEM.DOC;1          3  19-AUG-1987 10:30
[CAMPANELLA.APPLE.XMODEM]DESCRIP.MMS;14                     3  27-JUL-1988 09:29

Total of 5 files, 197 blocks
End of save set

216.6PNO::SANDERSBa belaganaThu Sep 08 1988 19:131981


				      - 1 -



			 XMODEM/YMODEM PROTOCOL REFERENCE
		     A compendium of documents describing the

				XMODEM and YMODEM

			     File Transfer Protocols




		      This document was formatted 10-27-87.







			     Edited by Chuck Forsberg












		     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
    Modem (TeleGodzilla): 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, the heading in YMODEM.DOC's Figure 1
    has mutated 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      10-27-87				     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      10-27-87				     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.

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

       + 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 switch
	 between 1024 and 128 byte blocks at the end of file(s), and when the
	 frequency of retransmissions so suggests.

       + 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.

    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
    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      10-27-87				     5



    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      10-27-87				     6



    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      10-27-87				     7



    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      10-27-87				     8



    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      10-27-87				     9



    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      10-27-87				    10



    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
    per byte overhead 3 per cent on long files.

    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, but some environments cannot accept 1024 byte
    bursts, especially minicomputers running 19.2kb ports.

    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
    this restriction allows transmission errors to pass undetected.



    __________

     1. The name hadn't been coined yet, but the protocol was the same.

     2. See "KMD/IMP Exceptions to YMODEM" below.




    Chapter 4					  XMODEM Protocol Enhancements







    X/YMODEM Protocol Reference      10-27-87				    11



    If 1024 byte blocks are being used, it is possible for a file to "grow" up
    to the next multiple of 1024 bytes.  This does not waste disk space if the
    allocation granularity is 1k or greater.  With YMODEM batch transmission,
    the optional file length transmitted in the file name block allows the
    receiver to discard the padding, preserving the exact file length and
    contents.

    1024 byte blocks may be used with batch file transmission or with single
    file transmission.	CRC-16 should be used with the k option to preserve
    data integrity over phone lines.  If a program wishes to enforce this
    recommendation, it should cancel the transfer, then issue an informative
    diagnostic message if the receiver requests checksum instead of CRC-16.

    Under no circumstances may a sending program use CRC-16 unless the
    receiver commands CRC-16.

	      Figure 1.  XMODEM-1k Blocks

	      SENDER				      RECEIVER
						      "s -k foo.bar"
	      "foo.bar open x.x minutes"
						      C
	      STX 01 FE Data[1024] CRC CRC
						      ACK
	      STX 02 FD Data[1024] CRC CRC
						      ACK
	      STX 03 FC Data[1000] CPMEOF[24] CRC CRC
						      ACK
	      EOT
						      ACK

	      Figure 2.  Mixed 1024 and 128 byte Blocks

	      SENDER				      RECEIVER
						      "s -k foo.bar"
	      "foo.bar open x.x minutes"
						      C
	      STX 01 FE Data[1024] CRC CRC
						      ACK
	      STX 02 FD Data[1024] CRC CRC
						      ACK
	      SOH 03 FC Data[128] CRC CRC
						      ACK
	      SOH 04 FB Data[100] CPMEOF[28] CRC CRC
						      ACK
	      EOT
						      ACK







    Chapter 4					  XMODEM Protocol Enhancements







    X/YMODEM Protocol Reference      10-27-87				    12



    5.	YMODEM Batch File Transmission

    The YMODEM Batch protocol is an extension to the XMODEM/CRC protocol that
    allows 0 or more files to be transmitted with a single command.  (Zero
    files may be sent if none of the requested files is accessible.) The
    design approach of the YMODEM Batch protocol is to use the normal routines
    for sending and receiving XMODEM blocks in a layered fashion similar to
    packet switching methods.

    Why was it necessary to design a new batch protocol when one already
    existed in MODEM7?[1] The batch file mode used by MODEM7 is unsuitable
    because it does not permit full pathnames, file length, file date, or
    other attribute information to be transmitted.  Such a restrictive design,
    hastily implemented with only CP/M in mind, would not have permitted
    extensions to current areas of personal computing such as Unix, DOS, and
    object oriented systems.  In addition, the MODEM7 batch file mode is
    somewhat susceptible to transmission impairments.

    As in the case of single a file transfer, the receiver initiates batch
    file transmission by sending a "C" character (for CRC-16).

    The sender opens the first file and sends block number 0 with the
    following information.[2]

    Only the pathname (file name) part is required for batch transfers.

    To maintain upwards compatibility, all unused bytes in block 0 must be set
    to null.

    Pathname The pathname (conventionally, the file name) is sent as a null
	 terminated ASCII string.  This is the filename format used by the
	 handle oriented MSDOS(TM) functions and C library fopen functions.
	 An assembly language example follows:
				  DB	  'foo.bar',0
	 No spaces are included in the pathname.  Normally only the file name
	 stem (no directory prefix) is transmitted unless the sender has
	 selected YAM's f option to send the full pathname.  The source drive
	 (A:, B:, etc.) is not sent.

	 Filename Considerations:



    __________

     1. The MODEM7 batch protocol transmitted CP/M FCB bytes f1...f8 and
	t1...t3 one character at a time.  The receiver echoed these bytes as
	received, one at a time.

     2. Only the data part of the block is described here.




    Chapter 5					  XMODEM Protocol Enhancements







    X/YMODEM Protocol Reference      10-27-87				    13



	    + File names are forced to lower case unless the sending system
	      supports upper/lower case file names.  This is a convenience for
	      users of systems (such as Unix) which store filenames in upper
	      and lower case.

	    + The receiver should accommodate file names in lower and upper
	      case.

	    + When transmitting files between different operating systems,
	      file names must be acceptable to both the sender and receiving
	      operating systems.

	 If directories are included, they are delimited by /; i.e.,
	 "subdir/foo" is acceptable, "subdir\foo" is not.

    Length The file length and each of the succeeding fields are optional.[3]
	 The length field is stored in the block as a decimal string counting
	 the number of data bytes in the file.	The file length does not
	 include any CPMEOF (^Z) or other garbage characters used to pad the
	 last block.

	 If the file being transmitted is growing during transmission, the
	 length field should be set to at least the final expected file
	 length, or not sent.

	 The receiver stores the specified number of characters, discarding
	 any padding added by the sender to fill up the last block.

    Modification Date The mod date is optional, and the filename and length
	 may be sent without requiring the mod date to be sent.

	 Iff the modification date is sent, a single space separates the
	 modification date from the file length.

	 The mod date is sent as an octal number giving the time the contents
	 of the file were last changed, measured in seconds from Jan 1 1970
	 Universal Coordinated Time (GMT).  A date of 0 implies the
	 modification date is unknown and should be left as the date the file
	 is received.

	 This standard format was chosen to eliminate ambiguities arising from
	 transfers between different time zones.





    __________

     3. Fields may not be skipped.




    Chapter 5					  XMODEM Protocol Enhancements







    X/YMODEM Protocol Reference      10-27-87				    14



    Mode Iff the file mode is sent, a single space separates the file mode
	 from the modification date.  The file mode is stored as an octal
	 string.  Unless the file originated from a Unix system, the file mode
	 is set to 0.  rb(1) checks the file mode for the 0x8000 bit which
	 indicates a Unix type regular file.  Files with the 0x8000 bit set
	 are assumed to have been sent from another Unix (or similar) system
	 which uses the same file conventions.	Such files are not translated
	 in any way.


    Serial Number Iff the serial number is sent, a single space separates the
	 serial number from the file mode.  The serial number of the
	 transmitting program is stored as an octal string.  Programs which do
	 not have a serial number should omit this field, or set it to 0.  The
	 receiver's use of this field is optional.


    Other Fields YMODEM was designed to allow additional header fields to be
	 added as above without creating compatibility problems with older
	 YMODEM programs.  Please contact Omen Technology if other fields are
	 needed for special application requirements.

    The rest of the block is set to nulls.  This is essential to preserve
    upward compatibility.[4]

    If the filename block is received with a CRC or other error, a
    retransmission is requested.  After the filename block has been received,
    it is ACK'ed if the write open is successful.  If the file cannot be
    opened for writing, the receiver cancels the transfer with CAN characters
    as described above.

    The receiver then initiates transfer of the file contents according to the
    standard XMODEM/CRC protocol.

    After the file contents have been transmitted, the receiver again asks for
    the next pathname.

    Transmission of a null pathname terminates batch file transmission.

    Note that transmission of no files is not necessarily an error.  This is
    possible if none of the files requested of the sender could be opened for
    reading.



    __________

     4. If, perchance, this information extends beyond 128 bytes (possible
	with Unix 4.2 BSD extended file names), the block should be sent as a
	1k block as described above.




    Chapter 5					  XMODEM Protocol Enhancements







    X/YMODEM Protocol Reference      10-27-87				    15



    The YMODEM receiver requests CRC-16 by default.

    The Unix programs sz(1) and rz(1) included in the source code file
    RZSZ.ZOO should answer other questions about YMODEM batch protocol.

	      Figure 3.  YMODEM Batch Transmission Session

	      SENDER				      RECEIVER
						      "sb foo.*<CR>"
	      "sending in batch mode etc."
						      C (command:rb)
	      SOH 00 FF foo.c NUL[123] CRC CRC
						      ACK
						      C
	      SOH 01 FE Data[128] CRC CRC
						      ACK
	      SOH 03 FC Data[128] CRC CRC
						      ACK
	      SOH 04 FB Data[100] CPMEOF[28] CRC CRC
						      ACK
	      EOT
						      NAK
	      EOT
						      ACK
						      C
	      SOH 00 FF NUL[128] CRC CRC
						      ACK

	    Figure 4.  YMODEM Batch Transmission Session-1k Blocks

	    SENDER				    RECEIVER
						    "sb -k foo.*<CR>"
	    "sending in batch mode etc."
						    C (command:rb)
	    SOH 00 FF foo.c NUL[123] CRC CRC
						    ACK
						    C
	    STX 02 FD Data[1024] CRC CRC
						    ACK
	    SOH 03 FC Data[128] CRC CRC
						    ACK
	    SOH 04 FB Data[100] CPMEOF[28] CRC CRC
						    ACK
	    EOT
						    NAK
	    EOT
						    ACK
						    C
	    SOH 00 FF NUL[128] CRC CRC
						    ACK




    Chapter 5					  XMODEM Protocol Enhancements







    X/YMODEM Protocol Reference      10-27-87				    16



	   Figure 5.  YMODEM Filename block transmitted by sz

	   -rw-r--r--  6347 Jun 17 1984 20:34 bbcsched.txt

	   00 0100FF62 62637363 6865642E 74787400   |...bbcsched.txt.|
	   10 36333437 20333331 34373432 35313320   |6347 3314742513 |
	   20 31303036 34340000 00000000 00000000   |100644..........|
	   30 00000000 00000000 00000000 00000000
	   40 00000000 00000000 00000000 00000000
	   50 00000000 00000000 00000000 00000000
	   60 00000000 00000000 00000000 00000000
	   70 00000000 00000000 00000000 00000000
	   80 000000CA 56

		Figure 6.  YMODEM Header Information and Features

    _____________________________________________________________
    | Program	| Length | Date | Mode | S/N | 1k-Blk | YMODEM-g |
    |___________|________|______|______|_____|________|__________|
    |Unix rz/sz | yes	 | yes	| yes  | no  | yes    | sb only  |
    |___________|________|______|______|_____|________|__________|
    |VMS rb/sb	| yes	 | no	| no   | no  | yes    | no	 |
    |___________|________|______|______|_____|________|__________|
    |Pro-YAM	| yes	 | yes	| no   | yes | yes    | yes	 |
    |___________|________|______|______|_____|________|__________|
    |CP/M YAM	| no	 | no	| no   | no  | yes    | no	 |
    |___________|________|______|______|_____|________|__________|
    |KMD/IMP	| ?	 | no	| no   | no  | yes    | no	 |
    |___________|________|______|______|_____|________|__________|

    5.1  KMD/IMP Exceptions to YMODEM

    KMD and IMP use a "CK" character sequence emitted by the receiver to
    trigger the use of 1024 byte blocks as an alternative to specifying this
    option to the sending program.  Although this two character sequence works
    well on single process micros in direct communication, timesharing systems
    and packet switched networks can separate the successive characters by
    several seconds, rendering this method unreliable.

    Sending programs may detect the CK sequence if the operating enviornment
    does not preclude reliable implementation.

    Instead of the standard YMODEM file length, KMD and IMP transmit the CP/M
    record count in the last two bytes of the header block.










    Chapter 6					  XMODEM Protocol Enhancements







    X/YMODEM Protocol Reference      10-27-87				    17



    6.	YMODEM-g File Transmission

    Developing technology is providing phone line data transmission at ever
    higher speeds using very specialized techniques.  These high speed modems,
    as well as session protocols such as X.PC, provide high speed, nearly
    error free communications at the expense of considerably increased delay
    time.

    This delay time is moderate compared to human interactions, but it
    cripples the throughput of most error correcting protocols.

    The g option to YMODEM has proven effective under these circumstances.
    The g option is driven by the receiver, which initiates the batch transfer
    by transmitting a G instead of C.  When the sender recognizes the G, it
    bypasses the usual wait for an ACK to each transmitted block, sending
    succeeding blocks at full speed, subject to XOFF/XON or other flow control
    exerted by the medium.

    The sender expects an inital G to initiate the transmission of a
    particular file, and also expects an ACK on the EOT sent at the end of
    each file.	This synchronization allows the receiver time to open and
    close files as necessary.

    If an error is detected in a YMODEM-g transfer, the receiver aborts the
    transfer with the multiple CAN abort sequence.  The ZMODEM protocol should
    be used in applications that require both streaming throughput and error
    recovery.

	    Figure 7.  YMODEM-g Transmission Session

	    SENDER				    RECEIVER
						    "sb foo.*<CR>"
	    "sending in batch mode etc..."
						    G (command:rb -g)
	    SOH 00 FF foo.c NUL[123] CRC CRC
						    G
	    SOH 01 FE Data[128] CRC CRC
	    STX 02 FD Data[1024] CRC CRC
	    SOH 03 FC Data[128] CRC CRC
	    SOH 04 FB Data[100] CPMEOF[28] CRC CRC
	    EOT
						    ACK
						    G
	    SOH 00 FF NUL[128] CRC CRC










    Chapter 6					  XMODEM Protocol Enhancements







    X/YMODEM Protocol Reference      10-27-87				    18



    7.	XMODEM PROTOCOL OVERVIEW

    8/9/82 by Ward Christensen.

    I will maintain a master copy of this.  Please pass on changes or
    suggestions via CBBS/Chicago at (312) 545-8086, CBBS/CPMUG (312) 849-1132
    or by voice at (312) 849-6279.

    7.1  Definitions

      <soh> 01H
      <eot> 04H
      <ack> 06H
      <nak> 15H
      <can> 18H
      <C>   43H


    7.2  Transmission Medium Level Protocol

    Asynchronous, 8 data bits, no parity, one stop bit.

    The protocol imposes no restrictions on the contents of the data being
    transmitted.  No control characters are looked for in the 128-byte data
    messages.  Absolutely any kind of data may be sent - binary, ASCII, etc.
    The protocol has not formally been adopted to a 7-bit environment for the
    transmission of ASCII-only (or unpacked-hex) data , although it could be
    simply by having both ends agree to AND the protocol-dependent data with
    7F hex before validating it.  I specifically am referring to the checksum,
    and the block numbers and their ones- complement.

    Those wishing to maintain compatibility of the CP/M file structure, i.e.
    to allow modemming ASCII files to or from CP/M systems should follow this
    data format:

       + ASCII tabs used (09H); tabs set every 8.

       + Lines terminated by CR/LF (0DH 0AH)

       + End-of-file indicated by ^Z, 1AH.  (one or more)

       + Data is variable length, i.e. should be considered a continuous
	 stream of data bytes, broken into 128-byte chunks purely for the
	 purpose of transmission.

       + A CP/M "peculiarity": If the data ends exactly on a 128-byte
	 boundary, i.e. CR in 127, and LF in 128, a subsequent sector
	 containing the ^Z EOF character(s) is optional, but is preferred.
	 Some utilities or user programs still do not handle EOF without ^Zs.





    Chapter 7					      Xmodem Protocol Overview







    X/YMODEM Protocol Reference      10-27-87				    19



       + The last block sent is no different from others, i.e.	there is no
	 "short block".
		  Figure 8.  XMODEM Message Block Level Protocol

    Each block of the transfer looks like:
	  <SOH><blk #><255-blk #><--128 data bytes--><cksum>
    in which:
    <SOH>	  = 01 hex
    <blk #>	  = binary number, starts at 01 increments by 1, and
		    wraps 0FFH to 00H (not to 01)
    <255-blk #>   = blk # after going thru 8080 "CMA" instr, i.e.
		    each bit complemented in the 8-bit block number.
		    Formally, this is the "ones complement".
    <cksum>	  = the sum of the data bytes only.  Toss any carry.

    7.3  File Level Protocol

    7.3.1  Common_to_Both_Sender_and_Receiver
    All errors are retried 10 times.  For versions running with an operator
    (i.e. NOT with XMODEM), a message is typed after 10 errors asking the
    operator whether to "retry or quit".

    Some versions of the protocol use <can>, ASCII ^X, to cancel transmission.
    This was never adopted as a standard, as having a single "abort" character
    makes the transmission susceptible to false termination due to an <ack>
    <nak> or <soh> being corrupted into a <can> and aborting transmission.

    The protocol may be considered "receiver driven", that is, the sender need
    not automatically re-transmit, although it does in the current
    implementations.


    7.3.2  Receive_Program_Considerations
    The receiver has a 10-second timeout.  It sends a <nak> every time it
    times out.	The receiver's first timeout, which sends a <nak>, signals the
    transmitter to start.  Optionally, the receiver could send a <nak>
    immediately, in case the sender was ready.	This would save the initial 10
    second timeout.  However, the receiver MUST continue to timeout every 10
    seconds in case the sender wasn't ready.

    Once into a receiving a block, the receiver goes into a one-second timeout
    for each character and the checksum.  If the receiver wishes to <nak> a
    block for any reason (invalid header, timeout receiving data), it must
    wait for the line to clear.  See "programming tips" for ideas

    Synchronizing:  If a valid block number is received, it will be: 1) the
    expected one, in which case everything is fine; or 2) a repeat of the
    previously received block.	This should be considered OK, and only
    indicates that the receivers <ack> got glitched, and the sender re-
    transmitted; 3) any other block number indicates a fatal loss of
    synchronization, such as the rare case of the sender getting a line-glitch



    Chapter 7					      Xmodem Protocol Overview







    X/YMODEM Protocol Reference      10-27-87				    20



    that looked like an <ack>.	Abort the transmission, sending a <can>


    7.3.3  Sending_program_considerations
    While waiting for transmission to begin, the sender has only a single very
    long timeout, say one minute.  In the current protocol, the sender has a
    10 second timeout before retrying.	I suggest NOT doing this, and letting
    the protocol be completely receiver-driven.  This will be compatible with
    existing programs.

    When the sender has no more data, it sends an <eot>, and awaits an <ack>,
    resending the <eot> if it doesn't get one.	Again, the protocol could be
    receiver-driven, with the sender only having the high-level 1-minute
    timeout to abort.


    Here is a sample of the data flow, sending a 3-block message.  It includes
    the two most common line hits - a garbaged block, and an <ack> reply
    getting garbaged.  <xx> represents the checksum byte.

		  Figure 9.  Data flow including Error Recovery

    SENDER				    RECEIVER
				  times out after 10 seconds,
				  <---		    <nak>
    <soh> 01 FE -data- <xx>	  --->
				  <---		    <ack>
    <soh> 02 FD -data- xx	  --->	     (data gets line hit)
				  <---		    <nak>
    <soh> 02 FD -data- xx	  --->
				  <---		    <ack>
    <soh> 03 FC -data- xx	  --->
    (ack gets garbaged) 	  <---		    <ack>
    <soh> 03 FC -data- xx	  --->		    <ack>
    <eot>			  --->
				  <---	     <anything except ack>
    <eot>			  --->
				  <---		    <ack>
    (finished)

    7.4  Programming Tips

       + The character-receive subroutine should be called with a parameter
	 specifying the number of seconds to wait.  The receiver should first
	 call it with a time of 10, then <nak> and try again, 10 times.

	 After receiving the <soh>, the receiver should call the character
	 receive subroutine with a 1-second timeout, for the remainder of the
	 message and the <cksum>.  Since they are sent as a continuous stream,
	 timing out of this implies a serious like glitch that caused, say,
	 127 characters to be seen instead of 128.



    Chapter 7					      Xmodem Protocol Overview







    X/YMODEM Protocol Reference      10-27-87				    21



       + When the receiver wishes to <nak>, it should call a "PURGE"
	 subroutine, to wait for the line to clear.  Recall the sender tosses
	 any characters in its UART buffer immediately upon completing sending
	 a block, to ensure no glitches were mis- interpreted.

	 The most common technique is for "PURGE" to call the character
	 receive subroutine, specifying a 1-second timeout,[1] and looping
	 back to PURGE until a timeout occurs.	The <nak> is then sent,
	 ensuring the other end will see it.

       + You may wish to add code recommended by John Mahr to your character
	 receive routine - to set an error flag if the UART shows framing
	 error, or overrun.  This will help catch a few more glitches - the
	 most common of which is a hit in the high bits of the byte in two
	 consecutive bytes.  The <cksum> comes out OK since counting in 1-byte
	 produces the same result of adding 80H + 80H as with adding 00H +
	 00H.






























    __________

     1. These times should be adjusted for use with timesharing systems.




    Chapter 7					      Xmodem Protocol Overview







    X/YMODEM Protocol Reference      10-27-87				    22



    8.	XMODEM/CRC Overview

    Original 1/13/85 by John Byrns -- CRC option.

    Please pass on any reports of errors in this document or suggestions for
    improvement to me via Ward's/CBBS at (312) 849-1132, or by voice at (312)
    885-1105.

    The CRC used in the Modem Protocol is an alternate form of block check
    which provides more robust error detection than the original checksum.
    Andrew S. Tanenbaum says in his book, Computer Networks, that the CRC-
    CCITT used by the Modem Protocol will detect all single and double bit
    errors, all errors with an odd number of bits, all burst errors of length
    16 or less, 99.997% of 17-bit error bursts, and 99.998% of 18-bit and
    longer bursts.[1]

    The changes to the Modem Protocol to replace the checksum with the CRC are
    straight forward. If that were all that we did we would not be able to
    communicate between a program using the old checksum protocol and one
    using the new CRC protocol. An initial handshake was added to solve this
    problem. The handshake allows a receiving program with CRC capability to
    determine whether the sending program supports the CRC option, and to
    switch it to CRC mode if it does. This handshake is designed so that it
    will work properly with programs which implement only the original
    protocol. A description of this handshake is presented in section 10.

		Figure 10.  Message Block Level Protocol, CRC mode

    Each block of the transfer in CRC mode looks like:
	 <SOH><blk #><255-blk #><--128 data bytes--><CRC hi><CRC lo>
    in which:
    <SOH>	 = 01 hex
    <blk #>	 = binary number, starts at 01 increments by 1, and
		   wraps 0FFH to 00H (not to 01)
    <255-blk #>  = ones complement of blk #.
    <CRC hi>	 = byte containing the 8 hi order coefficients of the CRC.
    <CRC lo>	 = byte containing the 8 lo order coefficients of the CRC.

    8.1  CRC Calculation

    8.1.1  Formal_Definition
    To calculate the 16 bit CRC the message bits are considered to be the
    coefficients of a polynomial. This message polynomial is first multiplied
    by X^16 and then divided by the generator polynomial (X^16 + X^12 + X^5 +


    __________

     1. This reliability figure is misleading because XMODEM's critical
	supervisory functions are not protected by this CRC.




    Chapter 8					      Xmodem Protocol Overview







    X/YMODEM Protocol Reference      10-27-87				    23



    1) using modulo two arithmetic. The remainder left after the division is
    the desired CRC. Since a message block in the Modem Protocol is 128 bytes
    or 1024 bits, the message polynomial will be of order X^1023. The hi order
    bit of the first byte of the message block is the coefficient of X^1023 in
    the message polynomial.  The lo order bit of the last byte of the message
    block is the coefficient of X^0 in the message polynomial.

	       Figure 11.  Example of CRC Calculation written in C

    The following XMODEM crc routine is taken from "rbsb.c".  Please refer to
    the source code for these programs (contained in RZSZ.ZOO) for usage.  A
    fast table driven version is also included in this file.

    /* update CRC */
    unsigned short
    updcrc(c, crc)
    register c;
    register unsigned crc;
    {
	    register count;

	    for (count=8; --count>=0;) {
		    if (crc & 0x8000) {
			    crc <<= 1;
			    crc += (((c<<=1) & 0400)  !=  0);
			    crc ^= 0x1021;
		    }
		    else {
			    crc <<= 1;
			    crc += (((c<<=1) & 0400)  !=  0);
		    }
	    }
	    return crc;
    }

    8.2  CRC File Level Protocol Changes

    8.2.1  Common_to_Both_Sender_and_Receiver
    The only change to the File Level Protocol for the CRC option is the
    initial handshake which is used to determine if both the sending and the
    receiving programs support the CRC mode. All Modem Programs should support
    the checksum mode for compatibility with older versions.  A receiving
    program that wishes to receive in CRC mode implements the mode setting
    handshake by sending a <C> in place of the initial <nak>.  If the sending
    program supports CRC mode it will recognize the <C> and will set itself
    into CRC mode, and respond by sending the first block as if a <nak> had
    been received. If the sending program does not support CRC mode it will
    not respond to the <C> at all. After the receiver has sent the <C> it will
    wait up to 3 seconds for the <soh> that starts the first block. If it
    receives a <soh> within 3 seconds it will assume the sender supports CRC
    mode and will proceed with the file exchange in CRC mode. If no <soh> is



    Chapter 8					      Xmodem Protocol Overview







    X/YMODEM Protocol Reference      10-27-87				    24



    received within 3 seconds the receiver will switch to checksum mode, send
    a <nak>, and proceed in checksum mode. If the receiver wishes to use
    checksum mode it should send an initial <nak> and the sending program
    should respond to the <nak> as defined in the original Modem Protocol.
    After the mode has been set by the initial <C> or <nak> the protocol
    follows the original Modem Protocol and is identical whether the checksum
    or CRC is being used.


    8.2.2  Receive_Program_Considerations
    There are at least 4 things that can go wrong with the mode setting
    handshake.

      1.  the initial <C> can be garbled or lost.

      2.  the initial <soh> can be garbled.

      3.  the initial <C> can be changed to a <nak>.

      4.  the initial <nak> from a receiver which wants to receive in checksum
	  can be changed to a <C>.

    The first problem can be solved if the receiver sends a second <C> after
    it times out the first time. This process can be repeated several times.
    It must not be repeated too many times before sending a <nak> and
    switching to checksum mode or a sending program without CRC support may
    time out and abort. Repeating the <C> will also fix the second problem if
    the sending program cooperates by responding as if a <nak> were received
    instead of ignoring the extra <C>.

    It is possible to fix problems 3 and 4 but probably not worth the trouble
    since they will occur very infrequently. They could be fixed by switching
    modes in either the sending or the receiving program after a large number
    of successive <nak>s. This solution would risk other problems however.


    8.2.3  Sending_Program_Considerations
    The sending program should start in the checksum mode. This will insure
    compatibility with checksum only receiving programs. Anytime a <C> is
    received before the first <nak> or <ack> the sending program should set
    itself into CRC mode and respond as if a <nak> were received. The sender
    should respond to additional <C>s as if they were <nak>s until the first
    <ack> is received. This will assist the receiving program in determining
    the correct mode when the <soh> is lost or garbled. After the first <ack>
    is received the sending program should ignore <C>s.









    Chapter 8					      Xmodem Protocol Overview







    X/YMODEM Protocol Reference      10-27-87				    25



    8.3  Data Flow Examples with CRC Option

    Here is a data flow example for the case where the receiver requests
    transmission in the CRC mode but the sender does not support the CRC
    option. This example also includes various transmission errors.  <xx>
    represents the checksum byte.

	  Figure 12.  Data Flow: Receiver has CRC Option, Sender Doesn't

    SENDER					  RECEIVER
			    <---		<C>
				    times out after 3 seconds,
			    <---		<C>
				    times out after 3 seconds,
			    <---		<C>
				    times out after 3 seconds,
			    <---		<C>
				    times out after 3 seconds,
			    <---		<nak>
    <soh> 01 FE -data- <xx> --->
			    <---		<ack>
    <soh> 02 FD -data- <xx> --->	(data gets line hit)
			    <---		<nak>
    <soh> 02 FD -data- <xx> --->
			    <---		<ack>
    <soh> 03 FC -data- <xx> --->
       (ack gets garbaged)  <---		<ack>
				    times out after 10 seconds,
			    <---		<nak>
    <soh> 03 FC -data- <xx> --->
			    <---		<ack>
    <eot>		    --->
			    <---		<ack>

    Here is a data flow example for the case where the receiver requests
    transmission in the CRC mode and the sender supports the CRC option.  This
    example also includes various transmission errors.	<xxxx> represents the
    2 CRC bytes.
















    Chapter 8					      Xmodem Protocol Overview







    X/YMODEM Protocol Reference      10-27-87				    26



	       Figure 13.  Receiver and Sender Both have CRC Option

    SENDER					 RECEIVER
			      <---		   <C>
    <soh> 01 FE -data- <xxxx> --->
			      <---		   <ack>
    <soh> 02 FD -data- <xxxx> --->	   (data gets line hit)
			      <---		   <nak>
    <soh> 02 FD -data- <xxxx> --->
			      <---		   <ack>
    <soh> 03 FC -data- <xxxx> --->
    (ack gets garbaged)       <---		   <ack>
					 times out after 10 seconds,
			      <---		   <nak>
    <soh> 03 FC -data- <xxxx> --->
			      <---		   <ack>
    <eot>		      --->
			      <---		   <ack>




































    Chapter 8					      Xmodem Protocol Overview







    X/YMODEM Protocol Reference      10-27-87				    27



    9.	MORE INFORMATION

    Please contact Omen Technology for troff source files and typeset copies
    of this document.


    9.1  TeleGodzilla Bulletin Board

    More information may be obtained by calling TeleGodzilla at 503-621-3746.
    Speed detection is automatic for 1200, 2400 and 19200(Telebit PEP) bps.
    TrailBlazer modem users may issue the TeleGodzilla trailblazer command to
    swith to 19200 bps once they have logged in.

    Interesting files include RZSZ.ZOO (C source code), YZMODEM.ZOO (Official
    XMODEM, YMODEM, and ZMODEM protocol descriptions), ZCOMMEXE.ARC,
    ZCOMMDOC.ARC, and ZCOMMHLP.ARC (PC-DOS shareware comm program with XMODEM,
    True YMODEM(TM), ZMODEM, Kermit Sliding Windows, Telink, MODEM7 Batch,
    script language, etc.).


    9.2  Unix UUCP Access

    UUCP sites can obtain the current version of this file with
		     uucp omen!/u/caf/public/ymodem.doc /tmp
    A continually updated list of available files is stored in
    /usr/spool/uucppublic/FILES.  When retrieving these files with uucp,
    remember that the destination directory on your system must be writeable
    by anyone, or the UUCP transfer will fail.

    The following L.sys line calls TeleGodzilla (Pro-YAM in host operation).
    TeleGodzilla determines the incoming speed automatically.

    In response to "Name Please:" uucico gives the Pro-YAM "link" command as a
    user name.	The password (Giznoid) controls access to the Xenix system
    connected to the IBM PC's other serial port.  Communications between
    Pro-YAM and Xenix use 9600 bps; YAM converts this to the caller's speed.

    Finally, the calling uucico logs in as uucp.

    omen Any ACU 2400 1-503-621-3746 se:--se: link ord: Giznoid in:--in: uucp



    10.  REVISIONS

    10-27-87 Optional fields added for number of files remaining to be sent
    and total number of bytes remaining to be sent.
    10-18-87 Flow control discussion added to 1024 byte block descritpion,
    minor revisions for clarity per user comments.
    8-03-87 Revised for clarity.
    5-31-1987 emphasizes minimum requirements for YMODEM, and updates



    Chapter 10					      Xmodem Protocol Overview







    X/YMODEM Protocol Reference      10-27-87				    28



    information on accessing files.
    9-11-1986 clarifies nomenclature and some minor points.
    The April 15 1986 edition clarifies some points concerning CRC
    calculations and spaces in the header.


    11.  YMODEM Programs

    ZCOMM, A shareware little brother to Professional-YAM, is available as
    ZCOMMEXE.ARC on TeleGodzilla and other bulletin board systems.  ZCOMM may
    be used to test YMODEM amd ZMODEM implementations.

    Unix programs supporting YMODEM are available on TeleGodzilla in RZSZ.ZOO.
    This ZOO archive includes a ZCOMM/Pro-YAM/PowerCom script ZUPL.T to upload
    a bootstrap program MINIRB.C, compile it, and then upload the rest of the
    files using the compiled MINIRB.  Most Unix like systems are supported,
    including V7, Xenix, Sys III, 4.2 BSD, SYS V, Idris, Coherent, and
    Regulus.

    A version for VAX-VMS is available in VRBSB.SHQ.

    Irv Hoff has added 1k blocks and basic YMODEM batch transfers to the KMD
    and IMP series programs, which replace the XMODEM and MODEM7/MDM7xx series
    respectively.  Overlays are available for a wide variety of CP/M systems.

    Questions about Professional-YAM communications software may be directed
    to:
	 Chuck Forsberg
	 Omen Technology Inc
	 17505-V Sauvie Island Road
	 Portland Oregon 97231
	 VOICE: 503-621-3406 :VOICE
	 Modem: 503-621-3746 Speed: 19200(Telebit PEP),2400,1200,300
	 Usenet: ...!tektronix!reed!omen!caf
	 CompuServe: 70007,2304
	 GEnie: CAF

    Unlike ZMODEM and Kermit, XMODEM and YMODEM place obstacles in the path of
    a reliable high performance implementation, evidenced by poor reliability
    under stress of the industry leaders' XMODEM and YMODEM programs.  Omen
    Technology provides consulting and other services to those wishing to
    implement XMODEM, YMODEM, and ZMODEM with state of the art features and
    reliability.











    Chapter 11					      Xmodem Protocol Overview











				     CONTENTS


     1.  TOWER OF BABEL...................................................   2
	 1.1  Definitions.................................................   2

     2.  YMODEM MINIMUM REQUIREMENTS......................................   4

     3.  WHY YMODEM?......................................................   5
	 3.1  Some Messages from the Pioneer..............................   6

     4.  XMODEM PROTOCOL ENHANCEMENTS.....................................   9
	 4.1  Graceful Abort..............................................   9
	 4.2  CRC-16 Option...............................................   9
	 4.3  XMODEM-1k 1024 Byte Block...................................  10

     5.  YMODEM Batch File Transmission...................................  12
	 5.1  KMD/IMP Exceptions to YMODEM................................  16

     6.  YMODEM-g File Transmission.......................................  17

     7.  XMODEM PROTOCOL OVERVIEW.........................................  18
	 7.1  Definitions.................................................  18
	 7.2  Transmission Medium Level Protocol..........................  18
	 7.3  File Level Protocol.........................................  19
	 7.4  Programming Tips............................................  20

     8.  XMODEM/CRC Overview..............................................  22
	 8.1  CRC Calculation.............................................  22
	 8.2  CRC File Level Protocol Changes.............................  23
	 8.3  Data Flow Examples with CRC Option..........................  25

     9.  MORE INFORMATION.................................................  27
	 9.1  TeleGodzilla Bulletin Board.................................  27
	 9.2  Unix UUCP Access............................................  27

    10.  REVISIONS........................................................  27

    11.  YMODEM Programs..................................................  28















				      - i -














				 LIST OF FIGURES


     Figure 1.	XMODEM-1k Blocks..........................................  11

     Figure 2.	Mixed 1024 and 128 byte Blocks............................  11

     Figure 3.	YMODEM Batch Transmission Session.........................  15

     Figure 4.	YMODEM Batch Transmission Session-1k Blocks...............  15

     Figure 5.	YMODEM Filename block transmitted by sz...................  16

     Figure 6.	YMODEM Header Information and Features....................  16

     Figure 7.	YMODEM-g Transmission Session.............................  17

     Figure 8.	XMODEM Message Block Level Protocol.......................  19

     Figure 9.	Data flow including Error Recovery........................  20

    Figure 10.	Message Block Level Protocol, CRC mode....................  22

    Figure 11.	Example of CRC Calculation written in C...................  23

    Figure 12.	Data Flow: Receiver has CRC Option, Sender Doesn't........  25

    Figure 13.	Receiver and Sender Both have CRC Option..................  26























				      - ii -





216.8PANGLS::BAILEYFri Sep 09 1988 18:414
    Just what I'd hoped for.
    
    Thanks, 
    Steph
216.9V2.12 fo ZModemPNO::SANDERSBa belaganaTue Sep 13 1988 15:0112
        The latest Zmodem source files (mainly for Unix and VMS) are
        available in RZSZ.ARC.
        
        
Directory $1$DUA33:[64K.SANDERSB.ST]

ARC.EXE;1               160
DSZ.DOC;1                45
RZSZ.ARC;1              178

Total of 3 files, 383 blocks.
216.10xmodem protocol descriptionCIMBAD::POWERSI Dream Of Wires - G. NumanWed Sep 14 1988 22:05188
    
    
     re .0

        Here is the xmodem protocol as layed out by it's creator.

     Bill Powers
================================================================================
MODEM PROTOCOL OVERVIEW  178 lines, 7.5K

1/1/82 by Ward Christensen.  I will maintain a master copy of
this.  Please pass on changes or suggestions via CBBS/Chicago
at (312) 545-8086, or by voice at (312) 849-6279.

NOTE this does not include things which I am not familiar with,
such as the CRC option implemented by John Mahr.

Last Rev: (none)

At the request of Rick Mallinak on behalf of the guys at
Standard Oil with IBM P.C.s, as well as several previous
requests, I finally decided to put my modem protocol into
writing.  It had been previously formally published only in the
AMRAD newsletter.

	Table of Contents
1. DEFINITIONS
2. TRANSMISSION MEDIUM LEVEL PROTOCOL
3. MESSAGE BLOCK LEVEL PROTOCOL
4. FILE LEVEL PROTOCOL
5. DATA FLOW EXAMPLE INCLUDING ERROR RECOVERY
6. PROGRAMMING TIPS.

-------- 1. DEFINITIONS.
<soh>	01H
<eot>	04H
<ack>	05H
<nak>	15H
<can>   18H

-------- 2. TRANSMISSION MEDIUM LEVEL PROTOCOL
Asynchronous, 8 data bits, no parity, one stop bit.

    The protocol imposes no restrictions on the contents of the
data being transmitted.  No control characters are looked for
in the 128-byte data messages.  Absolutely any kind of data may
be sent - binary, ASCII, etc.  The protocol has not formally
been adopted to a 7-bit environment for the transmission of
ASCII-only (or unpacked-hex) data , although it could be simply
by having both ends agree to AND the protocol-dependent data
with 7F hex before validating it.  I specifically am referring
to the checksum, and the block numbers and their ones-
complement.
    Those wishing to maintain compatibility of the CP/M file
structure, i.e. to allow modemming ASCII files to or from CP/M
systems should follow this data format:
  * ASCII tabs used (09H); tabs set every 8.
  * Lines terminated by CR/LF (0DH 0AH)
  * End-of-file indicated by ^Z, 1AH.  (one or more)
  * Data is variable length, i.e. should be considered a
    continuous stream of data bytes, broken into 128-byte
    chunks purely for the purpose of transmission. 
  * A CP/M "peculiarity": If the data ends exactly on a
    128-byte boundary, i.e. CR in 127, and LF in 128, a
    subsequent sector containing the ^Z EOF character(s)
    is optional, but is preferred.  Some utilities or
    user programs still do not handle EOF without ^Zs.
  * The last block sent is no different from others, i.e.
    there is no "short block".  

-------- 3. MESSAGE BLOCK LEVEL PROTOCOL
 Each block of the transfer looks like:
<SOH><blk #><255-blk #><--128 data bytes--><cksum>
    in which:
<SOH>       = 01 hex
<blk #>     = binary number, starts at 01 increments by 1, and
              wraps 0FFH to 00H (not to 01)
<255-blk #> = blk # after going thru 8080 "CMA" instr, i.e.
              each bit complemented in the 8-bit block number.
              Formally, this is the "ones complement".
<cksum>     = the sum of the data bytes only.  Toss any carry.

-------- 4. FILE LEVEL PROTOCOL

---- 4A. COMMON TO BOTH SENDER AND RECEIVER:

    All errors are retried 10 times.  For versions running with
an operator (i.e. NOT with XMODEM), a message is typed after 10
errors asking the operator whether to "retry or quit".
    Some versions of the protocol use <can>, ASCII ^X, to
cancel transmission.  This was never adopted as a standard, as
having a single "abort" character makes the transmission
susceptible to false termination due to an <ack> <nak> or <soh>
being corrupted into a <can> and canceling transmission.
    The protocol may be considered "receiver driven", that is,
the sender need not automatically re-transmit, although it does
in the current implementations.

---- 4B. RECEIVE PROGRAM CONSIDERATIONS:
    The receiver has a 10-second timeout.  It sends a <nak>
every time it times out.  The receiver's first timeout, which
sends a <nak>, signals the transmitter to start.  Optionally,
the receiver could send a <nak> immediately, in case the sender
was ready.  This would save the initial 10 second timeout. 
However, the receiver MUST continue to timeout every 10 seconds
in case the sender wasn't ready.
    Once into a receiving a block, the receiver goes into a
one-second timeout for each character and the checksum.  If the
receiver wishes to <nak> a block for any reason (invalid
header, timeout receiving data), it must wait for the line to
clear.  See "programming tips" for ideas
    Synchronizing:  If a valid block number is received, it
will be: 1) the expected one, in which case everything is fine;
or 2) a repeat of the previously received block.  This should
be considered OK, and only indicates that the receivers <ack>
got glitched, and the sender re-transmitted; 3) any other block
number indicates a fatal loss of synchronization, such as the
rare case of the sender getting a line-glitch that looked like
an <ack>.  Abort the transmission, sending a <can>

---- 4C. SENDING PROGRAM CONSIDERATIONS.

    While waiting for transmission to begin, the sender has
only a single very long timeout, say one minute.  In the
current protocol, the sender has a 10 second timeout before
retrying.  I suggest NOT doing this, and letting the protocol
be completely receiver-driven.  This will be compatible with
existing programs.
    When the sender has no more data, it sends an <eot>, and
awaits an <ack>, resending the <eot> if it doesn't get one. 
Again, the protocol could be receiver-driven, with the sender
only having the high-level 1-minute timeout to abort.


-------- 5. DATA FLOW EXAMPLE INCLUDING ERROR RECOVERY

Here is a sample of the data flow, sending a 3-block message.
It includes the two most common line hits - a garbaged block,
and an <ack> reply getting garbaged.  <xx> represents the
checksum byte.

SENDER					RECEIVER
				times out after 10 seconds,
			<---		<nak>
<soh> 01 FE -data- <xx>	--->
			<---		<ack>
<soh> 02 FD -data- xx	--->	(data gets line hit)
			<---		<nak>
<soh> 02 FD -data- xx	--->
			<---		<ack>
<soh> 03 FC -data- xx	--->
   (ack gets garbaged)	<---		<ack>
<soh> 03 FC -data- xx	--->		<ack>
<eot>			--->
			<---		<ack>

-------- 6. PROGRAMMING TIPS.

* The character-receive subroutine should be called with a
parameter specifying the number of seconds to wait.  The
receiver should first call it with a time of 10, then <nak> and
try again, 10 times.
  After receiving the <soh>, the receiver should call the
character receive subroutine with a 1-second timeout, for the
remainder of the message and the <cksum>.  Since they are sent
as a continuous stream, timing out of this implies a serious
like glitch that caused, say, 127 characters to be seen instead
of 128.

* When the receiver wishes to <nak>, it should call a "PURGE"
subroutine, to wait for the line to clear.  Recall the sender
tosses any characters in its UART buffer immediately upon
completing sending a block, to ensure no glitches were mis-
interpreted.
  The most common technique is for "PURGE" to call the
character receive subroutine, specifying a 1-second timeout,
and looping back to PURGE until a timeout occurs.  The <nak> is
then sent, ensuring the other end will see it.

* You may wish to add code recommended by Jonh Mahr to your
character receive routine - to set an error flag if the UART
shows framing error, or overrun.  This will help catch a few
more glitches - the most common of which is a hit in the high
bits of the byte in two consecutive bytes.  The <cksum> comes
out OK since counting in 1-byte produces the same result of
adding 80H + 80H as with adding 00H + 00H.


216.11Chicken or the Egg?LEDS::POLLANThu Feb 09 1989 21:159
    
    Hi,
    
    Could someone help me with the binary protocal to interface my new
    external 2400 baud modum to my ST.  I'm sure that people have been
    in this situation where you need some code just to download code.
    I will gladly return a floppy if someone would send me what I need.
    
                            Ken P
216.12How about unitermLEDDEV::WALLACEThu Feb 09 1989 23:008
    Send a disk to:
    	Ray Wallace
    	MLO21-4 / E10
    
    And I'll return it to you with Uniterm on it. Uniterm gives you
    a VT220 terminal emulator, Xmodem and Kermit file transfers.
    
    	Ray
216.13Xmodem ProtocolYNOTME::WALLACEWed Jan 24 1990 17:503293
	MODERATOR NOTE: This is a replacement for the original 216.7 note
			which somehow became corupted.
================================================================================
Note 216.7                       Xmodem Protocol                         7 of 12
PNO::SANDERSB "a belagana"                         3286 lines   8-SEP-1988 15:26
--------------------------------------------------------------------------------



	   The ZMODEM Inter Application File Transfer Protocol

			      Chuck Forsberg

			   Omen Technology Inc


	  A overview of this document is available as ZMODEM.OV
			     (in ZMDMOV.ARC)
















		       Omen Technology Incorporated
		      The High Reliability Software

		   17505-V Northwest Sauvie Island Road
			  Portland Oregon 97231
			VOICE: 503-621-3406 :VOICE
	  Modem: 503-621-3746 Speed 1200,2400,19200(Telebit PEP)
		     Compuserve:70007,2304  GEnie:CAF
		    UUCP: ...!tektronix!reed!omen!caf
























Chapter 0	      Rev 10-27-87  Typeset 10-27-87			 1







Chapter 0		     ZMODEM Protocol				 2



1.  INTENDED AUDIENCE

This document is intended for telecommunications managers, systems
programmers, and others who choose and implement asynchronous file
transfer protocols over dial-up networks and related environments.


2.  WHY DEVELOP ZMODEM?

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, now called XMODEM.

Advances in computing, modems and networking have spread the XMODEM
protocol far beyond the micro to micro environment for which it was
designed.  These application have exposed some weaknesses:

   o The awkward user interface is suitable for computer hobbyists.
     Multiple commands must be keyboarded to transfer each file.

   o Since commands must be given to both programs, simple menu selections
     are not possible.

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

   o The 8 bit checksum and unprotected supervison allow undetected errors
     and disrupted file transfers.

   o Only one file can be sent per command.  The file name has to be given
     twice, first to the sending program and then again to the receiving
     program.

   o The transmitted file accumulates as many as 127 bytes of garbage.

   o The modification date and other file attributes are lost.

   o XMODEM requires complete 8 bit transparency, all 256 codes.  XMODEM
     will not operate over some networks that use ASCII flow control or
     escape codes.  Setting network transparency disables important
     control functions for the duration of the call.

A number of other protocols have been developed over the years, but none
have proven satisfactory.

   o Lack of public domain documentation and example programs have kept
     proprietary protocols such as Relay, Blast, and others tightly bound
     to the fortunes of their suppliers.  These protocols have not
     benefited from public scrutiny of their design features.



Chapter 2	      Rev 10-27-87  Typeset 10-27-87			 2







Chapter 2		     ZMODEM Protocol				 3



   o Link level protocols such as X.25, X.PC, and MNP do not manage
     application to application file transfers.

   o Link Level protocols do not eliminate end-to-end errors.  Interfaces
     between error-free networks are not necessarily error-free.
     Sometimes, error-free networks aren't.

   o The Kermit protocol was developed to allow file transfers in
     environments hostile to XMODEM.  The performance compromises
     necessary to accommodate traditional mainframe environments limit
     Kermit's efficiency.  Even with completely transparent channels,
     Kermit control character quoting limits the efficiency of binary file
     transfers to about 75 per cent.[1]

     A number of submodes are used in various Kermit programs, including
     different methods of transferring binary files.  Two Kermit programs
     will mysteriously fail to operate with each other if the user has not
     correctly specified these submodes.

     Kermit Sliding Windows ("SuperKermit") improves throughput over
     networks at the cost of increased complexity.  SuperKermit requires
     full duplex communications and the ability to check for the presence
     of characters in the input queue, precluding its implementation on
     some operating systems.

     SuperKermit state transitions are encoded in a special language
     "wart" which requires a C compiler.

     SuperKermit sends an ACK packet for each data packet of 96 bytes
     (fewer if control characters are present).  This reduces throughput
     on high speed modems, from 1350 to 177 characters per second in one
     test.

A number of extensions to the XMODEM protocol have been made to improve
performance and (in some cases) the user interface.  They provide useful
improvements in some applications but not in others.  XMODEM's unprotected
control messages compromise their reliability.  Complex proprietary
techniques such as Cybernetic Data Recovery(TM)[2] improve reliability,
but are not universally available.  Some of the XMODEM mutant protocols
have significant design flaws of their own.

 o XMODEM-k uses 1024 byte blocks to reduce the overhead from transmission
   delays by 87 per cent compared to XMODEM, but network delays still


__________

 1. Some Kermit programs support run length encoding.

 2. Unique to DSZ, ZCOMM, Professional-YAM and PowerCom




Chapter 2	      Rev 10-27-87  Typeset 10-27-87			 3







Chapter 2		     ZMODEM Protocol				 4



   degrade performance.  Some networks cannot transmit 1024 byte packets
   without flow control, which is difficult to apply without impairing the
   perfect transparency required by XMODEM.  XMODEM-k adds garbage to
   received files.

 o YMODEM sends the file name, file length, and creation date at the
   beginning of each file, and allows optional 1024 byte blocks for
   improved throughput.  The handling of files that are not a multiple of
   1024 or 128 bytes is awkward, especially if the file length is not
   known in advance, or changes during transmission.  The large number of
   non conforming and substandard programs claiming to support YMODEM
   further complicates its use.

 o YMODEM-g provides efficient batch file transfers, preserving exact file
   length and file modification date.  YMODEM-g is a modification to
   YMODEM wherein ACKs for data blocks are not used.  YMODEM-g is
   essentially insensitive to network delays.  Because it does not support
   error recovery, YMODEM-g must be used hard wired or with a reliable
   link level protocol.  Successful application at high speed requires
   cafeful attention to transparent flow control.  When YMODEM-g detects a
   CRC error, data transfers are aborted.  YMODEM-g is easy to implement
   because it closely resembles standard YMODEM.

 o WXMODEM, SEAlink, and MEGAlink have applied a subset of ZMODEM's
   techniques to "Classic XMODEM" to improve upon their suppliers'
   previous offerings.  They provide good performance under ideal
   conditions.

Another XMODEM "extension" is protocol cheating, such as Omen Technology's
OverThruster(TM) and OverThruster II(TM).  These improve XMODEM throughput
under some conditions by compromising error recovery.

The ZMODEM Protocol corrects the weaknesses described above while
maintaining as much of XMODEM/CRC's simplicity and prior art as possible.



3.  ZMODEM Protocol Design Criteria

The design of a file transfer protocol is an engineering compromise
between conflicting requirements:

3.1  Ease of Use

 o ZMODEM allows either program to initiate file transfers, passing
   commands and/or modifiers to the other program.

 o File names need be entered only once.

 o Menu selections are supported.




Chapter 3	      Rev 10-27-87  Typeset 10-27-87			 4







Chapter 3		     ZMODEM Protocol				 5



 o Wild Card names may be used with batch transfers.

 o Minimum keystrokes required to initiate transfers.

 o ZRQINIT frame sent by sending program can trigger automatic downloads.

 o ZMODEM can step down to YMODEM if the other end does not support
   ZMODEM.[1]

3.2  Throughput

All file transfer protocols make tradeoffs between throughput,
reliability, universality, and complexity according to the technology and
knowledge base available to their designers.

In the design of ZMODEM, three applications deserve special attention.

  o Network applications with significant delays (relative to character
    transmission time) and low error rate

  o Timesharing and buffered modem applications with significant delays
    and throughput that is quickly degraded by reverse channel traffic.
    ZMODEM's economy of reverse channel bandwidth allows modems that
    dynamically partition bandwidth between the two directions to operate
    at optimal speeds.  Special ZMODEM features allow simple, efficient
    implementation on a wide variety of timesharing hosts.

  o Direct modem to modem communications with high error rate

Unlike Sliding Windows Kermit, ZMODEM is not optimized for optimum
throughput when error rate and delays are both high.  This tradeoff
markedly reduces code complexity and memory requirements.  ZMODEM
generally provides faster error recovery than network compatible XMODEM
implementations.

In the absence of network delays, rapid error recovery is possible, much
faster than MEGAlink and network compatible versions of YMODEM and XMODEM.

File transfers begin immediately regardless of which program is started
first, without the 10 second delay associated with XMODEM.







__________

 1. Provided the transmission medium accommodates X/YMODEM.




Chapter 3	      Rev 10-27-87  Typeset 10-27-87			 5







Chapter 3		     ZMODEM Protocol				 6



3.3  Integrity and Robustness

Once a ZMODEM session is begun, all transactions are protected with 16 or
32 bit CRC.[2] Complex proprietary techniques such as Cybernetic Data
Recovery(TM)[3] are not needed for reliable transfers.

An optional 32-bit CRC used as the frame check sequence in ADCCP (ANSI
X3.66, also known as FIPS PUB 71 and FED-STD-1003, the U.S. versions of
CCITT's X.25) is used when available.  The 32 bit CRC reduces undetected
errors by at least five orders of magnitude when properly applied (-1
preset, inversion).

A security challenge mechanism guards against "Trojan Horse" messages
written to mimic legitimate command or file downloads.

3.4  Ease of Implementation

ZMODEM accommodates a wide variety of systems:

 o Microcomputers that cannot overlap disk and serial i/o

 o Microcomputers that cannot overlap serial send and receive

 o Computers and/or networks requiring XON/XOFF flow control

 o Computers that cannot check the serial input queue for the presence of
   data without having to wait for the data to arrive.

Although ZMODEM provides "hooks" for multiple "threads", ZMODEM is not
intended to replace link level protocols such as X.25.

ZMODEM accommodates network and timesharing system delays by continuously
transmitting data unless the receiver interrupts the sender to request
retransmission of garbled data.  ZMODEM in effect uses the entire file as
a window.[4] Using the entire file as a window simplifies buffer
management, avoiding the window overrun failure modes that affect
MEGAlink, SuperKermit, and others.

ZMODEM provides a general purpose application to application file transfer
protocol which may be used directly or with with reliable link level


__________

 2. Except for the CAN-CAN-CAN-CAN-CAN abort sequence which requires five
    successive CAN characters.

 3. Unique to Professional-YAM and PowerCom

 4. Streaming strategies are discussed in coming chapters.




Chapter 3	      Rev 10-27-87  Typeset 10-27-87			 6







Chapter 3		     ZMODEM Protocol				 7



protocols such as X.25, MNP, Fastlink, etc.  When used with X.25, MNP,
Fastlink, etc., ZMODEM detects and corrects errors in the interfaces
between error controlled media and the remainder of the communications
link.

ZMODEM was developed for the public domain under a Telenet contract.  The
ZMODEM protocol descriptions and the Unix rz/sz program source code are
public domain.  No licensing, trademark, or copyright restrictions apply
to the use of the protocol, the Unix rz/sz source code and the ZMODEM
name.


4.  EVOLUTION OF ZMODEM

In early 1986, Telenet funded a project to develop an improved public
domain application to application file transfer protocol.  This protocol
would alleviate the throughput problems network customers were
experiencing with XMODEM and Kermit file transfers.

In the beginning, we thought a few modifications to XMODEM would allow
high performance over packet switched networks while preserving XMODEM's
simplicity.

The initial concept would add a block number to the ACK and NAK characters
used by XMODEM.  The resultant protocol would allow the sender to send
more than one block before waiting for a response.

But how to add the block number to XMODEM's ACK and NAK?  WXMODEM,
SEAlink, MEGAlink and some other protocols add binary byte(s) to indicate
the block number.

Pure binary was unsuitable for ZMODEM because binary code combinations
won't pass bidirectionally through some modems, networks and operating
systems.  Other operating systems may not be able to recognize something
coming back[1] unless a break signal or a system dependent code or
sequence is present.  By the time all this and other problems with the
simple ACK/NAK sequences mentioned above were corrected, XMODEM's simple
ACK and NACK characters had evolved into a real packet.  The Frog was
riveting.

Managing the window[2] was another problem.  Experience gained in
debugging The Source's SuperKermit protocol indicated a window size of
about 1000 characters was needed at 1200 bps.  High speed modems require a


__________

 1. Without stopping for a response

 2. The WINDOW is the data in transit between sender and receiver.




Chapter 4	      Rev 10-27-87  Typeset 10-27-87			 7







Chapter 4		     ZMODEM Protocol				 8



window of 20000 or more characters for full throughput.  Much of the
SuperKermit's inefficiency, complexity and debugging time centered around
its ring buffering and window management.  There had to be a better way to
get the job done.

A sore point with XMODEM and its progeny is error recovery.  More to the
point, how can the receiver determine whether the sender has responded, or
is ready to respond, to a retransmission request?  XMODEM attacks the
problem by throwing away characters until a certain period of silence.
Too short a time allows a spurious pause in output (network or timesharing
congestion) to masquerade as error recovery.  Too long a timeout
devastates throughput, and allows a noisy line to lock up the protocol.
SuperKermit solves the problem with a distinct start of packet character
(SOH).  WXMODEM and ZMODEM use unique character sequences to delineate the
start of frames.  SEAlink and MEGAlink do not address this problem.

A further error recovery problem arises in streaming protocols.  How does
the receiver know when (or if) the sender has recognized its error signal?
Is the next packet the correct response to the error signal?  Is it
something left over "in the queue"?  Or is this new subpacket one of many
that will have to be discarded because the sender did not receive the
error signal?  How long should this continue before sending another error
signal?  How can the protocol prevent this from degenerating into an
argument about mixed signals?

SuperKermit uses selective retransmission, so it can accept any good
packet it receives.  Each time the SuperKermit receiver gets a data
packet, it must decide which outstanding packet (if any) it "wants most"
to receive, and asks for that one.  In practice, complex software "hacks"
are needed to attain acceptable robustness.[3]

For ZMODEM, we decided to forgo the complexity of SuperKermit's packet
assembly scheme and its associated buffer management logic and memory
requirements.

Another sore point with XMODEM and WXMODEM is the garbage added to files.
This was acceptable with old CP/M files which had no exact length, but not
with modern systems such as DOS and Unix.  YMODEM uses file length
information transmitted in the header block to trim the output file, but
this causes data loss when transferring files that grow during a transfer.
In some cases, the file length may be unknown, as when data is obtained
from a process.  Variable length data subpackets solve both of these


__________

 3. For example, when SuperKermit encounters certain errors, the wndesr
    function is called to determine the next block to request.  A burst of
    errors generates several wasteful requests to retransmit the same
    block.




Chapter 4	      Rev 10-27-87  Typeset 10-27-87			 8







Chapter 4		     ZMODEM Protocol				 9



problems.

Since some characters had to be escaped anyway, there wasn't any point
wasting bytes to fill out a fixed packet length or to specify a variable
packet length.  In ZMODEM, the length of data subpackets is denoted by
ending each subpacket with an escape sequence similar to BISYNC and HDLC.

The end result is a ZMOEM header containing a "frame type", four bytes of
supervisory information, and its own CRC.  Data frames consist of a header
followed by 1 or more data subpackets.  In the absence of transmission
errors, an entire file can be sent in one data frame.

Since the sending system may be sensitive to numerous control characters
or strip parity in the reverse data path, all of the headers sent by the
receiver are sent in hex.  A common lower level routine receives all
headers, allowing the main program logic to deal with headers and data
subpackets as objects.

With equivalent binary (efficient) and hex (application friendly) frames,
the sending program can send an "invitation to receive" sequence to
activate the receiver without crashing the remote application with
unexpected control characters.

Going "back to scratch" in the protocol design presents an opportunity to
steal good ideas from many sources and to add a few new ones.

From Kermit and UUCP comes the concept of an initial dialog to exchange
system parameters.

ZMODEM generalizes Compuserve B Protocol's host controlled transfers to
single command AutoDownload and command downloading.  A Security Challenge
discourages password hackers and Trojan Horse authors from abusing
ZMODEM's power.

We were also keen to the pain and $uffering of legions of
telecommunicators whose file transfers have been ruined by communications
and timesharing faults.  ZMODEM's file transfer recovery and advanced file
management are dedicated to these kindred comrades.

After ZMODEM had been operational a short time, Earl Hall pointed out the
obvious: ZMODEM's user friendly AutoDownload was almost useless if the
user must assign transfer options to each of the sending and receiving
programs.  Now, transfer options may be specified to/by the sending
program, which passes them to the receiving program in the ZFILE header.










Chapter 5	      Rev 10-27-87  Typeset 10-27-87			 9







Chapter 5		     ZMODEM Protocol				10



5.  ROSETTA STONE

Here are some definitions which reflect current vernacular in the computer
media.  The attempt here is identify the file transfer protocol rather
than specific programs.

FRAME	A ZMODEM frame consists of a header and 0 or more data subpackets.

XMODEM  refers to the original 1977 file transfer etiquette introduced by
	Ward Christensen's MODEM2 program.  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's
	Group" and "TERM II FTP 3".  This protocol is supported by most
	communications programs because it is easy to implement.

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

XMODEM-1k Refers to XMODEM-CRC with optional 1024 byte blocks.

YMODEM  refers to the XMODEM/CRC protocol with batch transmission and
	optional 1024 byte blocks as described in YMODEM.DOC.[1]


6.  ZMODEM REQUIREMENTS

ZMODEM requires an 8 bit transfer medium.[1] ZMODEM escapes network
control characters to allow operation with packet switched networks.  In
general, ZMODEM operates over any path that supports XMODEM, and over many
that don't.

To support full streaming,[2] the transmission path should either assert
flow control or pass full speed transmission without loss of data.
Otherwise the ZMODEM sender must manage the window size.

6.1  File Contents

6.1.1  Binary Files
ZMODEM places no constraints on the information content of binary files,
except that the number of bits in the file must be a multiple of 8.



__________

 1. Available on TeleGodzilla as part of YZMODEM.ZOO

 1. The ZMODEM design allows encoded packets for less transparent media.

 2. With XOFF and XON, or out of band flow control such as X.25 or CTS




Chapter 6	      Rev 10-27-87  Typeset 10-27-87			10







Chapter 6		     ZMODEM Protocol				11



6.1.2  Text Files
Since ZMODEM is used to transfer files between different types of computer
systems, text files must meet minimum requirements if they are to be
readable on a wide variety of systems and environments.

Text lines consist of printing ASCII characters, spaces, tabs, and
backspaces.

6.1.2.1  ASCII End of Line
The ASCII code definition allows text lines terminated by a CR/LF (015,
012) sequence, or by a NL (012) character.  Lines logically terminated by
a lone CR (013) are not ASCII text.

A CR (013) without a linefeed implies overprinting, and is not acceptable
as a logical line separator.  Overprinted lines should print all important
characters in the last pass to allow CRT displays to display meaningful
text.  Overstruck characters may be generated by backspacing or by
overprinting the line with CR (015) not followed by LF.

Overstruck characters generated with backspaces should be sent with the
most important character last to accommodate CRT displays that cannot
overstrike.  The sending program may use the ZCNL bit to force the
receiving program to convert the received end of line to its local end of
line convention.[3]






















__________

 3. Files that have been translated in such a way as to modify their
    length cannot be updated with the ZCRECOV Conversion Option.




Chapter 6	      Rev 10-27-87  Typeset 10-27-87			11







Chapter 6		     ZMODEM Protocol				12



7.  ZMODEM BASICS

7.1  Packetization

ZMODEM frames differ somewhat from XMODEM blocks.  XMODEM blocks are not
used for the following reasons:

 o Block numbers are limited to 256

 o No provision for variable length blocks

 o Line hits corrupt protocol signals, causing failed file transfers.  In
   particular, modem errors sometimes generate false block numbers, false
   EOTs and false ACKs.  False ACKs are the most troublesome as they cause
   the sender to lose synchronization with the receiver.

   State of the art programs such as Professional-YAM and ZCOMM overcome
   some of these weaknesses with clever proprietary code, but a stronger
   protocol is desired.

 o It is difficult to determine the beginning and ends of XMODEM blocks
   when line hits cause a loss of synchronization.  This precludes rapid
   error recovery.

7.2  Link Escape Encoding

ZMODEM achieves data transparency by extending the 8 bit character set
(256 codes) with escape sequences based on the ZMODEM data link escape
character ZDLE.[1]

Link Escape coding permits variable length data subpackets without the
overhead of a separate byte count.  It allows the beginning of frames to
be detected without special timing techniques, facilitating rapid error
recovery.

Link Escape coding does add some overhead.  The worst case, a file
consisting entirely of escaped characters, would incur a 50% overhead.

The ZDLE character is special.  ZDLE represents a control sequence of some
sort.  If a ZDLE character appears in binary data, it is prefixed with
ZDLE, then sent as ZDLEE.

The value for ZDLE is octal 030 (ASCII CAN).  This particular value was
chosen to allow a string of 5 consecutive CAN characters to abort a ZMODEM


__________

 1. This and other constants are defined in the zmodem.h include file.
    Please note that constants with a leading 0 are octal constants in C.




Chapter 7	      Rev 10-27-87  Typeset 10-27-87			12







Chapter 7		     ZMODEM Protocol				13



session, compatible with YMODEM session abort.

Since CAN is not used in normal terminal operations, interactive
applications and communications programs can monitor the data flow for
ZDLE.  The following characters can be scanned to detect the ZRQINIT
header, the invitation to automatically download commands or files.

Receipt of five successive CAN characters will abort a ZMODEM session.
Eight CAN characters are sent.

The receiving program decodes any sequence of ZDLE followed by a byte with
bit 6 set and bit 5 reset (upper case letter, either parity) to the
equivalent control character by inverting bit 6.  This allows the
transmitter to escape any control character that cannot be sent by the
communications medium.  In addition, the receiver recognizes escapes for
0177 and 0377 should these characters need to be escaped.

ZMODEM software escapes ZDLE, 020, 0220, 021, 0221, 023, and 0223.  If
preceded by 0100 or 0300 (@), 015 and 0215 are also escaped to protect the
Telenet command escape CR-@-CR.  The receiver ignores 021, 0221, 023, and
0223 characters in the data stream.

The ZMODEM routines in zm.c accept an option to escape all control
characters, to allow operation with less transparent networks.  This
option can be given to either the sending or receiving program.

7.3  Header

All ZMODEM frames begin with a header which may be sent in binary or HEX
form.  ZMODEM uses a single routine to recognize binary and hex headers.
Either form of the header contains the same raw information:

 o A type byte[2] [3]

 o Four bytes of data indicating flags and/or numeric quantities depending
   on the frame type







__________

 2. The frame types are cardinal numbers beginning with 0 to minimize
    state transition table memory requirements.

 3. Future extensions to ZMODEM may use the high order bits of the type
    byte to indicate thread selection.




Chapter 7	      Rev 10-27-87  Typeset 10-27-87			13







Chapter 7		     ZMODEM Protocol				14



		   Figure 1.  Order of Bytes in Header

		   TYPE:  frame type
		   F0: Flags least significant byte
		   P0: file Position least significant
		   P3: file Position most significant

			   TYPE  F3 F2 F1 F0
			   -------------------
			   TYPE  P0 P1 P2 P3

7.3.1  16 Bit CRC Binary Header
A binary header is sent by the sending program to the receiving program.
ZDLE encoding accommodates XON/XOFF flow control.

A binary header begins with the sequence ZPAD, ZDLE, ZBIN.

The frame type byte is ZDLE encoded.

The four position/flags bytes are ZDLE encoded.

A two byte CRC of the frame type and position/flag bytes is ZDLE encoded.

0 or more binary data subpackets with 16 bit CRC will follow depending on
the frame type.

The function zsbhdr transmits a binary header.  The function zgethdr
receives a binary or hex header.

		   Figure 2.  16 Bit CRC Binary Header
	    * ZDLE A TYPE F3/P0 F2/P1 F1/P2 F0/P3 CRC-1 CRC-2


7.3.2  32 Bit CRC Binary Header
A "32 bit CRC" Binary header is similar to a Binary Header, except the
ZBIN (A) character is replaced by a ZBIN32 (C) character, and four
characters of CRC are sent.  0 or more binary data subpackets with 32 bit
CRC will follow depending on the frame type.

The common variable Txfcs32 may be set TRUE for 32 bit CRC iff the
receiver indicates the capability with the CANFC32 bit.  The zgethdr,
zsdata and zrdata functions automatically adjust to the type of Frame
Check Sequence being used.
		   Figure 3.  32 Bit CRC Binary Header
      * ZDLE C TYPE F3/P0 F2/P1 F1/P2 F0/P3 CRC-1 CRC-2 CRC-3 CRC-4


7.3.3  HEX Header
The receiver sends responses in hex headers.  The sender also uses hex
headers when they are not followed by binary data subpackets.




Chapter 7	      Rev 10-27-87  Typeset 10-27-87			14







Chapter 7		     ZMODEM Protocol				15



Hex encoding protects the reverse channel from random control characters.
The hex header receiving routine ignores parity.

Use of Kermit style encoding for control and paritied characters was
considered and rejected because of increased possibility of interacting
with some timesharing systems' line edit functions.  Use of HEX headers
from the receiving program allows control characters to be used to
interrupt the sender when errors are detected.  A HEX header may be used
in place of a binary header wherever convenient.  If a data packet follows
a HEX header, it is protected with CRC-16.

A hex header begins with the sequence ZPAD, ZPAD, ZDLE, ZHEX.  The zgethdr
routine synchronizes with the ZPAD-ZDLE sequence.  The extra ZPAD
character allows the sending program to detect an asynchronous header
(indicating an error condition) and then call zgethdr to receive the
header.

The type byte, the four position/flag bytes, and the 16 bit CRC thereof
are sent in hex using the character set 01234567890abcdef.  Upper case hex
digits are not allowed; they false trigger XMODEM and YMODEM programs.
Since this form of hex encoding detects many patterns of errors,
especially missing characters, a hex header with 32 bit CRC has not been
defined.

A carriage return and line feed are sent with HEX headers.  The receive
routine expects to see at least one of these characters, two if the first
is CR.  The CR/LF aids debugging from printouts, and helps overcome
certain operating system related problems.

An XON character is appended to all HEX packets except ZACK and ZFIN.  The
XON releases the sender from spurious XOFF flow control characters
generated by line noise, a common occurrence.  XON is not sent after ZACK
headers to protect flow control in streaming situations.  XON is not sent
after a ZFIN header to allow clean session cleanup.

0 or more data subpackets will follow depending on the frame type.

The function zshhdr sends a hex header.

			  Figure 4.  HEX Header

      * * ZDLE B TYPE F3/P0 F2/P1 F1/P2 F0/P3 CRC-1 CRC-2 CR LF XON

(TYPE, F3...F0, CRC-1, and CRC-2 are each sent as two hex digits.)










Chapter 7	      Rev 10-27-87  Typeset 10-27-87			15







Chapter 7		     ZMODEM Protocol				16



7.4  Binary Data Subpackets

Binary data subpackets immediately follow the associated binary header
packet.  A binary data packet contains 0 to 1024 bytes of data.
Recommended length values are 256 bytes below 2400 bps, 512 at 2400 bps,
and 1024 above 4800 bps or when the data link is known to be relatively
error free.[4]

No padding is used with binary data subpackets.  The data bytes are ZDLE
encoded and transmitted.  A ZDLE and frameend are then sent, followed by
two or four ZDLE encoded CRC bytes.  The CRC accumulates the data bytes
and frameend.

The function zsdata sends a data subpacket.  The function zrdata receives
a data subpacket.

7.5  ASCII Encoded Data Subpacket

The format of ASCII Encoded data subpackets is not currently specified.
These could be used for server commands, or main transfers in 7 bit
environments.


8.  PROTOCOL TRANSACTION OVERVIEW

As with the XMODEM recommendation, ZMODEM timing is receiver driven.  The
transmitter should not time out at all, except to abort the program if no
headers are received for an extended period of time, say one minute.[1]


8.1  Session Startup

To start a ZMODEM file transfer session, the sending program is called
with the names of the desired file(s) and option(s).

The sending program may send the string "rz\r" to invoke the receiving
program from a possible command mode.  The "rz" followed by carriage
return activates a ZMODEM receive program or command if it were not
already active.

The sender may then display a message intended for human consumption, such


__________

 4. Strategies for adjusting the subpacket length for optimal results
    based on real time error rates are still evolving.  Shorter subpackets
    speed error detection but increase protocol overhead slightly.

 1. Special considerations apply when sending commands.




Chapter 8	      Rev 10-27-87  Typeset 10-27-87			16







Chapter 8		     ZMODEM Protocol				17



as a list of the files requested, etc.

Then the sender may send a ZRQINIT header.  The ZRQINIT header causes a
previously started receive program to send its ZRINIT header without
delay.

In an interactive or conversational mode, the receiving application may
monitor the data stream for ZDLE.  The following characters may be scanned
for B00 indicating a ZRQINIT header, a command to download a command or
data.

The sending program awaits a command from the receiving program to start
file transfers.  If a "C", "G", or NAK is received, an XMODEM or YMODEM
file transfer is indicated, and file transfer(s) use the YMODEM protocol.
Note: With ZMODEM and YMODEM, the sending program provides the file name,
but not with XMODEM.

In case of garbled data, the sending program can repeat the invitation to
receive a number of times until a session starts.

When the ZMODEM receive program starts, it immediately sends a ZRINIT
header to initiate ZMODEM file transfers, or a ZCHALLENGE header to verify
the sending program.  The receive program resends its header at response
time (default 10 second) intervals for a suitable period of time (40
seconds total) before falling back to YMODEM protocol.

If the receiving program receives a ZRQINIT header, it resends the ZRINIT
header.  If the sending program receives the ZCHALLENGE header, it places
the data in ZP0...ZP3 in an answering ZACK header.

If the receiving program receives a ZRINIT header, it is an echo
indicating that the sending program is not operational.

Eventually the sending program correctly receives the ZRINIT header.

The sender may then send an optional ZSINIT frame to define the receiving
program's Attn sequence, or to specify complete control character
escaping.[2]

If the ZSINIT header specifies ESCCTL or ESC8, a HEX header is used, and
the receiver activates the specified ESC modes before reading the
following data subpacket.

The receiver sends a ZACK header in response, optionally containing the


__________

 2. If the receiver specifies the same or higher level of escaping, the
    ZSINIT frame need not be sent unless an Attn sequence is needed.




Chapter 8	      Rev 10-27-87  Typeset 10-27-87			17







Chapter 8		     ZMODEM Protocol				18



serial number of the receiving program, or 0.

8.2  File Transmission

The sender then sends a ZFILE header with ZMODEM Conversion, Management,
and Transport options[3] followed by a ZCRCW data subpacket containing the
file name, file length, modification date, and other information identical
to that used by YMODEM Batch.

The receiver examines the file name, length, and date information provided
by the sender in the context of the specified transfer options, the
current state of its file system(s), and local security requirements.  The
receiving program should insure the pathname and options are compatible
with its operating environment and local security requirements.

The receiver may respond with a ZSKIP header, which makes the sender
proceed to the next file (if any) in the batch.

       If the receiver has a file with the same name and length,
       it may respond with a ZCRC header, which requires the
       sender to perform a 32 bit CRC on the file and transmit the
       complement of the CRC in a ZCRC header.[4] The receiver
       uses this information to determine whether to accept the
       file or skip it.  This sequence is triggered by the ZMCRC
       Management Option.

A ZRPOS header from the receiver initiates transmission of the file data
starting at the offset in the file specified in the ZRPOS header.
Normally the receiver specifies the data transfer to begin begin at
offset 0 in the file.
       The receiver may start the transfer further down in the
       file.  This allows a file transfer interrupted by a loss
       or carrier or system crash to be completed on the next
       connection without requiring the entire file to be
       retransmitted.[5] If downloading a file from a timesharing
       system that becomes sluggish, the transfer can be
       interrupted and resumed later with no loss of data.

The sender sends a ZDATA binary header (with file position) followed by
one or more data subpackets.



__________

 3. See below, under ZFILE header type.

 4. The crc is initialized to 0xFFFFFFFF.

 5. This does not apply to files that have been translated.




Chapter 8	      Rev 10-27-87  Typeset 10-27-87			18







Chapter 8		     ZMODEM Protocol				19



The receiver compares the file position in the ZDATA header with the
number of characters successfully received to the file.  If they do not
agree, a ZRPOS error response is generated to force the sender to the
right position within the file.[6]

A data subpacket terminated by ZCRCG and CRC does not elicit a response
unless an error is detected; more data subpacket(s) follow immediately.

       ZCRCQ data subpackets expect a ZACK response with the
       receiver's file offset if no error, otherwise a ZRPOS
       response with the last good file offset.  Another data
       subpacket continues immediately.  ZCRCQ subpackets are
       not used if the receiver does not indicate FDX ability
       with the CANFDX bit.

ZCRCW data subpackets expect a response before the next frame is sent.
If the receiver does not indicate overlapped I/O capability with the
CANOVIO bit, or sets a buffer size, the sender uses the ZCRCW to allow
the receiver to write its buffer before sending more data.

       A zero length data frame may be used as an idle
       subpacket to prevent the receiver from timing out in
       case data is not immediately available to the sender.

In the absence of fatal error, the sender eventually encounters end of
file.  If the end of file is encountered within a frame, the frame is
closed with a ZCRCE data subpacket which does not elicit a response
except in case of error.

The sender sends a ZEOF header with the file ending offset equal to
the number of characters in the file.  The receiver compares this
number with the number of characters received.  If the receiver has
received all of the file, it closes the file.  If the file close was
satisfactory, the receiver responds with ZRINIT.  If the receiver has
not received all the bytes of the file, the receiver ignores the ZEOF
because a new ZDATA is coming.  If the receiver cannot properly close
the file, a ZFERR header is sent.

       After all files are processed, any further protocol
       errors should not prevent the sending program from
       returning with a success status.





__________

 6. If the ZMSPARS option is used, the receiver instead seeks to the
    position given in the ZDATA header.




Chapter 8	      Rev 10-27-87  Typeset 10-27-87			19







Chapter 8		     ZMODEM Protocol				20



8.3  Session Cleanup

The sender closes the session with a ZFIN header.  The receiver
acknowledges this with its own ZFIN header.

When the sender receives the acknowledging header, it sends two
characters, "OO" (Over and Out) and exits to the operating system or
application that invoked it.  The receiver waits briefly for the "O"
characters, then exits whether they were received or not.

8.4  Session Abort Sequence

If the receiver is receiving data in streaming mode, the Attn
sequence is executed to interrupt data transmission before the Cancel
sequence is sent.  The Cancel sequence consists of eight CAN
characters and ten backspace characters.  ZMODEM only requires five
Cancel characters, the other three are "insurance".

The trailing backspace characters attempt to erase the effects of the
CAN characters if they are received by a command interpreter.

       static char canistr[] = {
	24,24,24,24,24,24,24,24,8,8,8,8,8,8,8,8,8,8,0
       };






























Chapter 8	      Rev 10-27-87  Typeset 10-27-87			20







Chapter 8		     ZMODEM Protocol				21



9.  STREAMING TECHNIQUES / ERROR RECOVERY

It is a fact of life that no single method of streaming is applicable
to a majority of today's computing and telecommunications
environments.  ZMODEM provides several data streaming methods
selected according to the limitations of the sending environment,
receiving environment, and transmission channel(s).


9.1  Full Streaming with Sampling

If the receiver can overlap serial I/O with disk I/O, and if the
sender can sample the reverse channel for the presence of data
without having to wait, full streaming can be used with no Attn
sequence required.  The sender begins data transmission with a ZDATA
header and continuous ZCRCG data subpackets.  When the receiver
detects an error, it executes the Attn sequence and then sends a
ZRPOS header with the correct position within the file.

At the end of each transmitted data subpacket, the sender checks for
the presence of an error header from the receiver.  To do this, the
sender samples the reverse data stream for the presence of either a
ZPAD or CAN character.[1] Flow control characters (if present) are
acted upon.

Other characters (indicating line noise) increment a counter which is
reset whenever the sender waits for a header from the receiver.  If
the counter overflows, the sender sends the next data subpacket as
ZCRCW, and waits for a response.

ZPAD indicates some sort of error header from the receiver.  A CAN
suggests the user is attempting to "stop the bubble machine" by
keyboarding CAN characters.  If one of these characters is seen, an
empty ZCRCE data subpacket is sent.  Normally, the receiver will have
sent an ZRPOS or other error header, which will force the sender to
resume transmission at a different address, or take other action.  In
the unlikely event the ZPAD or CAN character was spurious, the
receiver will time out and send a ZRPOS header.[2]

Then the receiver's response header is read and acted upon.[3]


__________

 1. The call to rdchk() in sz.c performs this function.

 2. The obvious choice of ZCRCW packet, which would trigger an ZACK from
    the receiver, is not used because multiple in transit frames could
    result if the channel has a long propagation delay.

 3. The call to getinsync() in sz.c performs this function.



Chapter 9	      Rev 10-27-87  Typeset 10-27-87			21







Chapter 9		     ZMODEM Protocol				22



A ZRPOS header resets the sender's file offset to the correct
position.  If possible, the sender should purge its output buffers
and/or networks of all unprocessed output data, to minimize the
amount of unwanted data the receiver must discard before receiving
data starting at the correct file offset.  The next transmitted data
frame should be a ZCRCW frame followed by a wait to guarantee
complete flushing of the network's memory.

If the receiver gets a ZACK header with an address that disagrees
with the sender address, it is ignored, and the sender waits for
another header.  A ZFIN, ZABORT, or TIMEOUT terminates the session; a
ZSKIP terminates the processing of this file.

The reverse channel is then sampled for the presence of another
header from the receiver.[4] if one is detected, the getinsync()
function is again called to read another error header.  Otherwise,
transmission resumes at the (possibly reset) file offset with a ZDATA
header followed by data subpackets.


9.1.1  Window Management
When sending data through a network, some nodes of the network store
data while it is transferred to the receiver.  7000 bytes and more of
transient storage have been observed.  Such a large amount of storage
causes the transmitter to "get ahead" of the reciever.  This can be
fatal with MEGAlink and other protocols that depend on timely
notification of errors from the receiver.  This condition is not
fatal with ZMODEM, but it does slow error recovery.

To manage the window size, the sending program uses ZCRCQ data
subpackets to trigger ZACK headers from the receiver.  The returning
ZACK headers inform the sender of the receiver's progress.  When the
window size (current transmitter file offset - last reported receiver
file offset) exceeds a specified value, the sender waits for a
ZACK[5] packet with a receiver file offset that reduces the window
size.

Unix sz versions beginning with May 9 1987 control the window size
with the "-w N" option, where N is the maximum window size.  Pro-YAM,
ZCOMM and DSZ versions beginning with May 9 1987 control the window
size with "zmodem pwN".  This is compatible with previous versions of
these programs.[6]


__________

 4. If sampling is possible.

 5. ZRPOS and other error packets are handled normally.

 6. When used with modems or networks that simultaneously assert flow



Chapter 9	      Rev 10-27-87  Typeset 10-27-87			22







Chapter 9		     ZMODEM Protocol				23



9.2  Full Streaming with Reverse Interrupt

The above method cannot be used if the reverse data stream cannot be
sampled without entering an I/O wait.  An alternate method is to
instruct the receiver to interrupt the sending program when an error
is detected.

The receiver can interrupt the sender with a control character, break
signal, or combination thereof, as specified in the Attn sequence.
After executing the Attn sequence, the receiver sends a hex ZRPOS
header to force the sender to resend the lost data.

When the sending program responds to this interrupt, it reads a HEX
header (normally ZRPOS) from the receiver and takes the action
described in the previous section.  The Unix sz.c program uses a
setjmp/longjmp call to catch the interrupt generated by the Attn
sequence.  Catching the interrupt activates the getinsync() function
to read the receiver's error header and take appropriate action.

When compiled for standard SYSTEM III/V Unix, sz.c uses an Attn
sequence of Ctrl-C followed by a 1 second pause to interrupt the
sender, then give the sender (Unix) time to prepare for the
receiver's error header.


9.3  Full Streaming with Sliding Window

If none of the above methods is applicable, hope is not yet lost.  If
the sender can buffer responses from the receiver, the sender can use
ZCRCQ data subpackets to get ACKs from the receiver without
interrupting the transmission of data.  After a sufficient number of
ZCRCQ data subpackets have been sent, the sender can read one of the
headers that should have arrived in its receive interrupt buffer.

A problem with this method is the possibility of wasting an excessive
amount of time responding to the receiver's error header.  It may be
possible to program the receiver's Attn sequence to flush the
sender's interrupt buffer before sending the ZRPOS header.







__________________________________________________________________________

    control with XON and XOFF characters and pass XON characters that
    violate flow control, the receiving program should have a revision
    date of May 9 or later.




Chapter 9	      Rev 10-27-87  Typeset 10-27-87			23







Chapter 9		     ZMODEM Protocol				24



9.4  Full Streaming over Error Free Channels

File transfer protocols predicated on the existence of an error free
end to end communications channel have been proposed from time to
time.  Such channels have proven to be more readily available in
theory than in actuality.  The frequency of undetected errors
increases when modem scramblers have more bits than the error
detecting CRC.

A ZMODEM sender assuming an error free channel with end to end flow
control can send the entire file in one frame without any checking of
the reverse stream.  If this channel is completely transparent, only
ZDLE need be escaped.  The resulting protocol overhead for average
long files is less than one per cent.[7]

9.5  Segmented Streaming

If the receiver cannot overlap serial and disk I/O, it uses the
ZRINIT frame to specify a buffer length which the sender will not
overflow.  The sending program sends a ZCRCW data subpacket and waits
for a ZACK header before sending the next segment of the file.

If the sending program supports reverse data stream sampling or
interrupt, error recovery will be faster (on average) than a protocol
(such as YMODEM) that sends large blocks.

A sufficiently large receiving buffer allows throughput to closely
approach that of full streaming.  For example, 16kb segmented
streaming adds about 3 per cent to full streaming ZMODEM file
transfer times when the round trip delay is five seconds.


10.  ATTENTION SEQUENCE

The receiving program sends the Attn sequence whenever it detects an
error and needs to interrupt the sending program.

The default Attn string value is empty (no Attn sequence).  The
receiving program resets Attn to the empty default before each
transfer session.

The sender specifies the Attn sequence in its optional ZSINIT frame.
The Attn string is terminated with a null.



__________

 7. One in 256 for escaping ZDLE, about two (four if 32 bit CRC is used)
    in 1024 for data subpacket CRC's




Chapter 10	      Rev 10-27-87  Typeset 10-27-87			24







Chapter 10		     ZMODEM Protocol				25



Two meta-characters perform special functions:

   o \335 (octal) Send a break signal

   o \336 (octal) Pause one second


11.  FRAME TYPES

The numeric values for the values shown in boldface are given in
zmodem.h.  Unused bits and unused bytes in the header (ZP0...ZP3) are
set to 0.

11.1  ZRQINIT

Sent by the sending program, to trigger the receiving program to send
its ZRINIT header.  This avoids the aggravating startup delay
associated with XMODEM and Kermit transfers.  The sending program may
repeat the receive invitation (including ZRQINIT) if a response is
not obtained at first.

ZF0 contains ZCOMMAND if the program is attempting to send a command,
0 otherwise.

11.2  ZRINIT

Sent by the receiving program.  ZF0 and ZF1 contain the  bitwise or
of the receiver capability flags:
#define CANCRY	    8	/* Receiver can decrypt */
#define CANFDX	   01	/* Rx can send and receive true FDX */
#define CANOVIO    02	/* Rx can receive data during disk I/O */
#define CANBRK	   04	/* Rx can send a break signal */
#define CANCRY	  010	/* Receiver can decrypt */
#define CANLZW	  020	/* Receiver can uncompress */
#define CANFC32   040	/* Receiver can use 32 bit Frame Check */
#define ESCCTL	 0100	/* Receiver expects ctl chars to be escaped
*/
#define ESC8	 0200	/* Receiver expects 8th bit to be escaped */

ZP0 and ZP1 contain the size of the receiver's buffer in bytes, or 0
if nonstop I/O is allowed.

11.3  ZSINIT

The Sender sends flags followed by a binary data subpacket terminated
with ZCRCW.

/* Bit Masks for ZSINIT flags byte ZF0 */
#define TESCCTL 0100   /* Transmitter expects ctl chars to be escaped
*/
#define TESC8	0200   /* Transmitter expects 8th bit to be escaped



Chapter 11	      Rev 10-27-87  Typeset 10-27-87			25







Chapter 11		     ZMODEM Protocol				26



*/

The data subpacket contains the null terminated Attn sequence,
maximum length 32 bytes including the terminating null.

11.4  ZACK

Acknowledgment to a ZSINIT frame, ZCHALLENGE header, ZCRCQ or ZCRCW
data subpacket.  ZP0 to ZP3 contain file offset.  The response to
ZCHALLENGE contains the same 32 bit number received in the ZCHALLENGE
header.

11.5  ZFILE

This frame denotes the beginning of a file transmission attempt.
ZF0, ZF1, and ZF2 may contain options.  A value of 0 in each of these
bytes implies no special treatment.  Options specified to the
receiver override options specified to the sender with the exception
of ZCBIN which overrides any other Conversion Option given to the
sender or receiver.


11.5.1  ZF0: Conversion Option
If the receiver does not recognize the Conversion Option, an
application dependent default conversion may apply.

ZCBIN "Binary" transfer - inhibit conversion unconditionally

ZCNL Convert received end of line to local end of line
     convention.  The supported end of line conventions are
     CR/LF (most ASCII based operating systems except Unix
     and Macintosh), and NL (Unix).  Either of these two end
     of line conventions meet the permissible ASCII
     definitions for Carriage Return and Line Feed/New Line.
     Neither the ASCII code nor ZMODEM ZCNL encompass lines
     separated only by carriage returns.  Other processing
     appropriate to ASCII text files and the local operating
     system may also be applied by the receiver.[1]

ZCRECOV Recover/Resume interrupted file transfer.  ZCREVOV is
     also useful for updating a remote copy of a file that
     grows without resending of old data.  If the destination
     file exists and is no longer than the source, append to
     the destination file and start transfer at the offset
     corresponding to the receiver's end of file.  This


__________

 1. Filtering RUBOUT, NULL, Ctrl-Z, etc.




Chapter 11	      Rev 10-27-87  Typeset 10-27-87			26







Chapter 11		     ZMODEM Protocol				27



     option does not apply if the source file is shorter.
     Files that have been converted (e.g., ZCNL) or subject
     to a single ended Transport Option cannot have their
     transfers recovered.

11.5.2  ZF1: Management Option
If the receiver does not recognize the Management Option, the
file should be transferred normally.

The ZMSKNOLOC bit instructs the receiver to bypass the
current file if the rec
		... NOTE: Some text is missing here ....
ZMCLOB Replace existing destination file (if any).

ZMDIFF Transfer file if destination file absent.  Otherwise,
     transfer file overwriting destination if files have
     different lengths or dates.

ZMPROT Protect destination file by transferring file only if
     the destination file is absent.

ZMNEW Transfer file if destination file absent.  Otherwise,
     transfer file overwriting destination if the source file
     is newer.

11.5.3  ZF2: Transport Option
If the receiver does not implement the particular transport
option, the file is copied without conversion for later
processing.

ZTLZW Lempel-Ziv compression.  Transmitted data will be
     identical to that produced by compress 4.0 operating on
     a computer with VAX byte ordering, using 12 bit
     encoding.

ZTCRYPT Encryption.  An initial null terminated string
     identifies the key.  Details to be determined.



Chapter 11	      Rev 10-27-87  Typeset 10-27-87			27







Chapter 11		     ZMODEM Protocol				28



ZTRLE Run Length encoding, Details to be determined.

A ZCRCW data subpacket follows with file name, file length,
modification date, and other information described in a later
chapter.

11.5.4  ZF3: Extended Options
The Extended Options are bit encoded.

ZTSPARS Special processing for sparse files, or sender managed
     selective retransmission.  Each file segment is transmitted as
     a separate frame, where the frames are not necessarily
     contiguous.  The sender should end each segment with a ZCRCW
     data subpacket and process the expected ZACK to insure no data
     is lost.  ZTSPARS cannot be used with ZCNL.

11.6  ZSKIP

Sent by the receiver in response to ZFILE, makes the sender skip to
the next file.

11.7  ZNAK

Indicates last header was garbled.  (See also ZRPOS).

11.8  ZABORT

Sent by receiver to terminate batch file transfers when requested by
the user.  Sender responds with a ZFIN sequence.[2]

11.9  ZFIN

Sent by sending program to terminate a ZMODEM session.  Receiver
responds with its own ZFIN.

11.10  ZRPOS

Sent by receiver to force file transfer to resume at file offset
given in ZP0...ZP3.








__________

 2. Or ZCOMPL in case of server mode.




Chapter 11	      Rev 10-27-87  Typeset 10-27-87			28







Chapter 11		     ZMODEM Protocol				29



11.11  ZDATA

ZP0...ZP3 contain file offset.  One or more data subpackets follow.

11.12  ZEOF

Sender reports End of File.  ZP0...ZP3 contain the ending file
offset.

11.13  ZFERR

Error in reading or writing file, protocol equivalent to ZABORT.

11.14  ZCRC

Request (receiver) and response (sender) for file polynomial.
ZP0...ZP3 contain file polynomial.

11.15  ZCHALLENGE

Request sender to echo a random number in ZP0...ZP3 in a ZACK frame.
Sent by the receiving program to the sending program to verify that
it is connected to an operating program, and was not activated by
spurious data or a Trojan Horse message.

11.16  ZCOMPL

Request now completed.

11.17  ZCAN

This is a pseudo frame type returned by gethdr() in response to a
Session Abort sequence.

11.18  ZFREECNT

Sending program requests a ZACK frame with ZP0...ZP3 containing the
number of free bytes on the current file system.  A value of 0
represents an indefinite amount of free space.

11.19  ZCOMMAND

ZCOMMAND is sent in a binary frame.  ZF0 contains 0 or ZCACK1 (see
below).

A ZCRCW data subpacket follows, with the ASCII text command string
terminated with a NULL character.  If the command is intended to be
executed by the operating system hosting the receiving program
(e.g., "shell escape"), it must have "!" as the first character.
Otherwise the command is meant to be executed by the application
program which receives the command.



Chapter 11	      Rev 10-27-87  Typeset 10-27-87			29







Chapter 11		     ZMODEM Protocol				30



If the receiver detects an illegal or badly formed command, the
receiver immediately responds with a ZCOMPL header with an error
code in ZP0...ZP3.

If ZF0 contained ZCACK1, the receiver immediately responds with a
ZCOMPL header with 0 status.

Otherwise, the receiver responds with a ZCOMPL header when the
operation is completed.  The exit status of the completed command is
stored in ZP0...ZP3.  A 0 exit status implies nominal completion of
the command.

If the command causes a file to be transmitted, the command sender
will see a ZRQINIT frame from the other computer attempting to send
data.

The sender examines ZF0 of the received ZRQINIT header to verify it
is not an echo of its own ZRQINIT header.  It is illegal for the
sending program to command the receiving program to send a command.

If the receiver program does not implement command downloading, it
may display the command to the standard error output, then return a
ZCOMPL header.



12.  SESSION TRANSACTION EXAMPLES

12.1  A simple file transfer

A simple transaction, one file, no errors, no CHALLENGE, overlapped
I/O:

Sender	       Receiver

"rz\r"
ZRQINIT(0)
	       ZRINIT
ZFILE
	       ZRPOS
ZDATA data ...
ZEOF
	       ZRINIT
ZFIN
	       ZFIN
OO








Chapter 12	      Rev 10-27-87  Typeset 10-27-87			30







Chapter 12		     ZMODEM Protocol				31



12.2  Challenge and Command Download


Sender		    Receiver

"rz\r"
ZRQINIT(ZCOMMAND)
		    ZCHALLENGE(random-number)
ZACK(same-number)
		    ZRINIT
ZCOMMAND, ZDATA
		    (Performs Command)
		    ZCOMPL
ZFIN
		    ZFIN
OO


13.  ZFILE FRAME FILE INFORMATION

ZMODEM sends the same file information with the ZFILE frame data
that YMODEM Batch sends in its block 0.  N.B.: The pathname (file
name) field is mandatory.

Pathname The pathname (conventionally, the file name) is sent as a
     null terminated ASCII string.  This is the filename format used
     by the handle oriented MSDOS(TM) functions and C library fopen
     functions.  An assembly language example follows:
			   DB	  'foo.bar',0
     No spaces are included in the pathname.  Normally only the file
     name stem (no directory prefix) is transmitted unless the
     sender has selected YAM's f option to send the full absolute or
     relative pathname.  The source drive designator (A:, B:, etc.)
     usually is not sent.

			 Filename Considerations

	o File names should be translated to lower case unless the
	  sending system supports upper/lower case file names.  This
	  is a convenience for users of systems (such as Unix) which
	  store filenames in upper and lower case.

	o The receiver should accommodate file names in lower and
	  upper case.

	o When transmitting files between different operating
	  systems, file names must be acceptable to both the sender
	  and receiving operating systems.  If not, transformations
	  should be applied to make the file names acceptable.  If
	  the transformations are unsuccessful, a new file name may
	  be invented be the receiving program.



Chapter 13	      Rev 10-27-87  Typeset 10-27-87			31







Chapter 13		     ZMODEM Protocol				32



     If directories are included, they are delimited by /; i.e.,
     "subdir/foo" is acceptable, "subdir\foo" is not.

Length The file length and each of the succeeding fields are
     optional.[1] The length field is stored as a decimal string
     counting the number of data bytes in the file.

     The ZMODEM receiver uses the file length as an estimate only.
     It may be used to display an estimate of the transmission time,
     and may be compared with the amount of free disk space.  The
     actual length of the received file is determined by the data
     transfer.  A file may grow after transmission commences, and
     all the data will be sent.

Modification Date A single space separates the modification date
     from the file length.

     The mod date is optional, and the filename and length may be
     sent without requiring the mod date to be sent.

     The mod date is sent as an octal number giving the time the
     contents of the file were last changed measured in seconds from
     Jan 1 1970 Universal Coordinated Time (GMT).  A date of 0
     implies the modification date is unknown and should be left as
     the date the file is received.

     This standard format was chosen to eliminate ambiguities
     arising from transfers between different time zones.


File Mode A single space separates the file mode from the
     modification date.  The file mode is stored as an octal string.
     Unless the file originated from a Unix system, the file mode is
     set to 0.  rz(1) checks the file mode for the 0x8000 bit which
     indicates a Unix type regular file.  Files with the 0x8000 bit
     set are assumed to have been sent from another Unix (or
     similar) system which uses the same file conventions.  Such
     files are not translated in any way.


Serial Number A single space separates the serial number from the
     file mode.  The serial number of the transmitting program is
     stored as an octal string.  Programs which do not have a serial
     number should omit this field, or set it to 0.  The receiver's
     use of this field is optional.


__________

 1. Fields may not be skipped.




Chapter 13	      Rev 10-27-87  Typeset 10-27-87			32







Chapter 13		     ZMODEM Protocol				33



Number of Files Remaining Iff the number of files remaining is sent,
     a single space separates this field from the previous field.
     This field is coded as a decimal number, and includes the
     current file.  This field is an estimate, and incorrect values
     must not be allowed to cause loss of data.  The receiver's use
     of this field is optional.


Number of Bytes Remaining Iff the number of bytes remaining is sent,
     a single space separates this field from the previous field.
     This field is coded as a decimal number, and includes the
     current file.  This field is an estimate, and incorrect values
     must not be allowed to cause loss of data.  The receiver's use
     of this field is optional.


The file information is terminated by a null.  If only the pathname
is sent, the pathname is terminated with two nulls.  The length of
the file information subpacket, including the trailing null, must
not exceed 1024 bytes; a typical length is less than 64 bytes.


14.  PERFORMANCE RESULTS

14.1  Compatibility

Extensive testing has demonstrated ZMODEM to be compatible with
satellite links, packet switched networks, microcomputers,
minicomputers, regular and error correcting buffered modems at 75 to
19200 bps.  ZMODEM's economy of reverse channel bandwidth allows
modems that dynamically partition bandwidth between the two
directions to operate at optimal speeds.

14.2  Throughput

Between two single task PC-XT computers sending a program image on
an in house Telenet link, SuperKermit provided 72 ch/sec throughput
at 1200 baud.  YMODEM-k yielded 85 chars/sec, and ZMODEM provided
113 chars/sec.  XMODEM was not measured, but would have been much
slower based on observed network propagation delays.

Recent tests downloading large binary files to an IBM PC (4.7 mHz
V20) running YAMK 16.30 with table driven 32 bit CRC calculation
yielded a throughput of 1870 cps on a 19200 bps direct connection.

Tests with TELEBIT TrailBlazer modems have shown transfer rates
approaching 1400 characters per second for long files.  When files
are compressed, effective transfer rates of 2000 characters per
second are possible.





Chapter 14	      Rev 10-27-87  Typeset 10-27-87			33







Chapter 14		     ZMODEM Protocol				34



14.3  Error Recovery

Some tests of ZMODEM protocol error recovery performance have been
made.  A PC-AT with SCO SYS V Xenix or DOS 3.1 was connected to a PC
with DOS 2.1 either directly at 9600 bps or with unbuffered dial-up
1200 bps modems.  The ZMODEM software was configured to use 1024
byte data subpacket lengths above 2400 bps, 256 otherwise.

Because no time delays are necessary in normal file transfers, per
file negotiations are much faster than with YMODEM, the only
observed delay being the time required by the program(s) to update
logging files.

During a file transfer, a short line hit seen by the receiver
usually induces a CRC error.  The interrupt sequence is usually seen
by the sender before the next data subpacket is completely sent, and
the resultant loss of data throughput averages about half a data
subpacket per line hit.  At 1200 bps this is would be about .75
second lost per hit.  At 10-5 error rate, this would degrade
throughput by about 9 per cent.

The throughput degradation increases with increasing channel delay,
as more data subpackets in transit through the channel are discarded
when an error is detected.

A longer noise burst that affects both the receiver and the sender's
reception of the interrupt sequence usually causes the sender to
remain silent until the receiver times out in 10 seconds.  If the
round trip channel delay exceeds the receiver's 10 second timeout,
recovery from this type of error may become difficult.

Noise affecting only the sender is usually ignored, with one common
exception.  Spurious XOFF characters generated by noise stop the
sender until the receiver times out and sends an interrupt sequence
which concludes with an XON.

In summation, ZMODEM performance in the presence of errors resembles
that of X.PC and SuperKermit.  Short bursts cause minimal data
retransmission.  Long bursts (such as pulse dialing noises) often
require a timeout error to restore the flow of data.


15.  PACKET SWITCHED NETWORK CONSIDERATIONS

Flow control is necessary for printing messages and directories, and
for streaming file transfer protocols.  A non transparent flow
control is incompatible with XMODEM and YMODEM transfers.  XMODEM
and YMODEM protocols require complete transparency of all 256 8 bit
codes to operate properly.

The "best" flow control (when X.25 or hardware CTS is unavailable)



Chapter 15	      Rev 10-27-87  Typeset 10-27-87			34







Chapter 15		     ZMODEM Protocol				35



would not "eat" any characters at all.  When the PAD's buffer almost
fills up, an XOFF should be emitted.  When the buffer is no longer
nearly full, send an XON.  Otherwise, the network should neither
generate nor eat XON or XOFF control characters.

On Telenet, this can be met by setting CCIT X3 5:1 and 12:0 at both
ends of the network.  For best throughput, parameter 64 (advance
ACK) should be set to something like 4.  Packets should be forwarded
when the packet is a full 128 bytes, or after a moderate delay
(3:0,4:10,6:0).

With PC-Pursuit, it is sufficient to set parameter 5 to 1 at both
ends after one is connected to the remote modem.

	<ENTER>@<ENTER>
	set 5:1<ENTER>
	rst? 5:1<ENTER>
	cont<ENTER>

Unfortunately, many PADs do not accept the "rst?" command.

For YMODEM, PAD buffering should guarantee that a minimum of 1040
characters can be sent in a burst without loss of data or generation
of flow control characters.  Failure to provide this buffering will
generate excessive retries with YMODEM.

	     TABLE 1.  Network and Flow Control Compatibility

______________________________________________________________________________
|   Connectivity    |  Interactive|  XMODEM|  WXMODEM|  SUPERKERMIT|  ZMODEM |
|___________________|_____________|________|_________|_____________|_________|
|___________________|_____________|________|_________|_____________|_________|
|Direct Connect     |  YES	  |  YES   |  YES    |  YES	   |  YES    |
|___________________|_____________|________|_________|_____________|_________|
|Network, no FC     |  no	  |  YES   |  (4)    |  (6)	   |  YES (1)|
|___________________|_____________|________|_________|_____________|_________|
|Net, transparent FC|  YES	  |  YES   |  YES    |  YES	   |  YES    |
|___________________|_____________|________|_________|_____________|_________|
|Net, non-trans. FC |  YES	  |  no    |  no (5) |  YES	   |  YES    |
|___________________|_____________|________|_________|_____________|_________|
|Network, 7 bit     |  YES	  |  no    |  no     |  YES (2)    |  YES (3)|
|___________________|_____________|________|_________|_____________|_________|

(1) ZMODEM can optimize window size or burst length for fastest
transfers.
(2) Parity bits must be encoded, slowing binary transfers.
(3) Natural protocol extension possible for encoding data to 7 bits.
(4) Small WXMODEM window size may may allow operation.
(5) Some flow control codes are not escaped in WXMODEM.
(6) Kermit window size must be reduced to avoid buffer overrun.




Chapter 15	      Rev 10-27-87  Typeset 10-27-87			35







Chapter 15		     ZMODEM Protocol				36



16.  PERFORMANCE COMPARISON TABLES


"Round Trip Delay Time" includes the time for the last byte in a
packet to propagate through the operating systems and network to the
receiver, plus the time for the receiver's response to that packet
to propagate back to the sender.

The figures shown below are calculated for round trip delay times of
40 milliseconds and 5 seconds.  Shift registers in the two computers
and a pair of 212 modems generate a round trip delay time on the
order of 40 milliseconds.  Operation with busy timesharing computers
and networks can easily generate round trip delays of five seconds.
Because the round trip delays cause visible interruptions of data
transfer when using XMODEM protocol, the subjective effect of these
delays is greatly exaggerated, especially when the user is paying
for connect time.

A 102400 byte binary file with randomly distributed codes is sent at
1200 bps 8 data bits, 1 stop bit.  The calculations assume no
transmission errors.  For each of the protocols, only the per file
functions are considered.  Processor and I/O overhead are not
included.  YM-k refers to YMODEM with 1024 byte data packets.  YM-g
refers to the YMODEM "g" option.  ZMODEM uses 256 byte data
subpackets for this example.  SuperKermit uses maximum standard
packet size, 8 bit transparent transmission, no run length
compression.  The 4 block WXMODEM window is too small to span the 5
second delay in this example; the resulting thoughput degradation is
ignored.

For comparison, a straight "dump" of the file contents with no file
management or error checking takes 853 seconds.

		 TABLE 2.  Protocol Overhead Information
	   (102400 byte binary file, 5 Second Round Trip)

____________________________________________________________________________
       Protocol		 XMODEM   YM-k	  YM-g	 ZMODEM   SKermit   WXMODEM
____________________________________________________________________________
____________________________________________________________________________
 Protocol Round Trips	 804	  104	  5	 5	  5	    4
____________________________________________________________________________
 Trip Time at 40ms	 32s	  4s	  0	 0	  0	    0
____________________________________________________________________________
 Trip Time at 5s	 4020s	  520s	  25s	 25s	  25	    20
____________________________________________________________________________
____________________________________________________________________________
 Overhead Characters	 4803	  603	  503	 3600	  38280     8000
____________________________________________________________________________
____________________________________________________________________________
 Line Turnarounds	 1602	  204	  5	 5	  2560	    1602



Chapter 16	      Rev 10-27-87  Typeset 10-27-87			36







Chapter 16		     ZMODEM Protocol				37



|_____________________|________|_______|______|________|_________|_________|
|_____________________|________|_______|______|________|_________|_________|
|Transfer Time at 0s  |  893s  |  858s |  857s|  883s  |  1172s  |  916s   |
|_____________________|________|_______|______|________|_________|_________|
|Transfer Time at 40ms|  925s  |  862s |  857s|  883s  |  1172s  |  916s   |
|_____________________|________|_______|______|________|_________|_________|
|Transfer Time at 5s  |  5766s |  1378s|  882s|  918s  |  1197s  |  936s   |
|_____________________|________|_______|______|________|_________|_________|


		 Figure 5.  Transmission Time Comparison
	   (102400 byte binary file, 5 Second Round Trip)

************************************************** XMODEM
************ YMODEM-K
********** SuperKermit (Sliding Windows)
******* ZMODEM 16kb Segmented Streaming
******* ZMODEM Full Streaming
******* YMODEM-G

	TABLE 3.  Local Timesharing Computer Download Performance

__________________________________________________________________________
|    Command	|  Protocol|  Time/HD|  Time/FD|  Throughput|  Efficiency|
|_______________|__________|_________|_________|____________|____________|
|_______________|__________|_________|_________|____________|____________|
|kermit -x	|  Kermit  |  1:49   |  2:03   |  327	    |  34%	 |
|_______________|__________|_________|_________|____________|____________|
|sz -Xa phones.t|  XMODEM  |  1:20   |  1:44   |  343	    |  36%	 |
|_______________|__________|_________|_________|____________|____________|
|sz -a phones.t |  ZMODEM  |   :39   |	 :48   |  915	    |  95%	 |
|_______________|__________|_________|_________|____________|____________|


Times were measured downloading a 35721 character text file at 9600
bps, from Santa Cruz SysV 2.1.2 Xenix on a 9 mHz IBM PC-AT to DOS
2.1 on an IBM PC.  Xenix was in multiuser mode but otherwise idle.
Transfer times to PC hard disk and floppy disk destinations are
shown.

C-Kermit 4.2(030) used server mode and file compression, sending to
Pro-YAM 15.52 using 0 delay and a "get phones.t" command.

Crosstalk XVI 3.6 used XMODEM 8 bit checksum (CRC not available) and
an "ESC rx phones.t" command.  The Crosstalk time does not include
the time needed to enter the extra commands not needed by Kermit and
ZMODEM.

Professional-YAM used ZMODEM AutoDownload.  ZMODEM times included a
security challenge to the sending program.




Chapter 16	      Rev 10-27-87  Typeset 10-27-87			37







Chapter 16		     ZMODEM Protocol				38



		      TABLE 4.  File Transfer Speeds

__________________________________________________________________________________
| Prot	       file	   bytes    bps     ch/sec		 Notes		 |
|________________________________________________________________________________|
|X	  jancol.c	   18237    2400   53	       Tymnet PTL 5/3/87	 |
|X	  source.xxx	   6143     2400   56	       Source/Telenet PTL 5/29/87|
|X	  jancol.c	   18237    2400   64	       Tymnet PTL		 |
|B	  jancol.c	   18237    1200   87	       DataPac (604-687-7144)	 |
|XN	  tsrmaker.arc	   25088    1200   94	       GEnie PTL		 |
|B/ovth   emaibm.arc	   51200    1200   101	       CIS PTL MNP		 |
|UUCP	  74 files, each   >7000    1200   102	       Average, Various callers  |
|ZM	  jancol.c	   18237    1200   112	       DataPac (604-687-7144)	 |
|X/ovth   emaibm.arc	   51200    1200   114	       CIS PTL MNP		 |
|ZM	  emaibm.arc	   51200    1200   114	       CIS PTL MNP		 |
|B	  jancol.c	   18237    2400   124	       Tymnet PTL		 |
|B	  YI0515.87	   9081     2400   157	       CIS PTL node 5/29/87	 |
|SK	  source.xxx	   6143     2400   170	       Source/Telenet PTL 5/29/87|
|ZM	  jancol.c	   18237    2400   221	       Tymnet PTL upl/dl	 |
|B/ovth   destro.gif	   33613    2400   223	       CIS/PTL LEVEL 5 9-12-87	 |
|ZM	  jancol.c	   18237    2400   224	       Tymnet PTL		 |
|ZM	  jancol.c	   18237    2400   226/218     TeleGodzilla upl		 |
|ZM	  jancol.c	   18237    2400   226	       Tymnet PTL 5/3/87	 |
|ZM	  zmodem.ov	   35855    2400   227	       CIS PTL node		 |
|C	  jancol.c	   18237    2400   229	       Tymnet PTL 5/3/87	 |
|ZM	  jancol.c	   18237    2400   229/221     TeleGodzilla		 |
|ZM	  zmodem.ov	   35855    2400   229	       CIS PTL node upl		 |
|ZM	  jancol.c	   18237    2400   232	       CIS PTL node		 |
|ZM	  mbox		   473104   9600   948/942     TeleGodzilla upl		 |
|ZM	  zmodem.arc	   318826   14k    1357/1345   TeleGodzilla		 |
|ZM	  mbox		   473104   14k    1367/1356   TeleGodzilla upl		 |
|ZM	  c2.doc	   218823   38k    3473        Xenix 386 Toolkit upl	 |
|ZM	  mbox		   511893   38k    3860        386 Xenix 2.2 Beta #	 |
|ZM	  c.doc		   218823   57k    5611        **			 |
|________________________________________________________________________________|

Times are for downloads unless noted.  Where two speeds are noted,
the faster speed is reported by the receiver because its transfer
time calculation excludes the security check and transaction log
file processing.  The TeleGodzilla computer is a 4.77 mHz IBM PC
with a 10 MB hard disk.  The 386 computer uses an Intel motherboard
at 18 mHz 1ws.  The AT Clone (QIC) runs at 8 mHz 0ws.
Abbreviations:
 B     Compuserve B Protocol
 B/ovth			CIS B with Omen Technology OverThruster(TM)
 C     Capture DC2/DC4 (no protocol)
 K     Kermit
 MNP   Microcom MNP error correcting SX/1200 modem
 PTL   Portland Oregon network node
 SK    Sliding Window Kermit (SuperKermit) w=15
 X     XMODEM



Chapter 16	      Rev 10-27-87  Typeset 10-27-87			38







Chapter 16		     ZMODEM Protocol				39



 XN    XMODEM protocol implemented in network modes
 X/ovth			XMODEM, Omen Technology OverThruster(TM)
 ZM    ZMODEM
 Tk    Xenix 386 Toolkit, rz compiled -M3, dumb serial port
 **    AT Clone ramdisk to 386 ramdisk, or either ramdisk to nul
 #     On the fly format translation NL to CR/LF
		       TABLE 5.  Protocol Checklist

_________________________________________________________________________
|Item		       XMODEM  WXMODEM  YMDM-k	 YMDM-g  ZMODEM  SKermit|
|___________________|________|________|________|_______|_______|________|
|IN SERVICE	    |  1977  | 1986   | 1982   | 1985  | 1986  | 1985	|
|___________________|________|________|________|_______|_______|________|
|USER FEATURES	    |	     |	      |        |       |       |	|
|User Friendly I/F  |  -     | -      | -      | -     | YES   | -	|
|Commands/batch     |  2*N   | 2*N    | 2      | 2     | 1     | 1(1)	|
|Commands/file	    |  2     | 2      | 0      | 0     | 0     | 0	|
|Command Download   |  -     | -      | -      | -     | YES   | YES(6) |
|Menu Compatible    |  -     | -      | -      | -     | YES   | -	|
|Transfer Recovery  |  -     | -      | -      | -     | YES   | -	|
|File Management    |  -     | -      | -      | -     | YES   | -	|
|Security Check     |  -     | -      | -      | -     | YES   | -	|
|YMODEM Fallback    |  YES   | YES    | YES    | YES   | YES   | -	|
|___________________|________|________|________|_______|_______|________|
|COMPATIBILITY	    |	     |	      |        |       |       |	|
|Dynamic Files	    |  YES   | YES    | FAIL   | FAIL  | YES   | YES	|
|Packet SW NETS     |  -     | YES    | -      | -     | YES   | YES	|
|7 bit PS NETS	    |  -     | -      | -      | -     | (8)   | YES	|
|Old Mainframes     |  -     | -      | -      | -     | (8)   | YES	|
|CP/M-80	    |  YES   | YES    | YES    | -     | YES(9)| -	|
|___________________|________|________|________|_______|_______|________|
|ATTRIBUTES	    |	     |	      |        |       |       |	|
|Reliability(5)     |  fair  | poor   | fair(5)| none  | BEST  | HIGH	|
|Streaming	    |  -     | YES    | -      | YES   | YES   | YES	|
|Overhead(2)	    |  7%    | 7%     | 1%     | 1%    | 1%    | 30%	|
|Faithful Xfers     |  -     | -      | YES    | YES   | YES   | YES	|
|Preserve Date	    |  -     | -      | YES    | YES   | YES   | -	|
|___________________|________|________|________|_______|_______|________|
|COMPLEXITY	    |	     |	      |        |       |       |	|
|No-Wait Sample     |  -     | REQD   | -      | -     | opt   | REQD	|
|Ring Buffers	    |  -     | REQD   | -      | -     | opt   | REQD	|
|XMODEM Similar     |  YES   | LOW    | HIGH   | HIGH  | LOW   | NONE	|
|Complexity	    |  LOW(5)| MED    | LOW(5) | LOW   | MED   | HIGH	|
|___________________|________|________|________|_______|_______|________|
|EXTENSIONS	    |	     |	      |        |       |       |	|
|Server Operation   |  -     | -      | -      | -     | YES(4)| YES	|
|Multiple Threads   |  -     | -      | -      | -     | future| -	|
|___________________|________|________|________|_______|_______|________|

NOTES:
(1) Server mode or Omen Technology Kermit AutoDownload



Chapter 16	      Rev 10-27-87  Typeset 10-27-87			39







Chapter 16		     ZMODEM Protocol				40



(2) Character count, binary file, transparent channel
(3) 32 bit math needed for accurate transfer (no garbage added)
(4) AutoDownload operation
(5) Cybernetic Data Recovery(TM) improves XMODEM and YMODEM
reliability with complex proprietary logic.
(6) Server commands only
(7) No provision for transfers across time zones
(8) Future enhancement provided for
(9) With Segmented Streaming
WXMODEM: XMODEM derivative protocol with data encoding and windowing












































Chapter 16	      Rev 10-27-87  Typeset 10-27-87			40







Chapter 16		     ZMODEM Protocol				41



17.  FUTURE EXTENSIONS

Future extensions include:

   o Compatibility with 7 bit networks

   o Server/Link Level operation: An END-TO-END error corrected
     program to program session is required for financial and other
     sensitive applications.

   o Multiple independent threads

   o Encryption

   o Compression

   o File Comparison

   o Selective transfer within a file (e.g., modified segments of a
     database file)

   o Selective Retransmission for error correction


18.  REVISIONS

10-27-87 Optional fields added for number of files remaining to be
sent and total number of bytes remaining to be sent.
07-31-1987 The receiver should ignore a ZEOF with an offset that
does not match the current file length.  The previous action of
responding with ZRPOS caused transfers to fail if a CRC error
occurred immediately before end of file, because two retransmission
requests were being sent for each error.  This has been observed
under exceptional conditions, such as data transmission at speeds
greater than the receiving computer's interrupt response capabilitiy
or gross misapplication of flow control.

Discussion of the Tx backchannel garbage count and ZCRCW after error
ZRPOS was added.  Many revisions for clarity.
07-09-87 Corrected XMODEM's development date, incorrectly stated as
1979 instead of the actual August 1977.  More performance data was
added.
05-30-87 Added ZMNEW and ZMSKNOLOC
05-14-87 Window management, ZACK zshhdr XON removed, control
character escaping, ZMSPARS changed to ZXPARS, editorial changes.
04-13-87  The ZMODEM file transfer protocol's public domain status
is emphasized.
04-04-87: minor editorial changes, added conditionals for overview
version.
03-15-87: 32 bit CRC added.
12-19-86: 0 Length ZCRCW data subpacket sent in response to ZPAD or



Chapter 18	      Rev 10-27-87  Typeset 10-27-87			41







Chapter 18		     ZMODEM Protocol				42



ZDELE detected on reverse channel has been changed to ZCRCE.  The
reverse channel is now checked for activity before sending each
ZDATA header.
11-08-86: Minor changes for clarity.
10-2-86:  ZCNL definition expanded.
9-11-86:  ZMPROT file management option added.
8-20-86:  More performance data included.
8-4-86:  ASCII DLE (Ctrl-P, 020) now escaped; compatible with
previous versions.  More document revisions for clarity.
7-15-86: This document was extensively edited to improve clarity and
correct small errors.  The definition of the ZMNEW management option
was modified, and the ZMDIFF management option was added.  The
cancel sequence was changed from two to five CAN characters after
spurious two character cancel sequences were detected.


19.  MORE INFORMATION

Please contact Omen Technology for troff source files and typeset
copies of this document.


19.1  TeleGodzilla Bulletin Board

More information may be obtained by calling the TeleGodzilla
bulletin board at 503-621-3746.  TeleGodzilla supports 19200
(Telebit PEP), 2400 and 1200 bps callers with automatic speed
recognition.

Relevant files include YZMODEM.ZOO, YAMDEMO.ZOO, YAMHELP.ZOO,
ZCOMMEXE.ARC, ZCOMMDOC.ARC, ZCOMMHLP.ARC, and YMODEM.DQC.

Useful commands for TeleGodzilla include "menu", "dir", "sx file
(XMODEM)", "kermit sb file ...", and "sz file ...".

19.2  Unix UUCP Access

UUCP sites can obtain the current version of this file with
	      uucp omen!/u/caf/public/zmodem.doc /tmp
A continually updated list of available files is stored in
/usr/spool/uucppublic/FILES.
	   uucp  omen!~uucp/FILES   /usr/spool/uucppublic

The following L.sys line allows UUCP to call site "omen" via Omen's
bulletin board system "TeleGodzilla".  TeleGodzilla is an instance
of Omen Technology's Professional-YAM in host operation, acting as a
bulletin board and front ending a Xenix system.

In response to TeleGodzilla's "Name Please:" (e:--e:), uucico gives
the Pro-YAM "link" command as a user name.  Telegodzilla then asks
for a link password (d:).  The password (Giznoid) controls access to



Chapter 19	      Rev 10-27-87  Typeset 10-27-87			42







Chapter 19		     ZMODEM Protocol				43



the Xenix system connected to the IBM PC's other serial port.
Communications between Pro-YAM and Xenix use 9600 bps; YAM converts
this to the caller's speed.

Finally, the calling uucico sees the Xenix "Login:" message (n:--
n:), and logs in as "uucp".  No password is used for the uucp
account.

omen Any ACU 2400 1-503-621-3746 e:--e: link d: Giznoid n:--n: uucp



20.  ZMODEM PROGRAMS

A copy of this document, a demonstration version of
Professional-YAM, a flash-up tree structured help file and
processor, are available in YZMODEM.ZOO on TeleGodzilla and other
bulletin boards.  This file must be unpacked with LOOZ.EXE, also
available on TeleGodzilla.  YZMODEM.ZOO may be distributed provided
none of the files are deleted or modified without the written
consent of Omen Technology.

TeleGodzilla and other bulletin boards also feature ZCOMM, a
shareware communications program.  ZCOMM includes Omen Technology's
TurboLearn(TM) Script Writer, ZMODEM, Omen's highly acclaimed XMODEM
and YMODEM protocol support, Sliding Windows Kermit, several
traditional protocols, a powerful script language, and the most
accurate VT100/102 emulation available in a usr supported program.
The ZCOMM files include:

  o ZCOMMEXE.ARC Executable files and beginner's telephone directory

  o ZCOMMDOC.ARC "Universal Line Printer Edition" Manual

  o ZCOMMHLP.ARC Tree structured Flash-UP help processor and
    database

Source code and manual pages for the Unix/Xenix rz and sz programs
are available on TeleGodzilla in RZSZ.ZOO.  This ZOO archive may be
unpacked with LOOZ.EXE, also available on TeleGodzilla.  Most Unix
like systems are supported, including V7, Sys III, 4.x BSD, SYS V,
Idris, Coherent, and Regulus.

RZSZ.ZOO includes a ZCOMM/Pro-YAM/PowerCom script ZUPL.T to upload
the small (178 lines) YMODEM bootstrap program MINIRB.C without a
file transfer protocol.  MINIRB uses the Unix stty(1) program to set
the required raw tty modes, and compiles without special flags on
virtually all Unix and Xenix systems.  ZUPL.T directs the Unix
system to compile MINIRB, then uses it as a bootstrap to upload the
rz/sz source and manual files.




Chapter 20	      Rev 10-27-87  Typeset 10-27-87			43







Chapter 20		     ZMODEM Protocol				44



The PC-DOS Opus and Nochange bulletin boards support ZMODEM.
Integrated ZMODEM support for the Collie bulletin board program is
planned.

A number of other bulletin board programs support ZMODEM with
external modules (DSZ, etc.).

The PC-DOS Teleconferencing system IN-SYNCH uses ZMODEM.

The LAN modem sharing program Line Plus has announced ZMODEM
support.

Other PC-DOS communications programs with ZMODEM support modules
include QMODEM and BOYAN.  Many programs are adding direct ZMODEM
support, including Crosstalk Mark IV, Telix 3.0, and (expected)
Procomm and Qmodem.

The ZMDM communications program by Jwahar Bammi runs on Atari ST
machines.

The Online!  program for the Amiga supports ZMODEM.

The Compuserve Information Service has ported the Unix rz/sz ZMODEM
programs to DECSYSTEM 20 assembler.

20.1  Adding ZMODEM to DOS Programs

DSZ is a small program that supports XMODEM, YMODEM, and ZMODEM file
transfers.  DSZ is designed to be called from a bulletin board
program or another communications program.  It may be called as
		     dsz port 2 sz file1 file2
to send files, or as
			   dsz port 2 rz
to receive zero or more file(s), or as
		     dsz port 2 rz filea fileb
to receive two files, the first to filea and the second (if sent) to
fileb.  This form of dsz may be used to control the pathname of
incoming file(s).  In this example, if the sending program attempted
to send a third file, the transfer would be terminated.

Dsz uses DOS stdout for messages (no direct CRT access), acquires
the COMM port vectors with standard DOS calls, and restores the COMM
port's interrupt vector and registers upon exit.

Further information on dsz may be found in dsz.doc and the ZCOMM or
Pro-YAM user manuals.








Chapter 21	      Rev 10-27-87  Typeset 10-27-87			44







Chapter 21		     ZMODEM Protocol				45



21.  YMODEM PROGRAMS

The Unix rz/sz programs support YMODEM as well as ZMODEM.  Most Unix
like systems are supported, including V7, Sys III, 4.2 BSD, SYS V,
Idris, Coherent, and Regulus.

A version for VAX-VMS is available in VRBSB.SHQ, in the same
directory.

Irv Hoff has added 1k packets and YMODEM transfers to the KMD and
IMP series programs, which replace the XMODEM and MODEM7/MDM7xx
series respectively.  Overlays are available for a wide variety of
CP/M systems.

Many other programs, including MEX-PLUS and Crosstalk Mark IV also
support some of YMODEM's features.

Questions about YMODEM, the Professional-YAM communications program,
and requests for evaluation copies may be directed to:

     Chuck Forsberg
     Omen Technology Inc
     17505-V Sauvie Island Road
     Portland Oregon 97231
     VOICE: 503-621-3406 :VOICE
     Modem (TeleGodzilla): 503-621-3746
     Usenet: ...!tektronix!reed!omen!caf
     Compuserve: 70007,2304
     Source: TCE022


22.  ACKNOWLEDGMENTS

ZMODEM was developed for the public domain under a Telenet contract.
The ZMODEM protocol descriptions and the Unix rz/sz program source
code are public domain.  No licensing, trademark, or copyright
restrictions apply to the use of the protocol, the Unix rz/sz source
code and the ZMODEM name.

Encouragement and suggestions by Thomas Buck, Ward Christensen, Earl
Hall, Irv Hoff, Stuart Mathison, and John Wales, are gratefully
acknowledged.  32 bit CRC code courtesy Gary S. Brown.


23.  RELATED FILES

The following files may be useful while studying this document:

YMODEM.DOC Describes the XMODEM, XMODEM-1k, and YMODEM batch file
	transfer protocols.  This file is available on TeleGodzilla
	as YMODEM.DQC.



Chapter 23	      Rev 10-27-87  Typeset 10-27-87			45







Chapter 23		     ZMODEM Protocol				46



zmodem.h Definitions for ZMODEM manifest constants

rz.c, sz.c, rbsb.c Unix source code for operating ZMODEM programs.

rz.1, sz.1 Manual pages for rz and sz (Troff sources).

zm.c	Operating system independent low level ZMODEM subroutines.

minirb.c A YMODEM bootstrap program, 178 lines.

RZSZ.ZOO,rzsz.arc Contain the C source code and manual pages listed
	above, plus a ZCOMM script to upload minirb.c to a Unix or
	Xenix system, compile it, and use the program to upload the
	ZMODEM source files with error checking.

DSZ.ZOO,dsz.arc Contains DSZ.COM, a shareware X/Y/ZMODEM subprogram,
	DESQview "pif" files for background operation in minimum
	memory, and DSZ.DOC.

ZCOMM*.ARC Archive files for ZCOMM, a powerful shareware
	communications program.

































Chapter 23	      Rev 10-27-87  Typeset 10-27-87			46











			      CONTENTS


 1.  INTENDED AUDIENCE................................................	 2

 2.  WHY DEVELOP ZMODEM?..............................................	 2

 3.  ZMODEM Protocol Design Criteria..................................	 4
     3.1    Ease of Use...............................................	 4
     3.2    Throughput................................................	 5
     3.3    Integrity and Robustness..................................	 6
     3.4    Ease of Implementation....................................	 6

 4.  EVOLUTION OF ZMODEM..............................................	 7

 5.  ROSETTA STONE....................................................  10

 6.  ZMODEM REQUIREMENTS..............................................  10
     6.1    File Contents.............................................  10

 7.  ZMODEM BASICS....................................................  12
     7.1    Packetization.............................................  12
     7.2    Link Escape Encoding......................................  12
     7.3    Header....................................................  13
     7.4    Binary Data Subpackets....................................  16
     7.5    ASCII Encoded Data Subpacket..............................  16

 8.  PROTOCOL TRANSACTION OVERVIEW....................................  16
     8.1    Session Startup...........................................  16
     8.2    File Transmission.........................................  18
     8.3    Session Cleanup...........................................  20
     8.4    Session Abort Sequence....................................  20

 9.  STREAMING TECHNIQUES / ERROR RECOVERY............................  21
     9.1    Full Streaming with Sampling..............................  21
     9.2    Full Streaming with Reverse Interrupt.....................  23
     9.3    Full Streaming with Sliding Window........................  23
     9.4    Full Streaming over Error Free Channels...................  24
     9.5    Segmented Streaming.......................................  24

10.  ATTENTION SEQUENCE...............................................  24

11.  FRAME TYPES......................................................  25
     11.1   ZRQINIT...................................................  25
     11.2   ZRINIT....................................................  25
     11.3   ZSINIT....................................................  25
     11.4   ZACK......................................................  26
     11.5   ZFILE.....................................................  26
     11.6   ZSKIP.....................................................  28
     11.7   ZNAK......................................................  28
     11.8   ZABORT....................................................  28



				  - i -











     11.9   ZFIN......................................................  28
     11.10  ZRPOS.....................................................  28
     11.11  ZDATA.....................................................  29
     11.12  ZEOF......................................................  29
     11.13  ZFERR.....................................................  29
     11.14  ZCRC......................................................  29
     11.15  ZCHALLENGE................................................  29
     11.16  ZCOMPL....................................................  29
     11.17  ZCAN......................................................  29
     11.18  ZFREECNT..................................................  29
     11.19  ZCOMMAND..................................................  29

12.  SESSION TRANSACTION EXAMPLES.....................................  30
     12.1   A simple file transfer....................................  30
     12.2   Challenge and Command Download............................  31

13.  ZFILE FRAME FILE INFORMATION.....................................  31

14.  PERFORMANCE RESULTS..............................................  33
     14.1   Compatibility.............................................  33
     14.2   Throughput................................................  33
     14.3   Error Recovery............................................  34

15.  PACKET SWITCHED NETWORK CONSIDERATIONS...........................  34

16.  PERFORMANCE COMPARISON TABLES....................................  36

17.  FUTURE EXTENSIONS................................................  41

18.  REVISIONS........................................................  41

19.  MORE INFORMATION.................................................  42
     19.1   TeleGodzilla Bulletin Board...............................  42
     19.2   Unix UUCP Access..........................................  42

20.  ZMODEM PROGRAMS..................................................  43
     20.1   Adding ZMODEM to DOS Programs.............................  44

21.  YMODEM PROGRAMS..................................................  45

22.  ACKNOWLEDGMENTS..................................................  45

23.  RELATED FILES....................................................  45


LIST OF FIGURES


Figure 1.  Order of Bytes in Header...................................  14

Figure 2.  16 Bit CRC Binary Header...................................  14



				  - ii -











Figure 3.  32 Bit CRC Binary Header...................................  14

Figure 4.  HEX Header.................................................  15

Figure 5.  Transmission Time Comparison...............................  37


LIST OF TABLES


TABLE 1.  Network and Flow Control Compatibility......................  35

TABLE 2.  Protocol Overhead Information...............................  36

TABLE 3.  Local Timesharing Computer Download Performance.............  37

TABLE 4.  File Transfer Speeds........................................  38

TABLE 5.  Protocol Checklist..........................................  39



































				 - iii -









	   The ZMODEM Inter Application File Transfer Protocol

			      Chuck Forsberg

			   Omen Technology Inc


				 ABSTRACT



The ZMODEM file transfer protocol provides reliable file and command
transfers with complete END-TO-END data integrity between application
programs.  ZMODEM's 32 bit CRC catches errors that continue to sneak into
even the most advanced networks.

ZMODEM rapidly transfers files, particularly with buffered (error
correcting) modems, timesharing systems, satellite relays, and wide area
packet switched networks.

ZMODEM greatly simplifies file transfers compared to XMODEM.  In addition
to a friendly user interface, ZMODEM provides Personal Computer and other
users an efficient, accurate, and robust file transfer method.

ZMODEM provides advanced file management features including AutoDownload
(Automatic file Download initiated without user intervention), Crash
Recovery, selective file transfers, and security verified command
downloading.

ZMODEM protocol features allow implementation on a wide variety of systems
operating in a wide variety of environments.  A choice of buffering and
windowing modes allows ZMODEM to operate on systems that cannot support
other streaming protocols.  Finely tuned control character escaping allows
operation with real world networks without Kermit's high overhead.

Although ZMODEM software is more complex than unreliable XMODEM routines,
actual C source code to production programs allows developers to upgrade
their applications with efficient, reliable ZMODEM file transfers with a
minimum of effort.

ZMODEM is carefully designed to provide these benefits using a minimum of
new software technology.  ZMODEM can be implemented on all but the most
brain damaged computers.

ZMODEM was developed for the public domain under a Telenet contract.  The
ZMODEM protocol descriptions and the Unix rz/sz program source code are
public domain.  No licensing, trademark, or copyright restrictions apply
to the use of the protocol, the Unix rz/sz source code and the ZMODEM
name.