home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 340.lha / JModem_v1.0 / JAmiga.txt.pp / JAmiga.txt
Encoding:
Text File  |  1990-02-11  |  10.5 KB  |  217 lines
  1.  
  2.              JMODEM File Transfer Protocol, Amiga Version 1.0
  3.             ---------------------------------------------------
  4.  
  5.   Based on original implementation version 1.20 by Richard B. Johnson
  6.   for IBM PC compatibles. Amiga port made by Kenneth Osterberg, released
  7.   into public domain June 10, 1989.
  8.  
  9.   These files are supplied in the archive file:
  10.  
  11.   JModem      The executable program, compiled with Manx Aztec C 3.4a
  12.   JModem.c    The C source file which implements the protocol
  13.   protsupp.c  Some support routines which handle serial device receive/send
  14.               (with true timeouts) and simplified intuition window management.
  15.   protsupp.h  Header file included by JModem.c, defines constants and functions
  16.               in protsupp.c
  17.   docrc.asm   The assembler source which does the CRC calculation
  18.   Makefile    Makefile how to compile the modules. I didn't use Aztec make, so
  19.               you might have to change one or two things, but you get the idea.
  20.   JAmiga.txt  This documentation
  21.  
  22.   The program is implemented as an "external protocol", as is customary
  23.   in the IBM-PC world. This has many advantages, but limits its usage
  24.   until programs appear which can handle this feature in an efficient way.
  25.  
  26.   Introduction to JMODEM:
  27.   If you want exact information about Jmodem you have to get the original
  28.   documents included in the JMODEM package for PC compatibles. I give you
  29.   only a quick overview of its features and shortcomings.
  30.  
  31.   Features:
  32.   o      16-bit CRC for efficient error detection
  33.   o      File size maintained, no "extra" characters as with Xmodem
  34.   o      A limited form of automatic data compression
  35.   o      Rapid syncronization, usually only 1 or 2 bytes needed for
  36.          handshaking
  37.   o      Variable length transmission blocks, transfer starts with small
  38.          blocks, but grow if few line errors occur.
  39.   o      There is no minimum size for transmission blocks, if 2 characters
  40.          remain to be sent, 2 characters are indeed sent (+ block header),
  41.          not 128 as with Xmodem or Ymodem
  42.   o      Aborted files are saved, 0 length files are automatically deleted
  43.   o      Files being overwritten are renamed by appending ".old" to their
  44.          file name, rather than deleted
  45.  
  46.   Shortcomings:
  47.   o      File name, size and modification date is not transferred, as in
  48.          Ymodem, Zmodem, Megalink etc.
  49.   o      The protocol requires acknowledge of every block, thus decreasing
  50.          efficiency. This may not be a shortcoming, it increases reliability
  51.          in case the line is suddenly dropped without warning. Protocols like
  52.          Zmodem and Megalink do not, however, require receiver acknowledge of
  53.          all blocks.
  54.   o      XON/XOFF characters are not escaped. This is even more serious as
  55.          the block sizes are large, creating problems with slow disk drives
  56.          and high transmission speeds. This should not be a problem under
  57.          9600 baud, though.
  58.      
  59.   Compression:
  60.   The compression algorithm used by Jmodem is only guaranteed not to
  61.   *increase* the block size, often the simple compression method will not
  62.   produce good results. Files already compressed will gain nothing by the
  63.   Jmodem compression. The algorithm applied is Run-Length-Encoding, which
  64.   encodes repeated characters into a 4 byte structure consisting of a
  65.   "sentinel" byte ($BB), two bytes of repetition count (low byte first), and
  66.   the byte to repeat. All blocks to be sent are first compressed, but only
  67.   if the compressed version is smaller than the original is it actually used.
  68.   The block header specifies if a block is compressed or not so that the
  69.   receiver will know if it must be decompressed before written to disk.
  70.  
  71.   Synopsis:
  72.   JModem <device name> <unit number> <baud rate> {R|S} <file name> ....
  73.  
  74.   where
  75.   <device name>   usually serial.device. Be careful with this one, upper
  76.                   and lower case characters mean different things. Always
  77.                   use lower case.
  78.   <unit number>   the device unit to use, normally 0
  79.   <baud rate>     values between (and including) 110 and 19200 are allowed.
  80.                   Parity, databits and stopbits can not be specified, JModem
  81.                   always uses N,8,1 (no parity, 8 databits, 1 stopbit).
  82.   {R|S}           use R if you want to receive, S to send.
  83.   <file name>     the file to send or receive.
  84.   ...             specifies optional file names, amount limited only by the
  85.                   length of the command line. Note that the PC version of
  86.                   Jmodem allows only one file to be transferred, so the other
  87.                   end might not implement several file names.
  88.  
  89.   Examples:
  90.   JModem serial.device 0 1200 S df0:upload/JModem.zoo
  91.   This command line sends the file JModem.zoo to the remote system using a
  92.   1200 baud connection (try this one out, just to see if it works, eh ;-)
  93.  
  94.   JModem serial.device 0 2400 r DL:SuperGame DL:SuperGame.info
  95.   Download two files, SuperGame and SuperGame.info into the DL: logical
  96.   directory using 2400 baud.
  97.  
  98.   Status information:
  99.   Once started, JModem opens a window on the first intution screen which is
  100.   used to display information about the proceeding and current state of the
  101.   transfer process.
  102.  
  103.   = JModem v.1.0 send/receive ==================
  104.   |                                            |
  105.   | File name         :                        |
  106.   | File size         :                        |
  107.   | Block number      :                        |
  108.   | Block size        :                        |
  109.   | Bytes transferred :                        |
  110.   | Status            :                        |
  111.   |     ---------                              |
  112.   |     | Abort |                              |
  113.   |     ---------                              |
  114.   |____________________________________________|
  115.  
  116.   The title specifies if we are trying to send or receive, along with the
  117.   Amiga version number.
  118.  
  119.   The file name displays the file we are currently receiving or sending.
  120.  
  121.   The file size is used only when sending, as we don't know the size of
  122.   the file when receiving.
  123.  
  124.   The block number is the block we are currently sending/receiving, block
  125.   numbers start from 1.
  126.  
  127.   The block size is the actual block size, after compression, block header
  128.   not included. The block size reflects the block currently in transfer,
  129.   as opposed with PC-JMODEM, which displays the block size of the previous
  130.   block, including block header (6 bytes). When sending, additional
  131.   information is displayed on how much, if any, compression is used, given
  132.   in per cent of the uncompressed block size.
  133.  
  134.   Bytes transferred is the *uncompressed* byte count, not the number of bytes
  135.   really transferred over the line. When sending, an additional value is
  136.   shown giving the amount, in per cent, remaining to be sent.
  137.  
  138.   The Status line displays error messages and status reports, such as the
  139.   block last transferred, transmission errors and retry counts etc.
  140.  
  141.   The Abort gadget:
  142.   The gadget can be used if you for some reason want to abort the transmission
  143.   in the middle. Do not be alarmed even if nothing happens immediately when
  144.   you release the button, as the program tries to inform the remote system
  145.   about the abortion to avoid the other end from being stuck waiting for
  146.   synchronization that will never occur, etc. This delay can be as long as
  147.   transmission of one block will take, which is a long time on low speeds and
  148.   large block sizes. Eventually the program will, however, abort.
  149.  
  150.   Return codes:
  151.   The protocol can be called from a script file to do batch transfers.
  152.   It returns with a return code which can be inspected by other AmigaDos
  153.   commands according to the following rules:
  154.  
  155.   o      If one or more files were succesfully transferred, the return
  156.          code reflects the number of files actually transferred, e.g. 1
  157.          is returned if one file was sent/received, 2 if two files were
  158.          sent/received etc.
  159.   o      If no files were transferred ERROR (return code 10) is returned.
  160.          It is inadvisable to supply 10 or more files on the command line
  161.          if you wish to check the return code, as 10 files successfully
  162.          sent would return the same same value as if no files were sent
  163.          at all.
  164.   o      If a fatal error occurred, FAIL (return code 20) is returned.
  165.          As fatal errors are treated illegal command line options, memory
  166.          shortage, unability to access necessary resources (e.g serial
  167.          device already in use or not found).
  168.  
  169.   Here AmigaDOS causes some problems. There is no support for testing
  170.   return codes other than OK (0), WARN (5), ERROR (10) and FAIL (20).
  171.   The easiest way to see that all went well is to supply only one file
  172.   name at a time, and check for ERROR after every transfer. If you give
  173.   several files at a time, and some are not transferred, you must use
  174.   nonstandard AmigaDOS commands or a command shell (Csh for example) 
  175.   which can test just how many files were transferred before something
  176.   went wrong.
  177.  
  178.   Usage:
  179.   This is a problem, to this date there exists no communication programs
  180.   to my knowledge that support external protocols. Until such a program
  181.   appears you have to manually include the JModem sources supplied with
  182.   this document into some communication program sources. This requires
  183.   extensive knowledge of C and may be overwhelming for novices.
  184.  
  185.   It is possible, although somewhat awkward, to use it with existing
  186.   programs by leaving the communication program when the file transfer
  187.   is to begin and starting it immediately afterwards. This requires that
  188.   the program doesn't initialize the modem when starting and that the
  189.   modem doesn't hangup if DTR is dropped.
  190.  
  191.   The reason why the communication program and JModem can't function in
  192.   parellell as two processes is that the serial device "splits" it's
  193.   output between everyone reading it, thus sending some characters to
  194.   JModem, and some to the communications program.
  195.  
  196.   Final notes:
  197.   This program has been thoroughly tested running JMODEM 1.20 on a
  198.   Sidecar, using a "null" modem cable between the Amiga and a PC
  199.   serial card on the Sidecar. If you find any problems or have anything
  200.   to comment concerning the program or its usage with existing or future
  201.   communications programs, please contact me on the address below.
  202.  
  203.   Quickest way:
  204.          Fidonet 2:515/170.3   (Point system under FTeam MultiBBS)
  205.          FTeam MultiBBS 2:515/170 +358-0-802 6206, 21/22bis, 24H WDAYS
  206.          F.I.Lighthouse 2:515/110 +358-0-672 773,  21/22bis, 24H
  207.  
  208.   Ancient compatibility:
  209.          Kenneth Osterberg
  210.          Kiviparintie 5 B 12
  211.          00920 HELSINKI
  212.          Finland
  213.          Europe
  214.  
  215.   Voice:
  216.          +358-0-349 2376
  217.