home *** CD-ROM | disk | FTP | other *** search
/ HomeWare 14 / HOMEWARE14.bin / comms / p10.arj / README.TXT < prev   
Text File  |  1994-05-05  |  14KB  |  322 lines

  1.  
  2.  
  3.                             P version 1.0
  4.  
  5.                   Copyright (c) 1994 by Jyrki Salmi
  6.  
  7.  
  8.         This is a FREE file transfer protocol package for OS/2 2.x.
  9.         The main goal in designing the program was to optimize it
  10.     to use CPU time as little as possible and transfer data as
  11.     fast as possible. Don't expect beatiful user interfaces...
  12.  
  13.                                 - - -
  14.  
  15.         Following protocols are supported:
  16.  
  17.         * Zmodem
  18.                 - Automatic file name, size and date information exchange
  19.                 - Full streaming and windowing
  20.                 - 32-bit and 16-bit CRC frame checking
  21.                 - Crash recovery
  22.                 - Control character escaping
  23.                 
  24.         * Ymodem-g
  25.                 - Automatic file name, size and date information exchange
  26.                 - Continuos data flow
  27.                 - 128 and 1024 byte blocks
  28.                 - 16-bit CRC block checking
  29.  
  30.         * Ymodem
  31.                 - Automatic file name, size and date information exchange
  32.                 - 128 and 1024 byte blocks
  33.                 - 16-bit CRC and checksum block checking
  34.                 
  35.         * Xmodem
  36.                 - 128 and 1024 byte blocks
  37.                 - 16-bit CRC and checksum block checking
  38.  
  39.         Command line parameters explained:
  40.  
  41.         <com device|com handle>
  42.  
  43.         Either the name of a standard OS/2 device, like COM1, COM2,
  44.         etc. or an already open handle (a number) to such device. P
  45.         recognizes one from the other by checking the first character
  46.         of this parameter, if it's a non-digit it's the name of the
  47.         device and if not, it's the handle.
  48.  
  49.         <com speed>
  50.  
  51.         This parameter specifies the speed of connection in bits per
  52.         second. It's used only for calculating the estimated transfer
  53.         times. P *NEVER* changes the speed of the communication
  54.         device, either the calling program or the user (with OS/2's
  55.         MODE command) must setup the device.
  56.  
  57.         [options]
  58.  
  59.         You can enter any number (or none) of the following options in
  60.         this place. All options must be preceded by '-' character and
  61.         are to be separated by one or more spaces.
  62.  
  63.         -a -- Use the alternative error checking method
  64.  
  65.         All of the supported protocols but Ymodem-g has an alternative
  66.         error checking method besides its default. Here is the list of
  67.         default and alternative methods:
  68.  
  69.         Protocol        Default         Alternative
  70.         --------        -------         -----------
  71.         Zmodem          CRC-32          CRC-16
  72.         Ymodem-g        CRC-16          -
  73.         Ymodem          CRC-16          checksum
  74.         Xmodem          checksum        CRC-16
  75.  
  76.         Only when using Zmodem, both the receiver and the sender can
  77.         define the checking method to be used. Ymodem and Xmodem give
  78.         this responsibility to the receiver, although the sender can
  79.         ignore CRC-16 requests making the receiver fall-back into
  80.         checksum, but this takes a while of timeoutting and isn't
  81.         supported by P.
  82.  
  83.         -A -- send "rz\r" to the remote before the transfer (Z)
  84.  
  85.         This option affects only to Zmodem sending. It makes P to
  86.         send a string "rz\r" to the remote while trying to initiate the
  87.         transfer. If there's an UNIX shell running at the other end it
  88.         will be interpreted as the user has just typed "rz" and then
  89.         pressed enter, and the UNIX rz program will be run.
  90.  
  91.         If you aren't transferring files to an UNIX system this option
  92.         just generates more garbage to the remote screen in
  93.         intialization phase, in case it hasn't started receiving
  94.         program yet.
  95.  
  96.         -b<bytes> -- Define the size of communication buffers, default
  97.                      is 2048
  98.  
  99.         With this option you can define the size of low-level input
  100.         and output communication buffers. It has an effect only to the
  101.         protocols sending and receiving data in continuous streams:
  102.         Zmodem and Ymodem-g.
  103.  
  104.         With a bigger value and a reliable connection you can speed up
  105.         the throughput considerably. But if the connection requires
  106.         retransmits, a bigger value can slow down the throughput
  107.         much more and generate a lot of annoying garbage to the remote
  108.         screen after the transfer has been cancelled.
  109.  
  110.         For example if you specify 32768 bytes long buffers we will
  111.         block in read or write routine until we get it all read or
  112.         written. If you're sending with Zmodem and there is an error
  113.         in transmission, it won't be recovered until all data in the
  114.         buffers is transferred. And if you're using Ymodem-g the
  115.         transfer will be aborted in case of an error, all data in
  116.         buffers will be written to the remote screen until we
  117.         recognize the abortation.
  118.  
  119.         And when receiving with Zmodem or Ymodem-g, we won't check for
  120.         possible transmission errors until we have received the whole
  121.         buffer, making us potentially transferring a lot of data
  122.         that's to be resent.
  123.  
  124.         There's no maximum limit for the size of buffers. The bigger you
  125.         specify the more memory will we eaten. Under multitasking
  126.         environments like OS/2, bigger buffers will make us to use a
  127.         bit less processor time.
  128.  
  129.         -c -- Rename file if it already exists
  130.  
  131.         This option has an effect only when receiving files. It makes
  132.         us to check for existance of the file to be received instead of
  133.         simply overwriting. If the file already exists, the new file
  134.         will be written with an other name. For example, if we are to
  135.         receive file named FILE.ZIP and we already have one with an
  136.         identical name. The new file will be renamed to FILE.ZI0, and
  137.         if we receive yet another copy of it with -c option specified
  138.         it will be named as FILE.ZI1, and so on.
  139.  
  140.         NOTE: This file renaming algorithm is bit brain-dead. For
  141.         example, if you're receiving FILE.C and you already have one,
  142.         It will be named as FILE.0, instead of FILE.C0, which sounds
  143.         much more logical. The reason for this is that we don't want
  144.         to change the length of the file name, because it might cause
  145.         problems on file systems supporting different maximum name
  146.         lengths.
  147.  
  148.         -d -- Disable carrier watch
  149.  
  150.         This option makes us to ignore the state of carrier detect
  151.         signal. Use it if your modem or serial cable can't pass it.
  152.         Also, if you're using null-modem cable to transfer files
  153.         between two machines, you might want to disable the carrier
  154.         watch.
  155.  
  156.         -D<dir>   Define the download directory
  157.  
  158.         With this option you can specify where all received files will
  159.         be saved. If not specified, they will be saved in the current
  160.         directory. This option will be ignored if -f option
  161.         (receive/send full paths) has been defined.
  162.  
  163.         -e -- Escape all control characters (Z)
  164.  
  165.         This affects only to Zmodem sending and receiving.  It makes
  166.         us to escape all control characters (ASCII 0 to 31). Escaping
  167.         generates overhead by transmitting two bytes to represent
  168.         every control character. Use it only if your connection can't
  169.         pass them through.
  170.  
  171.         NOTE: Ymodem-g, Ymodem and Xmodem do not support any kind of
  172.         escaping and they require a totally transparent 8-bit
  173.         connection.
  174.  
  175.         -f -- Send/receive full paths (Z and Y)
  176.  
  177.         By this option you make us to send file path information just
  178.         as it was given on the command-line or in the list file. The
  179.         other end can however still strip the drive and directory
  180.         information and use the plain file name. 
  181.  
  182.         When receiving be careful with this option. Other end can send
  183.         files to any drive and directory on your system, even viruses
  184.         and trojans.
  185.  
  186.         When this option is *NOT* used, all drive and directory
  187.         information will be stripped. All files will be received to
  188.         the receive directory and if not specified, to the current
  189.         directory.
  190.  
  191.         -F -- Don't remove failed files
  192.  
  193.         By default we remove all files whose transfer was aborted or
  194.         failed for some other reason. If this option is specified we
  195.         will keep what we have got transferred, making it possible for
  196.         Zmodem to crash recover from it later.
  197.  
  198.         -k -- Use 1024 byte blocks instead of 128 byte (X and Y)
  199.  
  200.         This affects only to Ymodem-g, Ymodem and Xmodem sending.
  201.         It makes us to send data in 1024 byte blocks instead of 128
  202.         byte, speeding up the transfer considerably on high speed
  203.         connections. However, the propability of garbled data getting
  204.         through grows when there is more data to calculate the check
  205.         value from, thus you should avoid using 1024 byte blocks with
  206.         checksum checking.
  207.  
  208.         NOTE: When receiving, it's up to the remote to define the
  209.         block size.
  210.  
  211.         -p -- Wait for a keypress after the transfer
  212.  
  213.         This option might be useful if you're using P to provide
  214.         external protocols for some program that clears the screen
  215.         after the transfer. By using this option P waits for a
  216.         keypress after the transfer, providing you time to read the
  217.         messages concerning the transfer.
  218.  
  219.         -r -- Recover crashed transfers (Z)
  220.  
  221.         When a transfer has crashed in the middle of the file, it's
  222.         possible to recover from that and continue the transfer just
  223.         from there where it crashed. This requires that we have the
  224.         already transferred part of the file saved on the disk, ie.
  225.         file must have been transferred with the option -F specified.
  226.  
  227.         NOTE: Only Zmodem supports crash recovery.
  228.  
  229.         -v -- Show received headers' types and contents (Z)
  230.  
  231.         This only affects to Zmodem transfers and it's intented purely
  232.         for debugging and trouble-shooting purposes. It makes P to
  233.         display the type of every received Zmodem header and its
  234.         contents. You shouldn't bother yourself with this if you
  235.         aren't familiar with Zmodem internals.
  236.  
  237.         -V -- Show sent frameends (Z)
  238.  
  239.         This also affects only to Zmodem transfers and is purposed
  240.         to help debugging. It makes P to show transferred frameends.
  241.  
  242.         -w<bytes> -- Use a transmit window of <bytes> length (Z)
  243.  
  244.         Affects only to Zmodem transmissions. It makes us to wait for
  245.         an acknowledge for every <bytes> transferred, when the default
  246.         is sending data in full streaming, without acknowledges.
  247.  
  248.         Using this might be necessary if you're sending data through a
  249.         network where sone nodes of that network might timeout if
  250.         there isn't data transferred to one direction for some time.
  251.  
  252.         Using a small window size slows down the transfer somewhat.
  253.  
  254.         NOTE: Window size must be a multiple of 64, the minimum value
  255.         is 256 and the maximum is 65472.
  256.         
  257.         <protocol>
  258.  
  259.         With this parameter you define the protocol to be used and
  260.         whether to send or receive files.
  261.  
  262.         The transmission direction is figured out from the first
  263.         character of this parameter. 's' represents sending and 'r'
  264.         receiving, any other will cause an error message.
  265.  
  266.         The second character represents the protocol type:
  267.  
  268.                 x       Xmodem
  269.                 y       Ymodem
  270.                 g       Ymodem-g
  271.                 z       Zmodem
  272.  
  273.         [<file|@listfile>...]
  274.  
  275.         The rest of the command-line is for paths to files to be sent
  276.         or received. If you have a lot of files to transfer you might
  277.         want to use a list file instead specifying them all on the
  278.         command-line. List files are plain ASCII files containing file
  279.         paths on separate lines. List file paths are distinguished
  280.         from the normal file paths from the preceding '@' character.
  281.         You can mix up any number of files and list files on the
  282.         command-line.
  283.  
  284.         When sending files, the use of these file paths is obvious,
  285.         those files are to be sent. If the file specified can't be
  286.         opened by P, either it doesn't exist or it's used by an
  287.         another application, it will be skipped.
  288.  
  289.         You can specify any number of files to be transferred with
  290.         protocols that support batch transmissions, that is all but
  291.         Xmodem. With Xmodem you can specify only one file, whether you
  292.         are receiving or sending.
  293.  
  294.         When receiving with a protocol supporting batch transfers you
  295.         don't have to specify any files at all. However, if you will,
  296.         only those files specified will be received. If you are
  297.         receiving with Zmodem the files not found on the  command-line
  298.         will be skipped. With Ymodem, the transfer will be aborted,
  299.         because the protocol does not support skipping.
  300.  
  301.                                 - - -
  302.  
  303.         If you intend to use P with a bulletin board software you
  304.         might want to use a DSZ log. DSZ logs are used to tell the BBS
  305.         software whether the file transfer was succesful or not.
  306.  
  307.         All you have to do is to define an enviroment variable DSZLOG
  308.         that points to the file defined as DSZ log in your BBS's
  309.         configuration. Refer to its manual for detailed information.
  310.         If no DSZLOG variable has been defined, no DSZ log will be
  311.         created.
  312.  
  313.                                 - - -
  314.  
  315.         Yup, that's it folks. Hope you find some use for this. If you
  316.         have any problems, questions or you just want to give a
  317.         comment, drop me a note:
  318.  
  319.                                         Internet: jytasa@jyu.fi
  320.                                         FidoNet: Jyrki Salmi (2:225/12)
  321.  
  322.