NAME
          rz - ZMODEM file receive

     SYNOPSIS
          rz [-+abEeiIMmNnPpqrtuvYy]

     DESCRIPTION
          The rz program uses the ZMODEM-90Tm error correcting
          protocol to receive files from a program logged into a
          serial port.  (See SERVER/NETWORK NOTES below.)

          Normally, an "sz file ..." command given to the calling
          program automatically starts rz.

          This copy of VMS rz operates only with Omen Technology
          products (DSZ, ZCOMM, or Professional-YAM), and is licensed
          only for use therewith.

          Commercial sz and rz for use with any program supporting
          XMODEM, YMODEM, or ZMODEM are available for purchase from
          Omen Technology INC.

          This program is not designed be called from cu, tip, kermit,
          or any other communications program.  Unix flavors of Omen
          Technology's Professional-YAM communications software are
          available for dial-out applications.


          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
          implementations may require starting rz the old fashioned
          way.  Rz supports the ZMODEM features listed below under
          OPTIONS.  Unix flavors of Professional-YAM may be linked to
          "rz" and used in place of this rz to support any missing
          features.




     OPTIONS
          The meanings of the available options are:

          "-option"
               Enclosing an option in double quotes allows lower case
               to be used with VMS.
          \    (backslash) (VMS) Force the next option letter to upper
               case.
          +    Append transmitted data to existing file.
          a    Convert text files to local system conventions.  This
               option must be supplied to the sending program.
          b    Binary (tell it like it is) file transfer override.
               Witnout the P option, data is compressed.
          EP   Pack 4 data bytes into 5 bytes for operation over 7 bit
               paths.  This is more efficient when the data is already
               compressed.
          i    Receive with VMS Stream_LF record format to avoid
               padding file with nulls.  This record format is
               understood by many C programs.  (VMS only)
          I    Receive with VMS Variable length (mrs=510) (Image)
               record format to avoid padding file with nulls.  This
               record format is understood by many Kermit programs.
               (VMS only)
          n    (ZMODEM) Each file is transferred if the corresponding
               destination file does not exist, or if the source file
               is newer. The n option can be given with either the sz
               or rz commands.  This option is not allowed if the
               receiver is Restricted.
          m    Activate MobyTurbo accelerator to speed transmission of
               compressed files.
          N    (ZMODEM) Transfer the file if the corresponding
               destination file does not exist, or if the source file
               is newer or longer.  The N option be used with the sz
               and rz commands.  This option is not allowed if the
               receiver is Restricted.
          p    (ZMODEM) Protect: skip file if destination file exists.
          q    Quiet suppresses verbosity.
          r    (ZMODEM) Resume an interrupted file transfer with the
               ZMODEM protocol.  May be given with either the sz or rz
               commands.  The r option may be used to resume the
               transmission of a long file after a disconnect or power
               loss, without having to start over at the beginning of
               the file.  The r option may also be used when the
               source file grows from time to time and only the
               incremental portion needs to be sent.  The r option
               assumes that the contents of the destination file are
               identical to the corresponding beginning portion of the
               source file.  The r option should not be applied to a
               file that has been modified by the a option, or to a
               file that has been modified on the destination system.
               This option is not allowed if the receiver is
               Restricted.
          ttim Change timeout to tim tenths of seconds.
          v    Verbose causes a list of file names to be appended to
               /tmp/rzlog (rzlog.tmp on VMS).  More v's generate more
               detailed debugging output.
          y    Yes, clobber any existing files with the same name.  (A
               new version is created on VMS.)
          Y    (ZMODEM) Transfer only those files for which a file
               with the same pathname exists at the destination,
               overwriting the destination files.  (A new version is
               created on VMS.) The Y option may be followed by other
               ZMODEM options to further qualify the selection of
               files to transfer.  This option is not allowed if rz is
               Restricted.

     DIAGNOSTICS
          Unix 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.

          VMS exit status is SS_$NORMAL or SS$_ABORT.

     EXAMPLES
          (Professional-YAM command sequence)
          
          YAM Command: sz *.h *.c
          (This automatically invokes rz on the host system.)

     SEE ALSO
          DSZ, ZCOMM, or Professional-YAM User Manual, crc(omen),
          undos(omen)


     NOTES
          When rb, rc or rx is waiting for the sender to start,
          keyboarding Control-X (CAN) or Ctrl-C (ETX) characters will
          terminate the program.

          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 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,
          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, Professional-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; 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, 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, or
          KERMIT.  Setting one of these spoofing modes interferes with
          other protoocls.

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

     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.

          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.

          Escaping 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 the Professional-YAM/ZCOMM
          manual).

          If you encounter problems with control characters 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, you can fake it with ZMODEM.  Try
               sz -w1024 file...
          to enable software flow control. Experiment with different
          values to find the best throughput.

          Terminal servers are designed to accept keyboard input from
          human operators.  They may lose data when a program sends
          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 upgraded.  Please contact the network's vendor for
          corrective procedures.  An alternative is to install direct
          serial ports for users desiring to upload files.

          Some systems enforce a timeout which disconnects a user
          after several minutes of no keyboarding.  This can cause
          problems in long, error free ZMODEM transfers.  Restricting
          the window size with a "-w8192" option provides 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.)

     BUGS
          Rz is not intended be called from cu(1), or other
          communications programs.  Unix flavors of Omen Technology's
          Professional-YAM communications software are available for
          dial-out applications.

          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 NOTES
          The message WARNING: No ALT_TYPEAHEAD indicates the system
          manager has not enlarged VMS's input buffer.

          ALTYPEAHEAD is a terminal setting that increases the size of
          the terminal typeahead buffer over and above what TYPEAHEAD
          gives you.  Do a "HELP SET TERMINAL ALT" and you'll find the
          help for this.

          For efficient operation at high baud rates, the system
          manager should "set term tta0:/altypeahd/perm" (choose the
          appropriate tty port).  This must be done when the
          particular terminal line is not logged in.  Without setting
          altypeahd you may get excessive retries (ZRPOS messages)
          and/or lousy throughput.

          The SYSGEN parameter TTY_TYPAHDSZ should be set to 1024 or
          more.  Try increasing the SYSGEN parameter TTY_TYPAHDSZ to,
          say, 2048 or more for best results on uploads to VMS.

          To use rz a DCL verb must be defined with syntax similar to
          the following:

          rz :== "$disk$user2:[username.subdir]rz.exe rz"

          For example, suppose "dir rz" results in:
          Directory SYS$SYSDEVICE:[CAF]
          RZ.EXE;1

          You would then define rz as:
          $rz :== "$sys$sysdevice:[CAF]rz.exe rz"

          The VMS version does not set the file time.

          Received files default to FIXED 512 record format, null
          padded to a multiple of 512 bytes.  ASCII mode (-a flag
          given to sender) results in variable length records with CR
          carriage control.  Stream image mode (-i) writes in
          Stream_LF record format, no padding.  Stream_LF preserves
          exact file length, useful for archive servers.

          Block Image mode (-I) writes in Variable length binary
          record format (mrs=510) without padding.  Kermit servers
          like this record format.

          Except for Crash Recovery, VMS rz attempts to generate a new
          version number instead of overwriting the current file.

          In some instances VMS DCL forces command line arguments to
          upper case unless they are enclosed by double quotes.  Upper
          case option letters may be represented by preceding the
          letter with \.


     ZMODEM CAPABILITIES
          Rz supports incoming ZMODEM binary (-b), ASCII (-a),
          image(-i), Image(-I), 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.  The default is protect (-p)
          and binary (-b).

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

          Omen Technology INC
          Post Office Box 4681
          Portland OR 97208
          503-621-3406


     FILES
          /tmp/rzlog (RZLOG.TMP on VMS) stores debugging output
          generated with -vv option.

          32 bit CRC code courtesy Gary S. Brown.

     LICENSE
          Use of this software for commercial or administrative
          purposes except when exclusively limited to interfacing Omen
          Technology products requires a license from Omen Technology
          Inc.

          Use of this code by inclusion, decompilation, reverse
          engineering or any other means constitutes agreement to
          these conditions and acceptance of liability to license the
          materials and payment of any reasonable legal or
          investigative costs necessary to enforce this license
          agreement.

          Copyright 1994 Omen Technology INC All Rights Reserved

Information Services, Central Computing
University of Missouri Kansas City