Submitted-by: michaeli@stout.atd.ucar.edu
Archive-name: xmodem/part04

#!/bin/sh
# this is xmodem.04 (part 4 of xmodem)
# do not concatenate these parts, unpack them in order with /bin/sh
# file xmodem/send.c continued
#
touch -am 1231235999 $$.touch >/dev/null 2>&1
if test ! -f 1231235999 && test -f $$.touch; then
  shar_touch=touch
else
  shar_touch=:
  echo 'WARNING: not restoring timestamps'
fi
rm -f 1231235999 $$.touch
#
if test ! -r _sharseq.tmp; then
  echo 'Please unpack part 1 first!'
  exit 1
fi
shar_sequence=`cat _sharseq.tmp`
if test "$shar_sequence" != 4; then
  echo "Please unpack part $shar_sequence next!"
  exit 1
fi
if test ! -f _sharnew.tmp; then
  echo 'x - still skipping xmodem/send.c'
else
  echo 'x - continuing file xmodem/send.c'
  sed 's/^X//' << 'SHAR_EOF' >> 'xmodem/send.c' &&
X				logit("Receiver invoked CRC mode\n");
X				tlogit("Receiver invoked CRC mode\n");
X				}
X			if (readbyte(1) == KCHR)
X				{
X				buf1024 = TRUE;
X				logit("Receiver invoked 1K packet mode\n");
X				tlogit("Receiver invoked 1K packet mode\n");
X				}
X			}
X		}
X	while (firstchar != NAK && firstchar != CRCCHR && firstchar != GCHR);
X
X	if (MDM7BAT && closeout)	/* close out MODEM7 batch */
X		{
X		sendbyte(ACK); sendbyte (EOT);
X		flushin(); readbyte(2); 	/* flush junk */
X		return;
X		}
X
X	if (MDM7BAT && startup)		/* send MODEM7 file name */
X		{
X		if (send_name(unix_cpm(name)) == -1)
X			{
X			attempts = 0;
X			goto restart;
X			}
X		startup = FALSE;
X		attempts = 0;
X		goto restart;
X		}
X
X	sectnum = 1;
X
X	if (YMDMBAT)	/* Fudge for YMODEM transfer (to send name packet) */
X		{
X		sectnum = 0;
X		bufsize = 128;
X		filepack = TRUE;
X		}
X
X	attempts = sentsect = 0;
X	start = time((time_t *) 0);
X
X        do 			/* outer packet building/sending loop; loop till whole file is sent */
X		{   
X
X		if (closeout && YMDMBAT && sectnum == 1)	/* close out YMODEM */
X			return;
X
X		if (YMDMBAT && sectnum == 1)			/* get set to send YMODEM data packets */
X			{
X			bufsize = buf1024 ? 1024 : 128;
X
X			do		/* establish handshaking again */
X				{
X				while (((firstchar=readbyte(2)) != CRCCHR) && (firstchar != GCHR) && (firstchar != NAK) && (firstchar != CAN))
X					if (++attempts > ERRORMAX)
X						error("YMODEM protocol botch, C or G expected", TRUE);
X				if ((firstchar&0x7f) == CAN)
X					if (readbyte(3) == CAN)
X						error("Send Canceled by CAN-CAN", TRUE);
X				}
X			while ((firstchar != CRCCHR) &&  (firstchar != GCHR) && (firstchar != NAK));
X
X			attempts = 0;
X			}
X
X		if ((bufsize == 1024) && (attempts > KSWMAX))
X			{
X			logit("Reducing packet size to 128 due to excessive errors\n");
X			tlogit("Reducing packet size to 128 due to excessive errors\n");
X			bufsize = 128;
X			}
X
X		if ((bufsize == 1024) && ((expsect - sentsect) < 8))
X			{
X			logit("Reducing packet size to 128 for tail end of file\n");
X			tlogit("Reducing packet size to 128 for tail end of file\n");
X			bufsize = 128;
X			}
X
X		if (sectnum > 0)	/* data packet */
X			{
X			for (bufctr=0; bufctr < bufsize;)
X	    			{
X				if (nlflag)
X	       	 			{  
X					buff[bufctr++] = LF;  /* leftover newline */
X	       	    			nlflag = FALSE;
X	        			}
X				if (getbyte(fd, &c) == EOF)
X					{ 
X					sendfin = TRUE;  /* this is the last sector */
X		   			if (!bufctr)  /* if EOF on sector boundary */
X		      				break;  /* avoid sending extra sector */
X		      			buff[bufctr++] = CTRLZ;  /* pad with Ctrl-Z for CP/M EOF (even do for binary files) */
X		   			continue;
X		      			}
X	
X				if (tmode && c == LF)  /* text mode & Unix newline? */
X		    			{
X					buff[bufctr++] = CR;  /* insert carriage return */
X			     		if (bufctr < bufsize)
X		                		buff[bufctr++] = LF;  /* insert LF */
X		 	      		else
X			        		nlflag = TRUE;  /* insert on next sector */
X		   			}	
X				else if (amode && c == LF)   /* Apple mode & Unix newline? */
X					buff[bufctr++] = CR; /* substitute CR */
X				else
X					buff[bufctr++] = c;  /* copy the char without change */
X		    		}
X
X	    		if (!bufctr)  /* if EOF on sector boundary */
X   	       			break;  /* avoid sending empty sector */
X			}	
X
X		else		/* YMODEM filename packet */
X			{
X			for (bufctr=0; bufctr<1024; bufctr++)  /* zero packet */
X				buff[bufctr]=0;
X			if (!closeout)
X				{
X				strcpy((char *)buff, cpmify(name));
X				
X					/* put in file name, length, mode, */
X					/* dummy SN, files, bytes remaining and file type */
X					{
X					register char *p;
X					p = (char *)buff + strlen(buff) + 1;
X					sprintf(p, "%lu %lo %o 0 %d %ld 0", filestatbuf.st_size, 
X					  filestatbuf.st_mtime, filestatbuf.st_mode,
X					  yfilesleft, ytotleft);
X					if (DEBUG)
X						fprintf(LOGFP, "DEBUG: YMODEM header information: %s %s\n", buff, p);
X					}
X				if (buff[125])		/* need to have long packet? */
X					{
X					bufsize = 1024;
X					if (DEBUG)
X						fprintf(LOGFP, "DEBUG: YMODEM header sent in 1024 byte packet\n");
X					}
X				buff[bufsize-2]	= (expsect & 0xff);        /* put in KMD kludge information */
X				buff[bufsize-1] = ((expsect >> 8) & 0xff);
X
X				/* update totals */
X				ytotleft -= filestatbuf.st_size;
X				if (--yfilesleft <= 0)
X					ytotleft = 0;
X				if (ytotleft < 0)
X					ytotleft = 0;
X				}
X			}
X
X		bbufcnt = 0;		/* start building block to be sent */
X		blockbuf[bbufcnt++] = (bufsize == 1024) ? STX : SOH;    /* start of packet char */
X		blockbuf[bbufcnt++] = sectnum;	    /* current sector # */
X		blockbuf[bbufcnt++] = ~sectnum;   /* and its complement */
X
X               	checksum = 0;  /* initialize checksum */
X               	for (bufctr=0; bufctr < bufsize; bufctr++)
X       			{
X			blockbuf[bbufcnt++] = buff[bufctr];
X
X			if (CRCMODE)
X				checksum = (checksum<<B) ^ crctab[(checksum>>(W-B)) ^ buff[bufctr]];
X
X			else
X               			checksum = ((checksum+buff[bufctr]) & 0xff);
X         		}
X
X		if (CRCMODE)		/* put in CRC */
X			{
X			checksum &= 0xffff;
X			blockbuf[bbufcnt++] = ((checksum >> 8) & 0xff);
X			blockbuf[bbufcnt++] = (checksum & 0xff);
X			}
X		else			/* put in checksum */
X			blockbuf[bbufcnt++] = checksum;
X
X            	attempts = 0;
X	
X            	do				/* inner packet loop */
X            		{
X
X			writebuf(blockbuf, bbufcnt);	/* write the block */
X			if (!YMODEMG)
X				flushin();              /* purge anything in input queue */
X
X			if (DEBUG)
X				fprintf (LOGFP, "DEBUG: %d byte Packet %02xh (%02xh) sent, checksum %02xh %02xh\n", 
X				bbufcnt, blockbuf[1]&0xff, blockbuf[2]&0xff, blockbuf[bufsize+3]&0xff, blockbuf[bufsize+4]&0xff);
X
X                	attempts++;
X			sendresp = (YMODEMG) ? ACK : readbyte(10);	/* get response from remote  (or fake it for YMODEM-G) */
X
X			if (sendresp != ACK)
X		   		{
X				if (sendresp == TIMEOUT)
X					{
X		   			logitarg("Timeout on sector %s\n",sectdisp(sentsect,bufsize,1));
X		   			tlogitarg("Timeout on sector %s\n",sectdisp(sentsect,bufsize,1));
X					}
X				if (sendresp == CAN)
X					{
X					if (CANCAN)
X						{
X						if (readbyte(3) == CAN)
X							error("Send Canceled by CAN-CAN",TRUE);
X						}
X					else
X						{
X		   			logitarg("ignored CAN on sector %s\n",sectdisp(sentsect,bufsize,1));
X		   			tlogitarg("ignored CAN on sector %s\n",sectdisp(sentsect,bufsize,1));
X						}
X					}
X				else if (sendresp == NAK)
X					{
X		   			logitarg("NAK on sector %s\n",sectdisp(sentsect,bufsize,1));
X		   			tlogitarg("NAK on sector %s\n",sectdisp(sentsect,bufsize,1));
X					}
X				else
X					{
X		   			logitarg("Non-ACK on sector %s\n",sectdisp(sentsect,bufsize,1));
X		   			tlogitarg("Non-ACK on sector %s\n",sectdisp(sentsect,bufsize,1));
X					}
X		   		}
X            		}
X			while((sendresp != ACK) && (attempts < ERRORMAX));	/* close of inner loop */
X
X       		sectnum++;  /* increment to next sector number */
X		if (!filepack)
X			sentsect += (bufsize == 128) ? 1 : 8;
X		filepack = FALSE;
X		if (TIPFLAG && sentsect % 32 == 0)
X			tlogitarg("Sector %s sent\n", sectdisp(sentsect,bufsize,0));
X    		}
X		while (!sendfin && ( attempts < ERRORMAX));	/* end of outer loop */
X
X	if (attempts >= ERRORMAX)
X		{
X		sendbyte(CAN); sendbyte(CAN); sendbyte(CAN); sendbyte(CAN); sendbyte(CAN);
X		error ("Too many errors in transmission", TRUE);
X		}
X
X    	sendbyte(EOT);  /* send 1st EOT to close down transfer */
X    	attempts = 0;
X	
X    	while ((readbyte(15) != ACK) && (attempts++ < EOTMAX)) 	/* wait for ACK of EOT */
X		{
X		if (attempts > 1)
X			{
X			logitarg("EOT not ACKed, try %d\n", attempts);
X			tlogitarg("EOT not ACKed, try %d\n", attempts);
X			}
X	   	sendbyte(EOT);
X		}
X
X    	if (attempts >= RETRYMAX)
X	   	error("Remote System Not Responding on Completion", TRUE);
X
X    	close(fd);
X
X    	logit("Send Complete\n");
X    	tlogit("Send Complete\n");
X	if (LOGFLAG)
X		prtime(sentsect, time((time_t *) 0) - start, LOGFP);
X	if (TIPFLAG)
X		prtime(sentsect, time((time_t *) 0) - start, stderr);
X	}
SHAR_EOF
  echo 'File xmodem/send.c is complete' &&
  $shar_touch -am 0812084894 'xmodem/send.c' &&
  chmod 0644 'xmodem/send.c' ||
  echo 'restore of xmodem/send.c failed'
  shar_count="`wc -c < 'xmodem/send.c'`"
  test 12532 -eq "$shar_count" ||
    echo "xmodem/send.c: original size 12532, current size $shar_count"
  rm -f _sharnew.tmp
