SZ(1) Omen Technology INC (OMEN) SZ(1)
NAME
sx, sb, sz - Send Files with ZMODEM, YMODEM, or XMODEM
zcommand, zcommandi - Send Commands with ZMODEM
SYNOPSIS
sz [-+abdefkLlNnoptuvxyYZ] file ...
sb [-dfktuv] file ...
sx [-ktuv] file
zcommand [-otv] COMMAND
zcommandi [-otv] COMMAND
sz -T
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 send files to a commercial or shareware
program not published or licensed 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
Sz (send ZMODEM) uses the ZMODEM, YMODEM or XMODEM error
correcting protocol to send one or more files over a dial-in
serial port to a variety of programs running under PC-DOS,
CP/M, Unix, VMS, and other operating systems.
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
Page 1 (printed 1/27/98)
SZ(1) Omen Technology INC (OMEN) SZ(1)
programs. Unix flavors of Omen Technology's Professional-
YAM communications software are available 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.
Sz sends one or more files with ZMODEM protocol.
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 complete END-TO-END data integrity between
application programs. ZMODEM's 32 bit CRC catches errors
that sneak into even the most advanced networks.
Advanced file management features include AutoDownload
(Automatic file Download initiated without user
intervention), Display of individual and total file lengths
and transmission time estimates, Crash Recovery, selective
file transfers, and preservation of exact file date and
length.
The -y option instructs the receiver to open the file for
writing unconditionally. The -a option causes the receiver
to convert Unix newlines to PC-DOS carriage returns and
linefeeds.
Sb sends one or more files with YMODEM or ZMODEM protocol.
The initial ZMODEM initialization is not sent. When
requested by the receiver, sb supports YMODEM-g with
"cbreak" tty mode, XON/XOFF flow control, and interrupt
character set to CAN (^X). YMODEM-g (Professional-YAM g
option) increases YMODEM throughput over error free channels
(direct connection, X.PC, etc.) by disabling error recovery.
On Unix systems, additional information about the file is
transmitted. If the receiving program uses this
information, the transmitted file length controls the exact
number of bytes written to the output dataset and the modify
time are set accordingly.
Sx sends a single file with XMODEM or XMODEM-1k protocol
(sometimes incorrectly called "ymodem"). The user must
supply the file name to both sending and receiving programs.
Iff sz is invoked with $SHELL set and iff that variable
contains the string rsh or rksh (restricted shell), sz
Page 2 (printed 1/27/98)
SZ(1) Omen Technology INC (OMEN) SZ(1)
operates in restricted mode. Restricted mode restricts
pathnames to the current directory and PUBDIR (usually
/usr/spool/uucppublic) and/or subdirectories thereof.
The fourth form sends a single COMMAND to a ZMODEM receiver
for execution. Zcommand exits with the COMMAND return
value. If COMMAND includes spaces or characters special to
the shell, it must be quoted.
The fifth form sends a single COMMAND to a ZMODEM receiver
for execution. Zcommandi exits as soon as the receiver has
correctly received the command, before it is executed.
The sixth form (sz -T) outputs all 256 code combinations to
the terminal. The hex value of the character, a space, and
the raw character are sent, 8 per line. In you are having
difficulty sending files, this command lets you see which
character codes are being eaten by the operating system or
network. The terminal program must be set to display all
256 codes in a distinct form. Check that each code is sent,
and that the 8th bit on codes 0x80 to 0xFF is set.
Sz -T then allows the caller to input characters which are
echoed in hex. You should check that all control characters
can be input this way.
The meanings of the available options are:
+ Instruct the receiver to append transmitted data to an
existing file (ZMODEM only).
a Instruct the ZMODEM receiver to convert text file
format as appropriate for the receiving system. Valid
only for ZMODEM.
b (ZMODEM) Binary override: transfer file without any
translation.
c Instruct the receiver to change the pathname if the
destination file exists.
d Change all instances of "." to "/" in the transmitted
pathname. Thus, C.omenB0000 (which is unacceptable to
MSDOS or CP/M) is transmitted as C/omenB0000. If the
resultant filename has more than 8 characters in the
stem, a "." is inserted to allow a total of eleven.
e Escape all control characters and the all ones
character (0xFF); normally only XON, XOFF, and Ctrl-X
are escaped.
f Send Full pathname. Normally directory prefixes are
stripped from the transmitted filename.
Page 3 (printed 1/27/98)
SZ(1) Omen Technology INC (OMEN) SZ(1)
g Send ESC-[-?-3-4-l to start DSZ from Kermit.
k (XMODEM/YMODEM) Send files using 1024 byte blocks
rather than the default 128 byte blocks. 1024 byte
packets speed file transfers at high bit rates.
(ZMODEM streams the data for the best possible
throughput.)
LN Use ZMODEM sub-packets of length N. A larger N (32 <=
N <= 1024) gives slightly higher throughput, a smaller
N speeds error recovery. The default is 128 below 300
baud, 256 above 300 baud, or 1024 above 2400 baud.
lN Wait for the receiver to acknowledge correct data every
N (32 <= N) characters. This may be used to avoid
network overrun when XOFF flow control is lacking.
n (ZMODEM) Send each file if destination file does not
exist. Overwrite destination file if source file is
newer than the destination file.
N (ZMODEM) Send each file if destination file does not
exist. Overwrite destination file if source file is
newer or longer than the destination file.
o (ZMODEM) Disable automatic selection of 32 bit CRC.
p (ZMODEM) Protect existing destination files by skipping
transfer if the destination file exists.
r (ZMODEM) Resume interrupted file transfer. If the
source file is longer than the destination file, the
transfer commences at the offset in the source file
that equals the length of the destination file.
rr As above, but compares the files (the portion common to
sender and receiver) before resuming the transfer.
ttim Change timeout to tim tenths of seconds.
u Unlink the file after successful transmission. Users
should not manually abort or skip file transfers when
this option is used.
wN Limit the transmit window size to N bytes (ZMODEM).
v Verbose causes a list of file names to be appended to
/tmp/szlog . More v's generate more output.
x Count skipped files as errors.
y Instruct a ZMODEM receiving program to overwrite any
existing file with the same name.
Y Instruct a ZMODEM receiving program to overwrite any
existing file with the same name, and to skip any
source files that do have a file with the same pathname
on the destination system.
Z Use ZMODEM file compression to speed file transfer.
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.
EXAMPLES
Page 4 (printed 1/27/98)
SZ(1) Omen Technology INC (OMEN) SZ(1)
ZMODEM File Transfer (Unix to DSZ/ZCOMM/Professional-YAM)
% sz -a *.c
This single command transfers all .c files in the current
Unix directory with conversion (-a) to end of line
conventions appropriate to the receiving environment. With
ZMODEM AutoDownload enabled, Professional-YAM and ZCOMM
will automatically receive the files after performing a
security check.
% sz -Yan *.c *.h
Send only the .c and .h files that exist on both systems,
and are newer on the sending system than the corresponding
version on the receiving system, converting Unix to DOS text
format.
ZMODEM Command Download (Unix to Professional-YAM)
cpszall:all
zcommand "c:;cd /yam/dist"
sz -ya $(YD)/*.me
sz -yb y*.exe
zcommand "cd /yam"
zcommandi "!insms"
This Makefile fragment uses zcommand to issue commands to
Professional-YAM to change current disk and directory.
Next, sz transfers the .me files from the $YD directory,
commanding the receiver to overwrite the old files and to
convert from Unix end of line conventions to PC-DOS
conventions. The third line transfers some .exe files. The
fourth and fifth lines command Pro-YAM to change directory
and execute a PC-DOS batch file insms . Since the batch file
takes considerable time, the zcommandi form is used to allow
the program to exit immediately.
XMODEM File Transfer (Unix to Crosstalk)
% sx foo.c
ESC
rx foo.c
The above three commands transfer a single file from Unix to
a PC and Crosstalk. This combination is much slower and
less reliable than ZMODEM.
ERROR MESSAGES
"Caught signal 99" indicates the program was not properly
compiled, refer to "bibi(99)" in rbsb.c for details.
SEE ALSO
rz(omen), ZCOMM User's Manual, Professional-YAM User's
Manual, crc(omen), sq(omen), todos(omen), tocpm(omen),
tomac(omen), yam(omen)
Compile time options required for various operating systems
are described in the source file.
Page 5 (printed 1/27/98)
SZ(1) Omen Technology INC (OMEN) SZ(1)
FILES
32 bit CRC code courtesy Gary S. Brown.
sz.c, crctab.c, rbsb.c, zm.c, zmr.c, zmodem.h Unix source
files
/tmp/szlog stores debugging output (sz -vv)
TESTING FEATURE
The command "sz -T file" exercises the Attn sequence error
recovery by commanding errors with unterminated packets.
The receiving program should complain five times about
binary data packets being too long. Each time sz is
interrupted, it should send a ZDATA header followed by
another defective packet. If the receiver does not detect
five long data packets, the Attn sequence is not
interrupting the sender, and the Myattn string in sz.c must
be modified.
After 5 packets, sz stops the "transfer" and prints the
total number of characters "sent" (Tcount). The difference
between Tcount and 5120 represents the number of characters
stored in various buffers when the Attn sequence is
generated.
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
Page 6 (printed 1/27/98)
SZ(1) Omen Technology INC (OMEN) SZ(1)
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
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
Page 7 (printed 1/27/98)
SZ(1) Omen Technology INC (OMEN) SZ(1)
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
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
Sz, sb, sx, (Reg.)and zcommand are hard links to the
compiled sz program. These links are generated by the
Makefile.
Sz is now compiled with internal buffering to allow sending
datasets piped to its standard input (286 version excluded).
ps -ef | sz -
The file is sent as "szPID" where PID is the process ID of
sending sz.
Particular attention must be paid to flow control. The
modem and Unix must agree on the flow control method. Sz
does not set or reset flow control modes (if any). Most
Unix systems use XON/XOFF ("software") flow control.
Telebit modems must not be set to "spoof" UUCP, XMODEM,
YMODEM, or KERMIT. Setting one of these spoofing modes
interferes with other protocols. Telebit's YMODEM spoofing
interferes with YMODEM transfers.
If a program that does not properly implement the specified
file transfer protocol causes sb to "hang" the port after a
failed transfer, either wait for sb 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
Page 8 (printed 1/27/98)
SZ(1) Omen Technology INC (OMEN) SZ(1)
protocol.
Many programs claiming to support YMODEM only support XMODEM
with 1k blocks, and they often don't get that quite right.
XMODEM transfers add up to 127 garbage bytes per file.
XMODEM-1k and YMODEM-1k transfers use 128 byte blocks to
avoid extra padding.
YMODEM programs use the file length transmitted at the
beginning of the transfer to prune the file to the correct
length; this may cause problems with source files that grow
during the course of the transfer. This problem does not
pertain to ZMODEM transfers, which preserve the exact file
length unconditionally.
Most ZMODEM options are merely passed to the receiving
program; some programs do not implement all of these
options.
Circular buffering and a ZMODEM sliding window should be
used when input is from pipes instead of acknowledging
frames each 1024 bytes. If no files can be opened, sz sends
a ZMODEM command to echo a suitable complaint; perhaps it
should check for the presence of at least one accessible
file before getting hot and bothered.
Unix Professional-YAM provides higher performance and other
features not supported by sz. 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)
BUGS
Some third party software packages do not properly implement
the ZMODEM protocol. This often causes problems when users
attempt to use the -a or other options.
On at least one BSD system, sz would abend it got within a
few kilobytes of the end of file.
Using the "-w8192" option fixed the problem. The real cause
is unknown, perhaps a bug in the kernel TTY output routines.
The test mode leaves a zero length file on the receiving
system.
Page 9 (printed 1/27/98)
