RZ(1) Omen Technology INC (OMEN) RZ(1)
NAME
rx, rc, rb, rz - Receive Files and Commands with X/Y/ZMODEM
SYNOPSIS
rz [-v] [-wWINDOW] [-tTIMEOUT]
rb [-vy] [-tTIMEOUT]
rc [-vy] [-tTIMEOUT] file
rx [-vy] [-tTIMEOUT] file
gz file ...
LICENSE AGREEMENT
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.
SUPPORT
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.
DESCRIPTION
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 cu(1), tip(1), or other communications
programs. Unix flavors of Omen Technology's Professional-
Page 1 (printed 1/27/98)
RZ(1) Omen Technology INC (OMEN) RZ(1)
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.
Rz (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 rz manually.
Rb receives file(s) with YMODEM, accepting either standard
128 byte sectors or 1024 byte sectors (Pro-YAM/ZCOMM sb -k
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.
Rc receives a single file 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.
Rx receives a single file 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.
Gz is a shell script which calls sz to command Pro-YAM or
ZCOMM to transmit the specified files. Pathnames used with
gz 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)
RZ(1) Omen Technology INC (OMEN) RZ(1)
If invoked with a leading ``v'', rz 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 rsh or rksh
(restricted shell), registered copies of rz 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:
tTIMEOUT
Change TIMEOUT to TIMEOUT tenths of seconds.
v Verbose causes a list of file names to be appended to
/tmp/rzlog . More v's generate more detailed debugging
output.
wWINDOW
Use a receive window of WINDOW bytes. Details in the
Professional-YAM user manual.
(Pro-YAM command)
<ALT-2>
Pro-YAM Command: sz *.h *.c
This automatically invokes rz on the connected system, and
sends all .h and .c files in the current directory.
sz -n -Rf .
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.
rz | sort >/tmp/sorted
sz ONAME=- *.lst
The first command manually starts rz 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 rz 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.
DIAGNOSTICS
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)
RZ(1) Omen Technology INC (OMEN) RZ(1)
SEE ALSO
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.
SERVER/NETWORK NOTES
Terminals on some timesharing systems are connected
indirectly to the host with TERMINAL SERVERS operating over
networks. Terminal servers often interfere with file
transfers by "eating" control characters and/or losing data.
Accessing a distant system using telnet on a local Unix
system entails the same problems. If telnet does not work
well, try rlogin with the -8 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 after 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 telnet 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)
RZ(1) Omen Technology INC (OMEN) RZ(1)
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.
PORT WATCHERS
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)
RZ(1) Omen Technology INC (OMEN) RZ(1)
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.)
NOTES
Rz, rb, (Reg.)and rx 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 zmodem l 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 rz to "hang" the port after a
failed transfer, either wait for rz 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 rz; 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)
RZ(1) Omen Technology INC (OMEN) RZ(1)
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.
NETWORK NOTES
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.
BUGS
This version of rz 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.
ZMODEM CAPABILITIES
Rz 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 rz. 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)
FILES
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)
