JMODEM File Transfer Protocol, Amiga Version 1.0 --------------------------------------------------- Based on original implementation version 1.20 by Richard B. Johnson for IBM PC compatibles. Amiga port made by Kenneth Osterberg, released into public domain June 10, 1989. These files are supplied in the archive file: JModem The executable program, compiled with Manx Aztec C 3.4a JModem.c The C source file which implements the protocol protsupp.c Some support routines which handle serial device receive/send (with true timeouts) and simplified intuition window management. protsupp.h Header file included by JModem.c, defines constants and functions in protsupp.c docrc.asm The assembler source which does the CRC calculation Makefile Makefile how to compile the modules. I didn't use Aztec make, so you might have to change one or two things, but you get the idea. JAmiga.txt This documentation The program is implemented as an "external protocol", as is customary in the IBM-PC world. This has many advantages, but limits its usage until programs appear which can handle this feature in an efficient way. Introduction to JMODEM: If you want exact information about Jmodem you have to get the original documents included in the JMODEM package for PC compatibles. I give you only a quick overview of its features and shortcomings. Features: o 16-bit CRC for efficient error detection o File size maintained, no "extra" characters as with Xmodem o A limited form of automatic data compression o Rapid syncronization, usually only 1 or 2 bytes needed for handshaking o Variable length transmission blocks, transfer starts with small blocks, but grow if few line errors occur. o There is no minimum size for transmission blocks, if 2 characters remain to be sent, 2 characters are indeed sent (+ block header), not 128 as with Xmodem or Ymodem o Aborted files are saved, 0 length files are automatically deleted o Files being overwritten are renamed by appending ".old" to their file name, rather than deleted Shortcomings: o File name, size and modification date is not transferred, as in Ymodem, Zmodem, Megalink etc. o The protocol requires acknowledge of every block, thus decreasing efficiency. This may not be a shortcoming, it increases reliability in case the line is suddenly dropped without warning. Protocols like Zmodem and Megalink do not, however, require receiver acknowledge of all blocks. o XON/XOFF characters are not escaped. This is even more serious as the block sizes are large, creating problems with slow disk drives and high transmission speeds. This should not be a problem under 9600 baud, though. Compression: The compression algorithm used by Jmodem is only guaranteed not to *increase* the block size, often the simple compression method will not produce good results. Files already compressed will gain nothing by the Jmodem compression. The algorithm applied is Run-Length-Encoding, which encodes repeated characters into a 4 byte structure consisting of a "sentinel" byte ($BB), two bytes of repetition count (low byte first), and the byte to repeat. All blocks to be sent are first compressed, but only if the compressed version is smaller than the original is it actually used. The block header specifies if a block is compressed or not so that the receiver will know if it must be decompressed before written to disk. Synopsis: JModem {R|S} .... where usually serial.device. Be careful with this one, upper and lower case characters mean different things. Always use lower case. the device unit to use, normally 0 values between (and including) 110 and 19200 are allowed. Parity, databits and stopbits can not be specified, JModem always uses N,8,1 (no parity, 8 databits, 1 stopbit). {R|S} use R if you want to receive, S to send. the file to send or receive. ... specifies optional file names, amount limited only by the length of the command line. Note that the PC version of Jmodem allows only one file to be transferred, so the other end might not implement several file names. Examples: JModem serial.device 0 1200 S df0:upload/JModem.zoo This command line sends the file JModem.zoo to the remote system using a 1200 baud connection (try this one out, just to see if it works, eh ;-) JModem serial.device 0 2400 r DL:SuperGame DL:SuperGame.info Download two files, SuperGame and SuperGame.info into the DL: logical directory using 2400 baud. Status information: Once started, JModem opens a window on the first intution screen which is used to display information about the proceeding and current state of the transfer process. = JModem v.1.0 send/receive ================== | | | File name : | | File size : | | Block number : | | Block size : | | Bytes transferred : | | Status : | | --------- | | | Abort | | | --------- | |____________________________________________| The title specifies if we are trying to send or receive, along with the Amiga version number. The file name displays the file we are currently receiving or sending. The file size is used only when sending, as we don't know the size of the file when receiving. The block number is the block we are currently sending/receiving, block numbers start from 1. The block size is the actual block size, after compression, block header not included. The block size reflects the block currently in transfer, as opposed with PC-JMODEM, which displays the block size of the previous block, including block header (6 bytes). When sending, additional information is displayed on how much, if any, compression is used, given in per cent of the uncompressed block size. Bytes transferred is the *uncompressed* byte count, not the number of bytes really transferred over the line. When sending, an additional value is shown giving the amount, in per cent, remaining to be sent. The Status line displays error messages and status reports, such as the block last transferred, transmission errors and retry counts etc. The Abort gadget: The gadget can be used if you for some reason want to abort the transmission in the middle. Do not be alarmed even if nothing happens immediately when you release the button, as the program tries to inform the remote system about the abortion to avoid the other end from being stuck waiting for synchronization that will never occur, etc. This delay can be as long as transmission of one block will take, which is a long time on low speeds and large block sizes. Eventually the program will, however, abort. Return codes: The protocol can be called from a script file to do batch transfers. It returns with a return code which can be inspected by other AmigaDos commands according to the following rules: o If one or more files were succesfully transferred, the return code reflects the number of files actually transferred, e.g. 1 is returned if one file was sent/received, 2 if two files were sent/received etc. o If no files were transferred ERROR (return code 10) is returned. It is inadvisable to supply 10 or more files on the command line if you wish to check the return code, as 10 files successfully sent would return the same same value as if no files were sent at all. o If a fatal error occurred, FAIL (return code 20) is returned. As fatal errors are treated illegal command line options, memory shortage, unability to access necessary resources (e.g serial device already in use or not found). Here AmigaDOS causes some problems. There is no support for testing return codes other than OK (0), WARN (5), ERROR (10) and FAIL (20). The easiest way to see that all went well is to supply only one file name at a time, and check for ERROR after every transfer. If you give several files at a time, and some are not transferred, you must use nonstandard AmigaDOS commands or a command shell (Csh for example) which can test just how many files were transferred before something went wrong. Usage: This is a problem, to this date there exists no communication programs to my knowledge that support external protocols. Until such a program appears you have to manually include the JModem sources supplied with this document into some communication program sources. This requires extensive knowledge of C and may be overwhelming for novices. It is possible, although somewhat awkward, to use it with existing programs by leaving the communication program when the file transfer is to begin and starting it immediately afterwards. This requires that the program doesn't initialize the modem when starting and that the modem doesn't hangup if DTR is dropped. The reason why the communication program and JModem can't function in parellell as two processes is that the serial device "splits" it's output between everyone reading it, thus sending some characters to JModem, and some to the communications program. Final notes: This program has been thoroughly tested running JMODEM 1.20 on a Sidecar, using a "null" modem cable between the Amiga and a PC serial card on the Sidecar. If you find any problems or have anything to comment concerning the program or its usage with existing or future communications programs, please contact me on the address below. Quickest way: Fidonet 2:515/170.3 (Point system under FTeam MultiBBS) FTeam MultiBBS 2:515/170 +358-0-802 6206, 21/22bis, 24H WDAYS F.I.Lighthouse 2:515/110 +358-0-672 773, 21/22bis, 24H Ancient compatibility: Kenneth Osterberg Kiviparintie 5 B 12 00920 HELSINKI Finland Europe Voice: +358-0-349 2376