Share Gallery 1/share_gal_1.zip/share_gal_1/CO/CO004.ZIP/SZ.ZIP/ZMODEM.TXT

Text File | 1987-10-23 | 17KB | 541 lines

RZ

NAME

rx, rb, rz - XMODEM, YMODEM, ZMODEM (Batch) file receive

SYNOPSIS
rz [- " +1abepqtuv" ]

rb [- " +1abqtuv" ]

rz [- " 1abceqtuv" ] file

gz "file ..." [ - ][ v ] rzCOMMAND

DESCRIPTION

This program uses error correcting protocol to receive files over a
serial port from a variety of programs running under PC-DOS, CP/M, Unix,
and other operating systems.

The first form of rz (Receive ZMODEM) receives files with the ZMODEM
batch protocol.  If the sending program does not support ZMODEM, rz
steps down to YMODEM protocol after 50 seconds.  This delay can be
eliminated by invoking the program as rb.

When receiving with XMODEM or YMODEM, Rz accepts either standard 128
byte sectors or 1024 byte sectors.  The user should determine when the
longer block length actually improves throughput without causing
problems.

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

If no extended file information is 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
systems.  With YMODEM, each file name is converted to lower case unless
it contains one or more lower case letters.

The second form of rz receives a single file with XMODEM protocol.  The
user must supply the file name to both sending and receiving programs.

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"

The third form of rz is invoked as rzCOMMAND (with an optional leading
- as generated by login(1)).  For each received file, rz will pipe the
file to ``COMMAND filename'' where filename is the name of the
transmitted file with the file contents as standard input.

Each file transfer is acknowledged when COMMAND exits with 0 status.  A
non zero exit status terminates transfers.

A typical use for this form is rzrmail which calls rmail(1) to post mail
to the user specified by the transmitted file name.  For example,
sending the file "caf" from a PC-DOS system to rzrmail on a Unix system
would result in the contents of the DOS file "caf" being mailed to user
"caf".

On some Unix systems, the login directory must contain a link to COMMAND
as login sets SHELL=rsh which disallows absolute pathnames.  If invoked
with a leading ``v'', rz will report progress to /tmp/rzlog.  The
following entry works for Unix 3.0:

rzrmail::5:1::/bin:/usr/local/rzrmail

If the SHELL environment variable includes "rsh" or "rksh" (restricted
shell), rz will not accept absolute pathnames or references to a parent
directory, will not modify an existing file, and removes any files
received in error.

If rz is invoked with stdout and stderr to different datasets, Verbose
is set to 2, causing frame by frame progress reports to stderr.  This
may be disabled with the q option.

The meanings of the available options are:

1

Use file descriptor 1 for ioctls and reads (Unix only).  By default,
file descriptor 0 is used for ioctls and reads.  This option allows rz
to be used with the Professional-YAM $ command and some versions of
ncu(1).

a

Convert files to Unix conventions by stripping carriage returns and all
characters beginning with the first Control Z (CP/M end of file).

b

Binary (tell it like it is) File transfer override.

c

Request 16 bit CRC.  XMODEM file transfers default to 8 bit checksum.
YMODEM and ZMODEM normally use 16 bit CRC.

D

Output file data to /dev/null for testing.

e

Force sender to escape all control characters; normally XON, XOFF, DLE,
CR-@-CR, and Ctrl-X are escaped.

p (ZMODEM)

Protect: skip file if destination file exists.

q

Quiet suppresses verbosity.

"t tim"

Change timeout to tim tenths of seconds.

v

Verbose causes a list of file names to be appended to /tmp/rzlog .  More
v's generate more output.

6

EXAMPLES

(Pro-YAM command)

<ALT-2>

Pro-YAM Command:
"sz *.h *.c"

(This automatically invokes rz on the connected system.)

SEE ALSO ZMODEM.DOC, YMODEM.DOC, IMP(CP/M), Professional-YAM, sz(omen),
usq(omen), undos(omen)

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

NOTES

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

The TTY input buffering on some systems may not allow 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 when
YMODEM with 128 byte blocks works properly.  If the system's tty line
handling is really broken, the serial port or the entire system may not
survive the onslaught of long bursts of high speed data.

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").

32 bit CRC code courtesy Gary S. Brown.

BUGS

Calling rz from most versions of cu(1) doesn't work because cu's receive
process fights rz for characters from the modem.

Pathnames are restricted to 127 characters.  In XMODEM single file mode,
the pathname given on the command line is still processed as described
above.  The ASCII option's CR/LF to NL translation merely deletes
CR's; undos(omen) performs a more intelligent translation.

"VMS VERSION"

Some of the #includes with file names enclosed with angle brackets <>
may need to have the angle brackets changed to "", or vice versa.

The VMS version does not set binary mode according to the incoming file
type.  Non binary file processing consists of stripping all characters
beginning with CPMEOF (^Z).

The VMS version does not set the file time.

At high speeds, VMS sometimes loses incoming characters, resulting in
retries and degradation of throughput.

The mysterious VMS C Standard I/O Package and RMS may interact to modify
file contents unexpectedly.

The VMS version does not support invocation as rzCOMMAND .  ZMODEM has
not yet been implemented on the VMS version.

