Australian Personal Computer 1998 July

home *** CD-ROM | disk | FTP | other *** search

/ Australian Personal Computer 1998 July / apc37.iso / netkit / mac / dcomet / dcomet.hqx / Documents / 6.1 ZMODEM command options < prev next >

Wrap

Text File | 1998-01-29 | 24.6 KB | 621 lines

SZ(1) SZ(1) NAME sx, sb, sz - XMODEM, YMODEM, ZMODEM file send SYNOPSIS sz [-+abdefkLlNnopqTtuvyYZ] file ... sb [-adfkqtuv] file ... sx [-akqtuv] file sz [-oqtv] -c COMMAND sz [-oqtv] -i COMMAND sz -T DESCRIPTION Sz uses the ZMODEM, YMODEM or XMODEM error correcting pro- tocol 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. Sz is not intended be called from cu(1) or other communi- cations programs. Unix flavors of Omen Technology's Pro- fessional-YAM communications software are available for dial-out applications. (Reg.) Sz sends one or more files with ZMODEM protocol. ZMODEM greatly simplifies file transfers compared to XMO- DEM. 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 interven- tion), 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" batch sends one or more files with YMODEM or ZMODEM protocol. The initial ZMODEM initialization is not sent. When requested by the receiver, ssbb 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 informa- tion, the transmitted file length controls the exact num- ber of bytes written to the output dataset, and the modify time and file mode 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 pro- grams. 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 cor- rectly received the command, before it is executed. The sixth form (sz -T) attempts to output all 256 code combinations to the terminal. In you are having diffi- culty sending files, this command lets you see which char- acter codes are being eaten by the operating system. 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 qq option. The meanings of the available options are: \ (backslash) (VMS) Force the next option letter to upper case. + Instruct the receiver to append transmitted data to an existing file (ZMODEM only). 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 transmit- ted pathname. Thus, C.omenB0000 (which is unac- ceptable 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 NN (32 <= N <= 1024) characters. This may be used to avoid network overrun when XOFF flow con- trol 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. rr As above, but compares the files (the portion com- mon to sender and reciever) before resuming the transfer. t tim Change timeout to tim tenths of seconds. u Unlink the file after successful transmission. w N 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. 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. EXAMPLES 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 conven- tions appropriate to the receiving environment. With ZMO- DEM AutoDownload enabled, Professional-YAM and ZCOMM will automatically recieve the files after performing a secu- rity 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. $ sz -\Yan file1.c file2.c file3.c foo.h baz.h (Reg.)(for VMS) ZMODEM Command Download (Unix to Professional-YAM) 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 Pro- fessional-YAM to change current disk and directory. Next, sz transfers the .me files from the $YD directory, com- manding the receiver to overwrite the old files and to convert from Unix end of line conventions to PC-DOS con- ventions. 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 (Unix 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 and far 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), ZMODEM.DOC, YMODEM.DOC, Professional-YAM, crc(omen), sq(omen), todos(omen), tocpm(omen), tomac(omen), yam(omen) Compile time options required for various operating sys- tems are described in the source file. VMS VERSION The VMS version does not support wild cards. Because of VMS DCL, upper case option letters muse be represented by \ proceding the letter. The current VMS version does not support XMODEM, XMO- DEM-1k, or YMODEM. VMS C Standard I/O and RMS may interact to modify the file contents. FILES /tmp/szlog stores debugging output (sz -v) (szlog on VMS). 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 inter- rupting 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 differ- ence between Tcount and 5120 represents the number of characters stored in various buffers when the Attn sequence is generated. NOTES Sz is not intended be called from cu(1) or other communi- cations programs. Unix flavors of Omen Technology's Professional-YAM communications software are available for dial-out applications. If a program that does not properly implement the speci- fied 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 protocol. Many programs claiming to support YMODEM only support XMO- DEM 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; per- haps it should check for the presence of at least one accessible file before getting hot and bothered. A few 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. BUGS On at least one BSD system, sz would abend it got within a few kilobytes of the end of file. Using the "-w 8192" flag fixed the problem. The real cause is unknown, per- haps a bug in the kernel TTY output routines. The test mode leaves a zero length file on the receiving system. RZ(1) RZ(1) NAME rx, rb, rz - XMODEM, YMODEM, ZMODEM (Batch) file receive SYNOPSIS rz [- +abepqtuvy] rb [- +abqtuvy] rx [- abceqtuv] file gz file ... [-][v]rzCOMMAND DESCRIPTION This program uses error correcting protocols to receive files over a dial-in serial port from a variety of pro- grams running under PC-DOS, CP/M, Unix, and other operat- ing systems. It is invoked from a shell prompt manually, or automatically as a result of an "sz file ..." command given to the calling program. Rz is not intended be called from cu(1), or other communi- cations programs. Unix flavors of Omen Technology's Pro- fessional-YAM communications software are available for dial-out applications. (Reg.) "Rz" (Receive ZMODEM) receives files with the ZMODEM batch protocol. Pathnames are supplied by the sending program, and directories are made if necessary (and possible). Normally, the "rz" command is automatically issued by the calling ZMODEM program, but some defective ZMODEM imple- mentations may require starting rz the old fashioned way. Rz does not support ZMODEM Crash Recovery, compression, and other ZMODEM features. Unix flavors of Professional- YAM may be linked to "rz" and used in place of this pro- gram to support these ZMODEM features. "Rb" receives file(s) with YMODEM, accepting either standard 128 byte sectors or 1024 byte sectors (YAM sb -k option). The user should determine when the 1024 byte block length actually improves throughput without causing lost data or even system crashes. If True YMODEM (Omen Technology trademark) file informa- tion (file length, etc.) is received, the file length controls the number of bytes written to the output dataset, and the modify time and file mode (iff non zero) are set accordingly. If no True YMODEM 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 con- tains one or more lower case letters. "rx" receives a single file with XMODEM or XMODEM-1k proto- col. The user should determine when the 1024 byte block length actually improves throughput without causing prob- lems. 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" "rz" may be 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 trans- mitted 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 SYS III/V: 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 qq option. The meanings of the available options are: a Convert files to Unix conventions by stripping car- riage 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. (Unix only) e Force sender to escape all control characters; nor- mally 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. y Yes, clobber any existing files with the same name. 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, Professional-YAM, crc(omen), sz(omen), usq(omen), undos(omen) Compile time options required for various operating sys- tems are described in the source file. NOTES ZMODEM's support of XOFF/XON flow control allows proper operation in many environments that do not support XMODEM uploads. Unfortunately, not all timesharing systems sup- port 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, but YMODEM-1k or XMODEM-1k, when 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 speci- fied 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 XMO- DEM with 1k blocks, and they often don't get that quite right. In the case of a few poorly designed microcomputers, send- ing 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; CRT terminals with block mode 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, espe- cially if the personality of the system appears altered. The Unix "ulimit" parameter must be set high enough to permit large file transfers to Unix. 32 bit CRC code courtesy Gary S. Brown. Directory cre- ation code from John Gilmore's PD TAR program. BUGS Rz is not intended be called from cu(1), or other communi- cations programs. Unix flavors of Omen Technology's Pro- fessional-YAM communications software are available for dial-out applications. Rz does not support ZMODEM Crash Recovery, compression, and other ZMODEM features. Unix flavors of Professional- YAM may be linked to "rz" to support these features. 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 The VMS version does not set the file time. VMS C Standard I/O and RMS may interact to modify file contents unexpectedly. The VMS version does not support invocation as "rzCOMMAND" .. The current VMS version does not support XMODEM, XMO- DEM-1k, or YMODEM. According to the VMS documentation, the buffered input routine used on the VMS version of rz introduces a delay of up to one second for each protocol transaction. This delay may be significant for very short files. Removing the "#define BUFREAD" line from rz.c will eliminate this delay at the expense of increased CPU utilization. For high speed operation, try increasing the SYSGEN param- eter TTY_TYPAHDSZ to 256. The VMS version causes DCL to generate a random off the wall error message under some error conditions; this is a result of the incompatibility of the VMS "exit" function with the Unix/MSDOS standard. ZMODEM CAPABILITIES Rz supports incoming ZMODEM binary (-b), ASCII (-a), pro- tect (-p), clobber (-y), and append (-+) requests. Other options sent by the sender are ignored. The default is protect (-p) and binary (-b). The Unix versions support ZMODEM command execution. FILES /tmp/rzlog stores debugging output generated with -v option (rzlog on VMS).