fi
# ============= xmodem/ymodem.doc ==============
if test -f 'xmodem/ymodem.doc' && test X"$1" != X"-c"; then
  echo 'x - skipping xmodem/ymodem.doc (File already exists)'
  rm -f _sharnew.tmp
else
  > _sharnew.tmp
  echo 'x - extracting xmodem/ymodem.doc (Text)'
  sed 's/^X//' << 'SHAR_EOF' > 'xmodem/ymodem.doc' &&
X
X
X
X                                      - 1 -
X
X
X
X                         XMODEM/YMODEM PROTOCOL REFERENCE
X                     A compendium of documents describing the
X
X                                XMODEM and YMODEM
X
X                             File Transfer Protocols
X
X
X
X
X                      This document was formatted 10-14-88.
X
X
X
X
X
X
X
X                             Edited by Chuck Forsberg
X
X
X
X
X
X
X
X
X
X                This file may be redistributed without restriction
X                        provided the text is not altered.
X
X                     Please distribute as widely as possible.
X
X                           Questions to Chuck Forsberg
X
X
X
X
X
X                               Omen Technology Inc
X                          The High Reliability Software
X                            17505-V Sauvie Island Road
X                              Portland Oregon 97231
X                            VOICE: 503-621-3406 :VOICE
X      TeleGodzilla BBS: 503-621-3746 Speed 19200(Telebit PEP),2400,1200,300
X                              CompuServe: 70007,2304
X                                    GEnie: CAF
X                        UUCP: ...!tektronix!reed!omen!caf
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X                                      - 2 -
X
X
X
X    1.  TOWER OF BABEL
X
X    A "YMODEM Tower of Babel" has descended on the microcomputing community
X    bringing with it confusion, frustration, bloated phone bills, and wasted
X    man hours.  Sadly, I (Chuck Forsberg) am partly to blame for this mess.
X
X    As author of the early 1980s batch and 1k XMODEM extensions, I assumed
X    readers of earlier versions of this document would implement as much of
X    the YMODEM protocol as their programming skills and computing environments
X    would permit.  This proved a rather naive assumption as programmers
X    motivated by competitive pressure implemented as little of YMODEM as
X    possible.  Some have taken whatever parts of YMODEM that appealed to them,
X    applied them to MODEM7 Batch, Telink, XMODEM or whatever, and called the
X    result YMODEM.
X
X    Jeff Garbers (Crosstalk package development director) said it all: "With
X    protocols in the public domain, anyone who wants to dink around with them
X    can go ahead." [1]
X
X    Documents containing altered examples derived from YMODEM.DOC have added
X    to the confusion.  In one instance, some self styled rewriter of history
X    altered the heading in YMODEM.DOC's Figure 1 from "1024 byte Packets" to
X    "YMODEM/CRC File Transfer Protocol".  None of the XMODEM and YMODEM
X    examples shown in that document were correct.
X
X    To put an end to this confusion, we must make "perfectly clear" what
X    YMODEM stands for, as Ward Christensen defined it in his 1985 coining of
X    the term.
X
X    To the majority of you who read, understood, and respected Ward's
X    definition of YMODEM, I apologize for the inconvenience.
X
X    1.1  Definitions
X
X    ARC     ARC is a program that compresses one or more files into an archive
X            and extracts files from such archives.
X
X    XMODEM  refers to the file transfer etiquette introduced by Ward
X            Christensen's 1977 MODEM.ASM program.  The name XMODEM comes from
X            Keith Petersen's XMODEM.ASM program, an adaptation of MODEM.ASM
X            for Remote CP/M (RCPM) systems.  It's also called the MODEM or
X            MODEM2 protocol.  Some who are unaware of MODEM7's unusual batch
X            file mode call it MODEM7.  Other aliases include "CP/M Users'
X            Group" and "TERM II FTP 3".  The name XMODEM caught on partly
X            because it is distinctive and partly because of media interest in
X
X
X    __________
X
X     1. Page C/12, PC-WEEK July 12, 1987
X
X
X
X
X    Chapter 1
X
X
X
X
X
X
X
X    X/YMODEM Protocol Reference    June 18 1988                              3
X
X
X
X            bulletin board and RCPM systems where it was accessed with an
X            "XMODEM" command.  This protocol is supported by every serious
X            communications program because of its universality, simplicity,
X            and reasonable performance.
X
X    XMODEM/CRC replaces XMODEM's 1 byte checksum with a two byte Cyclical
X            Redundancy Check (CRC-16), giving modern error detection
X            protection.
X
X    XMODEM-1k Refers to the XMODEM/CRC protocol with 1024 byte data blocks.
X
X    YMODEM  Refers to the XMODEM/CRC (optional 1k blocks) protocol with batch
X            transmission as described below.  In a nutshell, YMODEM means
X            BATCH.
X
X    YMODEM-g Refers to the streaming YMODEM variation described below.
X
X    True YMODEM(TM) In an attempt to sort out the YMODEM Tower of Babel, Omen
X            Technology has trademarked the term True YMODEM(TM) to represent
X            the complete YMODEM protocol described in this document, including
X            pathname, length, and modification date transmitted in block 0.
X            Please contact Omen Technology about certifying programs for True
X            YMODEM(TM) compliance.
X
X    ZMODEM  uses familiar XMODEM/CRC and YMODEM technology in a new protocol
X            that provides reliability, throughput, file management, and user
X            amenities appropriate to contemporary data communications.
X
X    ZOO     Like ARC, ZOO is a program that compresses one or more files into
X            a "zoo archive".  ZOO supports many different operating systems
X            including Unix and VMS.
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X    Chapter 1
X
X
X
X
X
X
X
X    X/YMODEM Protocol Reference    June 18 1988                              4
X
X
X
X    2.  YMODEM MINIMUM REQUIREMENTS
X
X    All programs claiming to support YMODEM must meet the following minimum
X    requirements:
X
X       + The sending program shall send the pathname (file name) in block 0.
X
X       + The pathname shall be a null terminated ASCII string as described
X         below.
X
X         For those who are too lazy to read the entire document:
X
X            + Unless specifically requested, only the file name portion is
X              sent.
X
X            + No drive letter is sent.
X
X            + Systems that do not distinguish between upper and lower case
X              letters in filenames shall send the pathname in lower case only.
X
X
X       + The receiving program shall use this pathname for the received file
X         name, unless explicitly overridden.
X
X       + When the receiving program receives this block and successfully
X         opened the output file, it shall acknowledge this block with an ACK
X         character and then proceed with a normal XMODEM file transfer
X         beginning with a "C" or NAK tranmsitted by the receiver.
X
X       + The sending program shall use CRC-16 in response to a "C" pathname
X         nak, otherwise use 8 bit checksum.
X
X       + The receiving program must accept any mixture of 128 and 1024 byte
X         blocks within each file it receives.  Sending programs may
X         arbitrarily switch between 1024 and 128 byte blocks.
X
X       + The sending program must not change the length of an unacknowledged
X         block.
X
X       + At the end of each file, the sending program shall send EOT up to ten
X         times until it receives an ACK character.  (This is part of the
X         XMODEM spec.)
X
X       + The end of a transfer session shall be signified by a null (empty)
X         pathname, this pathname block shall be acknowledged the same as other
X         pathname blocks.
X
X    Programs not meeting all of these requirements are not YMODEM compatible,
X    and shall not be described as supporting YMODEM.
X
X    Meeting these MINIMUM requirements does not guarantee reliable file
X
X
X
X    Chapter 2
X
X
X
X
X
X
X
X    X/YMODEM Protocol Reference    June 18 1988                              5
X
X
X
X    transfers under stress.  Particular attention is called to XMODEM's single
X    character supervisory messages that are easily corrupted by transmission
X    errors.
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X    Chapter 2
X
X
X
X
X
X
X
X    X/YMODEM Protocol Reference    June 18 1988                              6
X
X
X
X    3.  WHY YMODEM?
X
X    Since its development half a decade ago, the Ward Christensen modem
X    protocol has enabled a wide variety of computer systems to interchange
X    data.  There is hardly a communications program that doesn't at least
X    claim to support this protocol.
X
X    Advances in computing, modems and networking have revealed a number of
X    weaknesses in the original protocol:
X
X       + The short block length caused throughput to suffer when used with
X         timesharing systems, packet switched networks, satellite circuits,
X         and buffered (error correcting) modems.
X
X       + The 8 bit arithmetic checksum and other aspects allowed line
X         impairments to interfere with dependable, accurate transfers.
X
X       + Only one file could be sent per command.  The file name had to be
X         given twice, first to the sending program and then again to the
X         receiving program.
X
X       + The transmitted file could accumulate as many as 127 extraneous
X         bytes.
X
X       + The modification date of the file was lost.
X
X    A number of other protocols have been developed over the years, but none
X    have displaced XMODEM to date:
X
X       + Lack of public domain documentation and example programs have kept
X         proprietary protocols such as Blast, Relay, and others tightly bound
X         to the fortunes of their suppliers.
X
X       + Complexity discourages the widespread application of BISYNC, SDLC,
X         HDLC, X.25, and X.PC protocols.
X
X       + Performance compromises and complexity have limited the popularity of
X         the Kermit protocol, which was developed to allow file transfers in
X         environments hostile to XMODEM.
X
X    The XMODEM protocol extensions and YMODEM Batch address some of these
X    weaknesses while maintaining most of XMODEM's simplicity.
X
X    YMODEM is supported by the public domain programs YAM (CP/M),
X    YAM(CP/M-86), YAM(CCPM-86), IMP (CP/M), KMD (CP/M), rz/sz (Unix, Xenix,
X    VMS, Berkeley Unix, Venix, Xenix, Coherent, IDRIS, Regulus).  Commercial
X    implementations include MIRROR, and Professional-YAM.[1] Communications
X
X
X
X
X
X
X
X    Chapter 3
X
X
X
X
X
X
X
X    X/YMODEM Protocol Reference    June 18 1988                              7
X
X
X
X    programs supporting these extensions have been in use since 1981.
X
X    The 1k block length (XMODEM-1k) described below may be used in conjunction
X    with YMODEM Batch Protocol, or with single file transfers identical to the
X    XMODEM/CRC protocol except for minimal changes to support 1k blocks.
X
X    Another extension is the YMODEM-g protocol.  YMODEM-g provides batch
X    transfers with maximum throughput when used with end to end error
X    correcting media, such as X.PC and error correcting modems, including 9600
X    bps units by TeleBit, U.S.Robotics, Hayes, Electronic Vaults, Data Race,
X    and others.
X
X    To complete this tome, edited versions of Ward Christensen's original
X    protocol document and John Byrns's CRC-16 document are included for
X    reference.
X
X    References to the MODEM or MODEM7 protocol have been changed to XMODEM to
X    accommodate the vernacular.  In Australia, it is properly called the
X    Christensen Protocol.
X
X
X    3.1  Some Messages from the Pioneer
X
X    #: 130940 S0/Communications 25-Apr-85  18:38:47
X    Sb: my protocol
X    Fm: Ward Christensen 76703,302 [2]
X    To: all
X
X    Be aware the article[3] DID quote me correctly in terms of the phrases
X    like "not robust", etc.
X
X    It was a quick hack I threw together, very unplanned (like everything I
X    do), to satisfy a personal need to communicate with "some other" people.
X
X    ONLY the fact that it was done in 8/77, and that I put it in the public
X    domain immediately, made it become the standard that it is.
X
X
X
X
X
X
X
X    __________________________________________________________________________
X
X     1. Available for IBM PC,XT,AT, Unix and Xenix
X
X     2. Edited for typesetting appearance
X
X     3. Infoworld April 29 p. 16
X
X
X
X
X    Chapter 3
X
X
X
X
X
X
X
X    X/YMODEM Protocol Reference    June 18 1988                              8
X
X
X
X    I think its time for me to
X
X    (1) document it; (people call me and say "my product is going to include
X    it - what can I 'reference'", or "I'm writing a paper on it, what do I put
X    in the bibliography") and
X
X    (2) propose an "incremental extension" to it, which might take "exactly"
X    the form of Chuck Forsberg's YAM protocol.  He wrote YAM in C for CP/M and
X    put it in the public domain, and wrote a batch protocol for Unix[4] called
X    rb and sb (receive batch, send batch), which was basically XMODEM with
X       (a) a record 0 containing filename date time and size
X       (b) a 1K block size option
X       (c) CRC-16.
X
X    He did some clever programming to detect false ACK or EOT, but basically
X    left them the same.
X
X    People who suggest I make SIGNIFICANT changes to the protocol, such as
X    "full duplex", "multiple outstanding blocks", "multiple destinations", etc
X    etc don't understand that the incredible simplicity of the protocol is one
X    of the reasons it survived to this day in as many machines and programs as
X    it may be found in!
X
X    Consider the PC-NET group back in '77 or so - documenting to beat the band
X    - THEY had a protocol, but it was "extremely complex", because it tried to
X    be "all things to all people" - i.e. send binary files on a 7-bit system,
X    etc.  I was not that "benevolent". I (emphasize > I < ) had an 8-bit UART,
X    so "my protocol was an 8-bit protocol", and I would just say "sorry" to
X    people who were held back by 7-bit limitations.  ...
X
X    Block size: Chuck Forsberg created an extension of my protocol, called
X    YAM, which is also supported via his public domain programs for UNIX
X    called rb and sb - receive batch and send batch.  They cleverly send a
X    "block 0" which contains the filename, date, time, and size.
X    Unfortunately, its UNIX style, and is a bit weird[5] - octal numbers, etc.
X    BUT, it is a nice way to overcome the kludgy "echo the chars of the name"
X    introduced with MODEM7.  Further, chuck uses CRC-16 and optional 1K
X    blocks.  Thus the record 0, 1K, and CRC, make it a "pretty slick new
X    protocol" which is not significantly different from my own.
X
X    Also, there is a catchy name - YMODEM.  That means to some that it is the
X    "next thing after XMODEM", and to others that it is the Y(am)MODEM
X
X
X    __________
X
X     4. VAX/VMS versions of these programs are also available.
X
X     5. The file length, time, and file mode are optional.  The pathname and
X        file length may be sent alone if desired.
X
X
X
X
X    Chapter 3
X
X
X
X
X
X
X
X    X/YMODEM Protocol Reference    June 18 1988                              9
X
X
X
X    protocol.  I don't want to emphasize that too much - out of fear that
X    other mfgrs might think it is a "competitive" protocol, rather than an
X    "unaffiliated" protocol.  Chuck is currently selling a much-enhanced
X    version of his CP/M-80 C program YAM, calling it Professional Yam, and its
X    for the PC - I'm using it right now.  VERY slick!  32K capture buffer,
X    script, scrolling, previously captured text search, plus built-in commands
X    for just about everything - directory (sorted every which way), XMODEM,
X    YMODEM, KERMIT, and ASCII file upload/download, etc.  You can program it
X    to "behave" with most any system - for example when trying a number for
X    CIS it detects the "busy" string back from the modem and substitutes a
X    diff phone # into the dialing string and branches back to try it.
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X    Chapter 3
X
X
X
X
X
X
X
X    X/YMODEM Protocol Reference    June 18 1988                             10
X
X
X
X    4.  XMODEM PROTOCOL ENHANCEMENTS
X
X    This chapter discusses the protocol extensions to Ward Christensen's 1982
X    XMODEM protocol description document.
X
X    The original document recommends the user be asked whether to continue
X    trying or abort after 10 retries.  Most programs no longer ask the
X    operator whether he wishes to keep retrying.  Virtually all correctable
X    errors are corrected within the first few retransmissions.  If the line is
X    so bad that ten attempts are insufficient, there is a significant danger
X    of undetected errors.  If the connection is that bad, it's better to
X    redial for a better connection, or mail a floppy disk.
X
X
X    4.1  Graceful Abort
X
X    The YAM and Professional-YAM X/YMODEM routines recognize a sequence of two
X    consecutive CAN (Hex 18) characters without modem errors (overrun,
X    framing, etc.) as a transfer abort command.  This sequence is recognized
X    when is waiting for the beginning of a block or for an acknowledgement to
X    a block that has been sent.  The check for two consecutive CAN characters
X    reduces the number of transfers aborted by line hits.  YAM sends eight CAN
X    characters when it aborts an XMODEM, YMODEM, or ZMODEM protocol file
X    transfer.  Pro-YAM then sends eight backspaces to delete the CAN
X    characters from the remote's keyboard input buffer, in case the remote had
X    already aborted the transfer and was awaiting a keyboarded command.
X
X
X    4.2  CRC-16 Option
X
X    The XMODEM protocol uses an optional two character CRC-16 instead of the
X    one character arithmetic checksum used by the original protocol and by
X    most commercial implementations.  CRC-16 guarantees detection of all
X    single and double bit errors,  all errors with an odd number of error
X    bits, all burst errors of length 16 or less, 99.9969% of all 17-bit error
X    bursts, and 99.9984 per cent of all possible longer error bursts.  By
X    contrast, a double bit error, or a burst error of 9 bits or more can sneak
X    past the XMODEM protocol arithmetic checksum.
X
X    The XMODEM/CRC protocol is similar to the XMODEM protocol, except that the
X    receiver specifies CRC-16 by sending C (Hex 43) instead of NAK when
X    requesting the FIRST block.  A two byte CRC is sent in place of the one
X    byte arithmetic checksum.
X
X    YAM's c option to the r command enables CRC-16 in single file reception,
X    corresponding to the original implementation in the MODEM7 series
X    programs.  This remains the default because many commercial communications
X    programs and bulletin board systems still do not support CRC-16,
X    especially those written in Basic or Pascal.
X
X    XMODEM protocol with CRC is accurate provided both sender and receiver
X
X
X
X    Chapter 4                                     XMODEM Protocol Enhancements
X
X
X
X
X
X
X
X    X/YMODEM Protocol Reference    June 18 1988                             11
X
X
X
X    both report a successful transmission.  The protocol is robust in the
X    presence of characters lost by buffer overloading on timesharing systems.
X
X    The single character ACK/NAK responses generated by the receiving program
X    adapt well to split speed modems, where the reverse channel is limited to
X    ten per cent or less of the main channel's speed.
X
X    XMODEM and YMODEM are half duplex protocols which do not attempt to
X    transmit information and control signals in both directions at the same
X    time.  This avoids buffer overrun problems that have been reported by
X    users attempting to exploit full duplex asynchronous file transfer
X    protocols such as Blast.
X
X    Professional-YAM adds several proprietary logic enhancements to XMODEM's
X    error detection and recovery.  These compatible enhancements eliminate
X    most of the bad file transfers other programs make when using the XMODEM
X    protocol under less than ideal conditions.
X
X
X    4.3  XMODEM-1k 1024 Byte Block
X
X    Disappointing throughput downloading from Unix with YMODEM[1] lead to the
X    development of 1024 byte blocks in 1982.  1024 byte blocks reduce the
X    effect of delays from timesharing systems, modems, and packet switched
X    networks on throughput by 87.5 per cent in addition to decreasing XMODEM's
X    3 per cent overhead (block number, CRC, etc.).
X
X    Some environments cannot accept 1024 byte bursts, including some networks
X    and minicomputer ports.  The longer block length should be an option.
X
X    The choice to use 1024 byte blocks is expressed to the sending program on
X    its command line or selection menu.[2] 1024 byte blocks improve throughput
X    in many applications.
X
X    An STX (02) replaces the SOH (01) at the beginning of the transmitted
X    block to notify the receiver of the longer block length.  The transmitted
X    block contains 1024 bytes of data.  The receiver should be able to accept
X    any mixture of 128 and 1024 byte blocks.  The block number (in the second
X    and third bytes of the block) is incremented by one for each block
X    regardless of the block length.
X
X    The sender must not change between 128 and 1024 byte block lengths if it
X    has not received a valid ACK for the current block.  Failure to observe
X
X
X    __________
X
X     1. The name hadn't been coined yet, but the protocol was the same.
X
X     2. See "KMD/IMP Exceptions to YMODEM" below.
X
X
X
X
X    Chapter 4                                     XMODEM Protocol Enhancements
X
X
X
X
X
X
X
X    X/YMODEM Protocol Reference    June 18 1988                             12
X
X
X
X    this restriction allows transmission errors to pass undetected.
X
X    If 1024 byte blocks are being used, it is possible for a file to "grow" up
X    to the next multiple of 1024 bytes.  This does not waste disk space if the
X    allocation granularity is 1k or greater.  With YMODEM batch transmission,
X    the optional file length transmitted in the file name block allows the
X    receiver to discard the padding, preserving the exact file length and
X    contents.
X
X    1024 byte blocks may be used with batch file transmission or with single
X    file transmission.  CRC-16 should be used with the k option to preserve
X    data integrity over phone lines.  If a program wishes to enforce this
X    recommendation, it should cancel the transfer, then issue an informative
X    diagnostic message if the receiver requests checksum instead of CRC-16.
X
X    Under no circumstances may a sending program use CRC-16 unless the
X    receiver commands CRC-16.
X
X             Figure 1.  XMODEM-1k Blocks
X
X             SENDER                                  RECEIVER
X                                                     "sx -k foo.bar"
X             "foo.bar open x.x minutes"
X                                                     C
X             STX 01 FE Data[1024] CRC CRC
X                                                     ACK
X             STX 02 FD Data[1024] CRC CRC
X                                                     ACK
X             STX 03 FC Data[1000] CPMEOF[24] CRC CRC
X                                                     ACK
X             EOT
X                                                     ACK
X
X             Figure 2.  Mixed 1024 and 128 byte Blocks
X
X             SENDER                                  RECEIVER
X                                                     "sx -k foo.bar"
X             "foo.bar open x.x minutes"
X                                                     C
X             STX 01 FE Data[1024] CRC CRC
X                                                     ACK
X             STX 02 FD Data[1024] CRC CRC
X                                                     ACK
X             SOH 03 FC Data[128] CRC CRC
X                                                     ACK
X             SOH 04 FB Data[100] CPMEOF[28] CRC CRC
X                                                     ACK
X             EOT
X                                                     ACK
X
X
X
X
X
X    Chapter 4                                     XMODEM Protocol Enhancements
X
X
X
X
X
X
X
X    X/YMODEM Protocol Reference    June 18 1988                             13
X
X
X
X    5.  YMODEM Batch File Transmission
X
X    The YMODEM Batch protocol is an extension to the XMODEM/CRC protocol that
X    allows 0 or more files to be transmitted with a single command.  (Zero
X    files may be sent if none of the requested files is accessible.) The
X    design approach of the YMODEM Batch protocol is to use the normal routines
X    for sending and receiving XMODEM blocks in a layered fashion similar to
X    packet switching methods.
X
X    Why was it necessary to design a new batch protocol when one already
X    existed in MODEM7?[1] The batch file mode used by MODEM7 is unsuitable
X    because it does not permit full pathnames, file length, file date, or
X    other attribute information to be transmitted.  Such a restrictive design,
X    hastily implemented with only CP/M in mind, would not have permitted
X    extensions to current areas of personal computing such as Unix, DOS, and
X    object oriented systems.  In addition, the MODEM7 batch file mode is
X    somewhat susceptible to transmission impairments.
X
X    As in the case of single a file transfer, the receiver initiates batch
X    file transmission by sending a "C" character (for CRC-16).
X
X    The sender opens the first file and sends block number 0 with the
X    following information.[2]
X
X    Only the pathname (file name) part is required for batch transfers.
X
X    To maintain upwards compatibility, all unused bytes in block 0 must be set
X    to null.
X
X    Pathname The pathname (conventionally, the file name) is sent as a null
X         terminated ASCII string.  This is the filename format used by the
X         handle oriented MSDOS(TM) functions and C library fopen functions.
X         An assembly language example follows:
X                                  DB      'foo.bar',0
X         No spaces are included in the pathname.  Normally only the file name
X         stem (no directory prefix) is transmitted unless the sender has
X         selected YAM's f option to send the full pathname.  The source drive
X         (A:, B:, etc.) is not sent.
X
X         Filename Considerations:
X
X
X
X    __________
X
X     1. The MODEM7 batch protocol transmitted CP/M FCB bytes f1...f8 and
X        t1...t3 one character at a time.  The receiver echoed these bytes as
X        received, one at a time.
X
X     2. Only the data part of the block is described here.
X
X
X
X
X    Chapter 5                                     XMODEM Protocol Enhancements
X
X
X
X
X
X
X
X    X/YMODEM Protocol Reference    June 18 1988                             14
X
X
X
X            + File names are forced to lower case unless the sending system
X              supports upper/lower case file names.  This is a convenience for
X              users of systems (such as Unix) which store filenames in upper
X              and lower case.
X
X            + The receiver should accommodate file names in lower and upper
X              case.
X
X            + When transmitting files between different operating systems,
X              file names must be acceptable to both the sender and receiving
X              operating systems.
X
X         If directories are included, they are delimited by /; i.e.,
X         "subdir/foo" is acceptable, "subdir\foo" is not.
X
X    Length The file length and each of the succeeding fields are optional.[3]
X         The length field is stored in the block as a decimal string counting
X         the number of data bytes in the file.  The file length does not
X         include any CPMEOF (^Z) or other garbage characters used to pad the
X         last block.
X
X         If the file being transmitted is growing during transmission, the
X         length field should be set to at least the final expected file
X         length, or not sent.
X
X         The receiver stores the specified number of characters, discarding
X         any padding added by the sender to fill up the last block.
X
X    Modification Date The mod date is optional, and the filename and length
X         may be sent without requiring the mod date to be sent.
X
X         Iff the modification date is sent, a single space separates the
X         modification date from the file length.
X
X         The mod date is sent as an octal number giving the time the contents
X         of the file were last changed, measured in seconds from Jan 1 1970
X         Universal Coordinated Time (GMT).  A date of 0 implies the
X         modification date is unknown and should be left as the date the file
X         is received.
X
X         This standard format was chosen to eliminate ambiguities arising from
X         transfers between different time zones.
X
X
X
X
X
X    __________
X
X     3. Fields may not be skipped.
X
X
X
X
X    Chapter 5                                     XMODEM Protocol Enhancements
X
X
X
X
X
X
X
X    X/YMODEM Protocol Reference    June 18 1988                             15
X
X
X
X    Mode Iff the file mode is sent, a single space separates the file mode
X         from the modification date.  The file mode is stored as an octal
X         string.  Unless the file originated from a Unix system, the file mode
X         is set to 0.  rb(1) checks the file mode for the 0x8000 bit which
X         indicates a Unix type regular file.  Files with the 0x8000 bit set
X         are assumed to have been sent from another Unix (or similar) system
X         which uses the same file conventions.  Such files are not translated
X         in any way.
X
X
X    Serial Number Iff the serial number is sent, a single space separates the
X         serial number from the file mode.  The serial number of the
X         transmitting program is stored as an octal string.  Programs which do
X         not have a serial number should omit this field, or set it to 0.  The
X         receiver's use of this field is optional.
X
X
X    Other Fields YMODEM was designed to allow additional header fields to be
X         added as above without creating compatibility problems with older
X         YMODEM programs.  Please contact Omen Technology if other fields are
X         needed for special application requirements.
X
X    The rest of the block is set to nulls.  This is essential to preserve
SHAR_EOF
  : || echo 'restore of xmodem/ymodem.doc failed'
fi
echo 'End of xmodem part 4'
echo 'File xmodem/ymodem.doc is continued in part 5'
echo 5 > _sharseq.tmp
exit 0