"ZMODEM CAPABILITIES"

Rz supports incoming ZMODEM binary (-b), ASCII (-a), protect (-p), and
append (-+) requests, and ZMODEM command execution.

FILES

rz.c, rbsb.c, zm.c, zmodem.h source files.



SZ

NAME

sx, sb, sz - XMODEM, YMODEM, ZMODEM file send

SYNOPSIS

sz [- +1abdefkLlNnopqTtuvyY ] file ...

sb [- 1adfkqtuv ] file ...

sx [- 1akqtuv ] file

sz [- 1oqtv ] "-c COMMAND"

sz [- 1oqtv ] "-i COMMAND"

DESCRIPTION

Sz uses the ZMODEM, YMODEM or XMODEM error correcting protocol to send
one or more files over a serial port to a variety of programs running
under PC-DOS, CP/M, Unix, VMS, and other operating systems.

The first form of 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), Crash Recovery, selective
file transfers, and preservation of exact file date and length.

Output from another program may be piped to sz for transmission by
denoting standard input with "-":

ps -ef | sz -

The program output is transmitted with the filename sPID.sz where PID is
the process ID of the sz program.  If the environment variable ONAME is
set, that is used instead.  In this case, the Unix command:

ONAME=con ps -ef|sz -ay -

will send a "file" to the PC-DOS console display.  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.

The second form is invoked as sb to batch send one or more files with
ZMODEM or YMODEM 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 throughput
over error free channels (direct connection, X.PC, etc.) by not
acknowledging each transmitted sector.

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 and file mode are set.

The third form of sz is invoked as sx to send 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 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.  Sz 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.  Sz exits as soon as the receiver has correctly received the
command, before it is executed.

If sz is invoked with stdout and stderr to different datasets, Verbose
is set to 2, causing frame by frame progress reports to stderr.  This
may be disabled with the q option.


The meanings of the available options are:

0

Instruct the receiver to append transmitted data to an existing file
(ZMODEM only).

1

Use file descriptor 1 for ioctls and reads.  By default, file descriptor
0 is used.  This option allows sz to be used with the Professional-YAM $
command.

a

Convert NL characters in the transmitted file to CR/LF.  This is done by
the sender for XMODEM and YMODEM, by the receiver for ZMODEM.

b (ZMODEM)

Binary override: transfer file without any translation.

"c COMMAND"

Send COMMAND to the receiver for execution, return with COMMAND's exit
status.

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; normally XON, XOFF, DLE, CR-@-CR, and
Ctrl-X are escaped.

f

Send Full pathname.  Normally directory prefixes are stripped from the
transmitted filename.

"i COMMAND"

Send COMMAND to the receiver for execution, return Immediately upon the
receiving program's successful recption of the command.

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

"L N"

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.

"l N"

Wait for the receiver to acknowledge correct data every N (32 <= N <=
1024) 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.

q

Quiet suppresses verbosity.

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.

"t tim"

Change timeout to tim tenths of seconds.

u

Unlink the file after successful transmission.

v

Verbose causes a list of file names to be appended to /tmp/szlog .  More
v's generate more output.

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.

EXAMPLES

7 "ZMODEM File Transfer"

"$ 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 recieve 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"

 cpszall:all
    sz -c "c:;cd /yam/dist"
    sz -ya $(YD)/*.me
    sz -yqb y*.exe
    sz -c "cd /yam"
    sz -i "!insms"

This Makefile fragment uses sz to issue commands to Professional-YAM to
change current disk and directory.  Next, sz transfers the 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 "-i" form is
used to allow sz to exit immediately.

"XMODEM File Transfer"
(To Crosstalk)

$
"sx -a foo.c"

"ESC"

"rx foo.c"

The above three commands transfer a single file from Unix to a PC and
Crosstalk with sz translating Unix newlines to DOS CR/LF.  This
combination is much slower than ZMODEM.  SEE ALSO rz(omen), ZMODEM.DOC,
YMODEM.DOC, Professional-YAM, IMP(CP/M), sq(omen), todos(omen),
tocpm(omen), tomac(omen), yam(omen)

Compile time options required for various operating systems are
described in the source file.  "VMS VERSION" The VMS version does not
transmit the file date.  The VMS version calculates the file length by
reading the file and counting the bytes.

The VMS version does not support YMODEM-g or ZMODEM.

When VMS is lightly loaded, the response time may be too quick for
MODEM7 unless the MODEM7 "q" modifier is used.

The VMS C standard i/o package and RMS sometimes interact to modify file
contents unexpectedly.

FILES

32 bit CRC code courtesy Gary S.  Brown.

sz.c, rbsb.c, zm.c, zmodem.h 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.  BUGS Calling sz from most versions of cu(1)
doesn't work because cu's receive process fights sz for characters from
the modem.

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 (1023 bytes with
XMODEM-k).

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 do
not implement all 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.  The test mode leaves a
zero length file on the receiving system.

Some high speed modems have a firmware bug that drops characters when
the direction of high speed transmissson is reversed.  The environment
variable ZNULLS may be used to specify the number of nulls to send
before a ZDATA frame.  Values of 101 for a 4.77 mHz PC and 124 for an AT
are typical.