rz.doc

     RRRRZZZZ((((1111))))		OOOOmmmmeeeennnn TTTTeeeecccchhhhnnnnoooollllooooggggyyyy	IIIINNNNCCCC ((((OOOOMMMMEEEENNNN))))		 RRRRZZZZ((((1111))))



     NNNNAAAAMMMMEEEE
	  rx, rc, rb, rz - Receive Files and Commands with X/Y/ZMODEM

     SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
	  rrrrzzzz [-vvvv] [-wwwwWWWWIIIINNNNDDDDOOOOWWWW] [-ttttTTTTIIIIMMMMEEEEOOOOUUUUTTTT]
	  rrrrbbbb [-vvvvyyyy] [-ttttTTTTIIIIMMMMEEEEOOOOUUUUTTTT]
	  rrrrcccc [-vvvvyyyy] [-ttttTTTTIIIIMMMMEEEEOOOOUUUUTTTT] _f_i_l_e
	  rrrrxxxx [-vvvvyyyy] [-ttttTTTTIIIIMMMMEEEEOOOOUUUUTTTT] _f_i_l_e
	  ggggzzzz _f_i_l_e ...

     LLLLIIIICCCCEEEENNNNSSSSEEEE AAAAGGGGRRRREEEEEEEEMMMMEEEENNNNTTTT
	  This is a Copyrighted	shareware program.  Commercial use of
	  this program is subject to licensing conditions detailed in
	  the rz.c source code.	 "Commercial Use" includes any use of
	  this program to receive files	from a commercial or shareware
	  program not published	by Omen	Technology INC.

	  Registration information is provided in the file mailer.rz.

	  Use of this program constitutes agreement to the License
	  Agreement.

	  Please check http://www.omen.com for more information.

     SSSSUUUUPPPPPPPPOOOORRRRTTTT
	  Users	who have not purchased support as part of their
	  registration may call	503-614-0430 to	arrange	for technical
	  support on a consulting basis.

	  Registered users encountering	problems using this program on
	  standard serial ports	to transfer files with Professional-
	  YAM or ZCOMM may call	the support number listed in the
	  Professional-YAM/ZCOMM documentation.	 Solutions to nearly
	  all file transfer problems are described in the
	  Professional-YAM/ZCOMM documentation.

     DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
	  This program uses error correcting protocols to receive
	  files	over a dial-in serial port from	a variety of programs
	  running under	PC-DOS,	CP/M, Unix, and	other operating
	  systems.  It is invoked from a shell prompt manually,	or
	  automatically	as a result of an "sz file ..."	command	given
	  to the calling program.

	  To obtain the	maximum	performance and	full functionality of
	  this program we recommend its	use with GSZ, Professional-YAM
	  or ZCOMM.

	  This program is intended to act as a server for terminal
	  programs, not	to act as one.	This program is	not designed
	  to be	called from _c_u(_1), _t_i_p(_1), or other communications
	  programs.  Unix flavors of Omen Technology's Professional-



     Page 1					     (printed 1/27/98)






     RRRRZZZZ((((1111))))		OOOOmmmmeeeennnn TTTTeeeecccchhhhnnnnoooollllooooggggyyyy	IIIINNNNCCCC ((((OOOOMMMMEEEENNNN))))		 RRRRZZZZ((((1111))))



	  YAM communications software are suitable for dial-out
	  applications.	 Unix Professional-YAM supports	dial-out
	  applications with telephone directory, a powerful script
	  language with	learn function,	high quality multiple protocol
	  support, and UUCP port arbitration.


	  RRRRzzzz (Receive ZMODEM) receives one or more files with the
	  ZMODEM protocol.  Pathnames are supplied by the sending
	  program, and directories are created if necessary.  (See the
	  example below.) if standard output is	not redirected to a
	  file or pipe,	output is appended to a	file named "stdout".

	  Normally, the	"rz" command is	automatically issued by	the
	  calling ZMODEM program, but defective	ZMODEM implementations
	  may require starting _r_z manually.

	  RRRRbbbb receives file(s) with YMODEM, accepting either standard
	  128 byte sectors or 1024 byte	sectors	(Pro-YAM/ZCOMM sb ----kkkk
	  option).  The	user should determine when the 1024 byte block
	  length actually improves throughput.

	  If True YMODEM (Omen Technology trademark) file information
	  (file	length,	etc.) is received, the file length controls
	  the number of	bytes written to the output dataset and	the
	  modify time (iff non zero) are set accordingly.

	  If True YMODEM file information is not received, slashes in
	  the pathname are changed to underscore, and any trailing
	  period in the	pathname is eliminated.	 This conversion is
	  useful for files received from CP/M and other	historical
	  systems.

	  RRRRcccc receives a	single _f_i_l_e with XMODEM-CRC or XMODEM-1k-CRC
	  protocol.  The user should determine when the	1024 byte
	  block	length actually	improves throughput without causing
	  problems.  The user must supply the file name	to both
	  sending and receiving	programs.  Up to 1023 garbage
	  characters may be added to the received file.

	  RRRRxxxx receives a	single _f_i_l_e with XMODEM	or XMODEM-1k protocol.
	  The user should determine when the 1024 byte block length
	  actually improves throughput without causing problems.  The
	  user must supply the file name to both sending and receiving
	  programs.  Up	to 1023	garbage	characters may be added	to the
	  received file.

	  GGGGzzzz is	a shell	script which calls _s_z to command Pro-YAM or
	  ZCOMM	to transmit the	specified files.  Pathnames used with
	  _g_z must be escaped if	they have special significance to the
	  Unix shell.
	  EXAMPLE: gz "-a C:*.c	D:*.h"



     Page 2					     (printed 1/27/98)






     RRRRZZZZ((((1111))))		OOOOmmmmeeeennnn TTTTeeeecccchhhhnnnnoooollllooooggggyyyy	IIIINNNNCCCC ((((OOOOMMMMEEEENNNN))))		 RRRRZZZZ((((1111))))



	  If invoked with a leading ``v'', _r_z will report progress to
	  /tmp/rzlog.
	  EXAMPLE: ln rz vrz; rz=vrz; export rz

	  If the RESTRICTED shell environment variable is set to 1, or
	  if the SHELL environment variable includes _r_s_h or _r_k_s_h
	  (restricted shell), registered copies	of _r_z will not accept
	  command uploads, absolute pathnames, references to a parent
	  directory, will not modify an	existing file, and removes any
	  files	received in error.
	  EXAMPLE: RESTRICTED=1	rz


	  The meanings of the available	options	are:

	  ttttTTTTIIIIMMMMEEEEOOOOUUUUTTTT
	       Change TIMEOUT to _T_I_M_E_O_U_T tenths	of seconds.
	  vvvv    Verbose causes a	list of	file names to be appended to
	       /tmp/rzlog .  More v's generate more detailed debugging
	       output.
	  wwwwWWWWIIIINNNNDDDDOOOOWWWW
	       Use a receive window of WINDOW bytes.  Details in the
	       Professional-YAM	user manual.
	  (Pro-YAM command)
	  <_A_L_T-_2>
	  Pro-YAM Command: _s_z *._h *._c
	  This automatically invokes _r_z	on the connected system, and
	  sends	all .h and .c files in the current directory.

	  _s_z -_n	-_R_f .
	  This Professional-YAM	command	recursively follows the
	  current directory tree (.) (Pro-YAM -R option), sends	the
	  full relative	pathname (-f), for files that are newer	(-n)
	  than their copies on the destination system.

	  _r_z | _s_o_r_t >/_t_m_p/_s_o_r_t_e_d
	  _s_z _O_N_A_M_E=- *._l_s_t
	  The first command manually starts rrrrzzzz with output piped to
	  the sort command.  The second	command	instructs
	  Professional-YAM, ZCOMM, GSZ or DSZ to sene the files	using
	  "-" as pathname, which instructs rrrrzzzz to output	the received
	  data to its standard output.	The end	result is a single
	  file containing all the lines	of the .lst files sorted
	  alphabetically.



     DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
	  Exit status is as follows: 0 for successful transfers.  1 if
	  unrecoverable	errors are detected.  2	if syntax errors or
	  file access problems are detected.  3	if the program was
	  terminated by	a caught interrupt.



     Page 3					     (printed 1/27/98)






     RRRRZZZZ((((1111))))		OOOOmmmmeeeennnn TTTTeeeecccchhhhnnnnoooollllooooggggyyyy	IIIINNNNCCCC ((((OOOOMMMMEEEENNNN))))		 RRRRZZZZ((((1111))))



     SSSSEEEEEEEE AAAALLLLSSSSOOOO
	  Professional-YAM, ZCOMM, DSZ,	crc(omen), sz(omen),
	  usq(omen), undos(omen)

	  Compile time options required	for various operating systems
	  are described	in the source file.

     SSSSEEEERRRRVVVVEEEERRRR////NNNNEEEETTTTWWWWOOOORRRRKKKK NNNNOOOOTTTTEEEESSSS
	  Terminals on some timesharing	systems	are connected
	  indirectly to	the host with TTTTEEEERRRRMMMMIIIINNNNAAAALLLL SSSSEEEERRRRVVVVEEEERRRRSSSS operating over
	  networks.  Terminal servers often interfere with file
	  transfers by "eating"	control	characters and/or losing data.

	  Accessing a distant system using tttteeeellllnnnneeeetttt on a local Unix
	  system entails the same problems.  If	tttteeeellllnnnneeeetttt does not	work
	  well,	try rrrrllllooooggggiiiinnnn with	the ----8888 option.	Set the	escape
	  character to ^P (control P) which is protected by ZMODEM.

	  When terminal	servers	interfere with file transfers, server
	  commands are often available to help the problem.  When
	  possible, enable the server and modems for hardware flow
	  control in and out.  Set the terminal	server to telnet
	  transparent mode.  Some typical commands are "SET TERMINAL
	  DOWNLOAD", "set session passall", and	"SET TERMINAL NO ESC",
	  but there is no standard set of commands suitable for	all
	  terminal servers.  Normally these commands are given before
	  attempting file transfers, but one user has reported that
	  the command must be given _a_f_t_e_r the file transfer is
	  started(!).  Until terminal server vendors improve the
	  quality of their product, you	may have to get	on their case
	  until	they adequately	support	high performance file
	  transfers.

	  The telnet protcol used by the _t_e_l_n_e_t	program	and terminal
	  servers uses 0xFF (377 octal)	for special control functions.
	  The 0xFF character may cause problems	if it appears in the
	  data stream, especially uploading at high speeds.  With
	  ZCOMM	or Professional-YAM the	0xFF character can be
	  protected by giving the command:
	  set zmtxesc ?

	  Escaping control characters with ZMODEM (sz -e) may help if
	  the transfer gets stuck in the same place on every attempt.
	  Professional-YAM and ZCOMM allow selection of	which control
	  characters need to be	escaped.  In extreme cases 7-bit
	  transmission may be required (see the	Professional-YAM/ZCOMM
	  manual).  If you encounter problems with control characters
	  you should identify which control characters are causing the
	  problem.  Please refer to the	sz -T command in sz.doc	for
	  more help.

	  Flow control between the server and modem is often



     Page 4					     (printed 1/27/98)






     RRRRZZZZ((((1111))))		OOOOmmmmeeeennnn TTTTeeeecccchhhhnnnnoooollllooooggggyyyy	IIIINNNNCCCC ((((OOOOMMMMEEEENNNN))))		 RRRRZZZZ((((1111))))



	  defective.  This rarely causes a problem in interactive
	  applications whose short bursts (a screenfull	at most) fit
	  within the available memory buffers.	Streaming protocols
	  such as YMODEM-g, long packet	SuperKermit, and ZMODEM	can
	  overload the available buffering.  Some terminal servers
	  support commands to enable hardware flow control such	as
	  "TERM	FLOWCONTROL HARDWARE IN	OUT"; this assumes the modem
	  attached to the server is properly configured.

	  If the terminal server is too	brain damaged to support flow
	  control, ZMODEM lets you fake	it by setting a	window size.
	  Try
	       sz -w2048 file...
	  to enable software flow control.  Experiment with different
	  window sizes for best	results.

	  Terminal servers are designed	to accept keyboard input from
	  human	operators.  They may lose data when a program sends
	  more data to the host	faster than humans type.  Some servers
	  allow	larger input buffers to	support	file uploads.  If you
	  can upload short files (less than 100	bytes) but not longer
	  files, try
	       sz -w1024 file...
	  with your uploading program.	(Not all programs support this
	  option; use ZCOMM or Professional-YAM.)

	  When both flow control and character transparency are
	  problems, use
	       sz -ew1024 file...
	  as a starting	point.

	  Sometimes the	terminal server	software is defective and must
	  be corrected.	 Please	contact	the network's vendor for
	  corrective procedures.  An alternative is to install direct
	  serial ports for users desiring to upload files.

	  We have also encountered problems when networking software
	  fails	to pass	data after a large amount of data has been
	  sent to the host.  This has happened on a PPP	internet
	  connection which prevented uploads of	large amounts of data
	  via either FTP or a ZMODEM upload (via TELNET).  The PPP
	  connection grinds to a standstill and	not even PING works.
	  The same ZMODEM/TELNET combination easily uploaded ten times
	  as much to a nearby machine connected	by Ethernet.


     PPPPOOOORRRRTTTT WWWWAAAATTTTCCCCHHHHEEEERRRRSSSS
	  Some systems enforce a timeout which disconnects a user
	  after	several	minutes	of keyboard inactivity.	 Long, error
	  free ZMODEM transfers	do not generate	keyboard activity
	  (this	is why ZMODEM is so efficient).	 Restricting the
	  window size with



     Page 5					     (printed 1/27/98)






     RRRRZZZZ((((1111))))		OOOOmmmmeeeennnn TTTTeeeecccchhhhnnnnoooollllooooggggyyyy	IIIINNNNCCCC ((((OOOOMMMMEEEENNNN))))		 RRRRZZZZ((((1111))))



	       sz -w16384 file...
	  option generates terminal input at regular intervals even
	  when no error	correction is needed.  If problems persist,
	  try setting a	packet length.
	       sz -l1024 file...
	  (The default ZMODEM packet length is the file	length.)

     NNNNOOOOTTTTEEEESSSS
	  RRRRzzzz,,,, rrrrbbbb,,,, (Reg.)and rrrrxxxx are hard	links to the rz	executable.
	  These	links are automatically	made by	the Makefile.

	  ZMODEM's support of XOFF/XON flow control allows proper
	  operation in many environments that do not support XMODEM
	  uploads.  Unfortunately, not all Unix	versions support input
	  flow control.	 The TTY input buffering on some systems may
	  not adequately buffer	long blocks or streaming input at high
	  speed.  You should suspect this problem when you can't send
	  data to the Unix system at high speeds using ZMODEM,
	  YMODEM-1k or XMODEM-1k, but YMODEM with 128 byte blocks
	  works	properly.

	  The DSZ or Pro-YAM zzzzmmmmooooddddeeeemmmm llll numeric parameter	may be set to
	  a value between 64 and 1024 to limit the burst length
	  ("zmodem pl128").  Although this compromises ZMODEM's
	  throughput, ZMODEM's superior	reliability remains intact.

	  If a program that does not properly implement	the specified
	  file transfer	protocol causes	_r_z to "hang" the port after a
	  failed transfer, either wait for _r_z to time out or keyboard
	  a dozen Ctrl-X characters.  Every reported instance of this
	  problem has been corrected by	using ZCOMM, Pro-YAM, DSZ, or
	  other	program	with a correct implementation of the specified
	  protocol.

	  Many programs	claiming to support YMODEM only	support	XMODEM
	  with 1k blocks, and they often don't get that	quite right.

	  In the case of a few poorly designed microcomputers, sending
	  serial data to a tty port at sustained high speeds has been
	  known	to cause lockups, system halts,	kernel panics, and
	  occasional antisocial	behaviour.  This problem is not	unique
	  to _r_z; newer versions	of Kermit, CRT terminals with screen
	  transmission,	and line noise have the	same effect.  When
	  experimenting	with high speed	input to a system, consider
	  rebooting the	system if the file transfers are not
	  successful, especially if the	personality of the system
	  appears altered.

	  The Unix "ulimit" parameter must be set high enough to
	  permit large file transfers to Unix.

	  Telebit modems must not be set to "spoof" UUCP, XMODEM,



     Page 6					     (printed 1/27/98)






     RRRRZZZZ((((1111))))		OOOOmmmmeeeennnn TTTTeeeecccchhhhnnnnoooollllooooggggyyyy	IIIINNNNCCCC ((((OOOOMMMMEEEENNNN))))		 RRRRZZZZ((((1111))))



	  YMODEM, or KERMIT.  Setting one of these spoofing modes
	  interferes with other	protocols.  Telebit's YMODEM spoofing
	  interferes with YMODEM transfers.

	  32 bit CRC code courtesy Gary	S. Brown.  Directory creation
	  code from John Gilmore's PD TAR program.

     NNNNEEEETTTTWWWWOOOORRRRKKKK NNNNOOOOTTTTEEEESSSS
	  Escaping all control characters (sz -e) may help if the
	  transfer gets	stuck in the same place	on every attempt.
	  Professional-YAM and ZCOMM allow selection of	which control
	  characters need to be	escaped.

	  In extreme cases 7-bit transmission may be required (see
	  Professional-YAM/ZCOMM manual).  7-bit transmission requires
	  rz version 4.50 or higher.

	  Please refer to the sz -T command in sz.doc for more help.

     BBBBUUUUGGGGSSSS
	  This version of _r_z does not support some ZMODEM features.
	  Unix flavors of Professional-YAM may be linked to "rz" to
	  support these	features.

	  The ASCII option's CR/LF to NL translation merely deletes
	  CR's;	undos(omen) performs a more intelligent	translation.

     ZZZZMMMMOOOODDDDEEEEMMMM CCCCAAAAPPPPAAAABBBBIIIILLLLIIIITTTTIIIIEEEESSSS
	  _R_z supports ZMODEM command execution (zcommand), incoming
	  ZMODEM binary	(-b), ASCII (-a), escape controls (-e),
	  newer(-n), newer+longer(-N), protect (-p), Crash Recovery(-
	  r), clobber (-y), match+clobber (-Y),	compression(-Z), and
	  append (-+) requests.	 Other options sent by the sender are
	  ignored.  Crash recovery (-r)	cannot be combined with	other
	  options.  The	default	is protect (-p)	and binary (-b).

	  Unix Professional-YAM	provides higher	performance and	other
	  features not supported by _r_z.	Please contact Omen Technology
	  Inc for product information.

	  http://www.omen.com

	  Omen Technology INC
	  Post Office Box 4681
	  Portland OR 97208
	  503-614-0430 (Sales)


     FFFFIIIILLLLEEEESSSS
	  rz.c,	crctab.c, rbsb.c, zm.c,	zmr.c, zmodem.h, rz.1

	  /tmp/rzlog stores debugging output generated with -vv	option



     Page 7					     (printed 1/27/98)