P version 1.01 Copyright (c) 1994 by Jyrki Salmi This is a FREE file transfer protocol package for OS/2 2.x. The main goal in designing the program was to optimize it to use CPU time as little as possible and transfer data as fast as possible. Don't expect beatiful user interfaces... - - - Following protocols are supported: * Zmodem - Automatic file name, size and date information exchange - Full streaming and windowing - 32-bit and 16-bit CRC frame checking - Crash recovery - Control character escaping * Ymodem-g - Automatic file name, size and date information exchange - Continuos data flow - 128 and 1024 byte blocks - 16-bit CRC block checking * Ymodem - Automatic file name, size and date information exchange - 128 and 1024 byte blocks - 16-bit CRC and checksum block checking * Xmodem - 128 and 1024 byte blocks - 16-bit CRC and checksum block checking Command line parameters explained: Either the name of a standard OS/2 device, like COM1, COM2, etc. or an already open handle (a number) to such device. P recognizes one from the other by checking the first character of this parameter, if it's a non-digit it's the name of the device and if not, it's the handle. This parameter specifies the speed of connection in bits per second. It's used only for calculating the estimated transfer times. P *NEVER* changes the speed of the communication device, either the calling program or the user (with OS/2's MODE command) must setup the device. [options] You can enter any number (or none) of the following options in this place. All options must be preceded by '-' character and are to be separated by one or more spaces. -a -- Use the alternative error checking method All of the supported protocols but Ymodem-g has an alternative error checking method besides its default. Here is the list of default and alternative methods: Protocol Default Alternative -------- ------- ----------- Zmodem CRC-32 CRC-16 Ymodem-g CRC-16 - Ymodem CRC-16 checksum Xmodem checksum CRC-16 Only when using Zmodem, both the receiver and the sender can define the checking method to be used. Ymodem and Xmodem give this responsibility to the receiver, although the sender can ignore CRC-16 requests making the receiver fall-back into checksum, but this takes a while of timeoutting and isn't supported by P. -A -- send "rz\r" to the remote before the transfer (Z) This option affects only to Zmodem sending. It makes P to send a string "rz\r" to the remote while trying to initiate the transfer. If there's an UNIX shell running at the other end it will be interpreted as the user has just typed "rz" and then pressed enter, and the UNIX rz program will be run. If you aren't transferring files to an UNIX system this option just generates more garbage to the remote screen in intialization phase, in case it hasn't started receiving program yet. -b -- Define the size of communication buffers, default is 2048 With this option you can define the size of low-level input and output communication buffers. It has an effect only to the protocols sending and receiving data in continuous streams: Zmodem and Ymodem-g. With a bigger value and a reliable connection you can speed up the throughput considerably. But if the connection requires retransmits, a bigger value can slow down the throughput much more and generate a lot of annoying garbage to the remote screen after the transfer has been cancelled. For example if you specify 32768 bytes long buffers we will block in read or write routine until we get it all read or written. If you're sending with Zmodem and there is an error in transmission, it won't be recovered until all data in the buffers is transferred. And if you're using Ymodem-g the transfer will be aborted in case of an error, all data in buffers will be written to the remote screen until we recognize the abortation. And when receiving with Zmodem or Ymodem-g, we won't check for possible transmission errors until we have received the whole buffer, making us potentially transferring a lot of data that's to be resent. There's no maximum limit for the size of buffers. The bigger you specify the more memory will we eaten. Under multitasking environments like OS/2, bigger buffers will make us to use a bit less processor time. -c -- Rename file if it already exists This option has an effect only when receiving files. It makes us to check for existance of the file to be received instead of simply overwriting. If the file already exists, the new file will be written with an other name. For example, if we are to receive file named FILE.ZIP and we already have one with an identical name. The new file will be renamed to FILE.ZI0, and if we receive yet another copy of it with -c option specified it will be named as FILE.ZI1, and so on. NOTE: This file renaming algorithm is bit brain-dead. For example, if you're receiving FILE.C and you already have one, It will be named as FILE.0, instead of FILE.C0, which sounds much more logical. The reason for this is that we don't want to change the length of the file name, because it might cause problems on file systems supporting different maximum name lengths. -d -- Disable carrier watch This option makes us to ignore the state of carrier detect signal. Use it if your modem or serial cable can't pass it. Also, if you're using null-modem cable to transfer files between two machines, you might want to disable the carrier watch. -D Define the download directory With this option you can specify where all received files will be saved. If not specified, they will be saved in the current directory. This option will be ignored if -f option (receive/send full paths) has been defined. -e -- Escape all control characters (Z) This affects only to Zmodem sending and receiving. It makes us to escape all control characters (ASCII 0 to 31). Escaping generates overhead by transmitting two bytes to represent every control character. Use it only if your connection can't pass them through. NOTE: Ymodem-g, Ymodem and Xmodem do not support any kind of escaping and they require a totally transparent 8-bit connection. NOTE: This option is ignored when the -m option is specified. -f -- Send/receive full paths (Z and Y) By this option you make us to send file path information just as it was given on the command-line or in the list file. The other end can however still strip the drive and directory information and use the plain file name. When receiving be careful with this option. Other end can send files to any drive and directory on your system, even viruses and trojans. When this option is *NOT* used, all drive and directory information will be stripped. All files will be received to the receive directory and if not specified, to the current directory. -F -- Don't remove failed files By default we remove all files whose transfer was aborted or failed for some other reason. If this option is specified we will keep what we have got transferred, making it possible for Zmodem to crash recover from it later. -k -- Use 1024 byte blocks instead of 128 byte (X and Y) This affects only to Ymodem-g, Ymodem and Xmodem sending. It makes us to send data in 1024 byte blocks instead of 128 byte, speeding up the transfer considerably on high speed connections. However, the probability of garbled data getting through grows when there is more data to calculate the check value from, thus you should avoid using 1024 byte blocks with checksum checking. NOTE: When receiving, it's up to the remote to define the block size. -m -- Minimal escaping (Z) By default P escapes following characters in the data flow when transferring with Zmodem: ASCII 16 (Ctrl-P) ASCII 144 (Ctrl-P with 8th bit set) ASCII 17 (*) (XON) ASCII 145 (*) (XON with 8th bit set) ASCII 19 (*) (XOFF) ASCII 147 (*) (XOFF with 8th bit set) ASCII 24 (*) (Ctrl-X) ASCII 152 (Ctrl-X with 8th bit set) And these if they follow an ASCII 64 ('@') or ASCII 192 ('@' with 8th bit set): ASCII 13 (Carriage return) ASCII 141 (Carriage return with 8th bit set) However, modern hardware and software, when properly configured, do not need all this escaping. By specifying the -m option you tell P that it should escape only those characters (marked with asterisks) that are absolutely necessary for the protocol to work with standard implementations, which might increase the throughput somewhat. NOTE: This option overrides the -e option. -p -- Wait for a keypress after the transfer This option might be useful if you're using P to provide external protocols for some program that clears the screen after the transfer. By using this option P waits for a keypress after the transfer, providing you time to read the messages concerning the transfer. -r -- Recover crashed transfers (Z) When a transfer has crashed in the middle of the file, it's possible to recover from that and continue the transfer just from there where it crashed. This requires that we have the already transferred part of the file saved on the disk, ie. file must have been transferred with the option -F specified. NOTE: Only Zmodem supports crash recovery. -v -- Show received headers' types and contents (Z) This only affects to Zmodem transfers and it's intented purely for debugging and trouble-shooting purposes. It makes P to display the type of every received Zmodem header and its contents. You shouldn't bother yourself with this if you aren't familiar with Zmodem internals. -V -- Show sent frameends (Z) This also affects only to Zmodem transfers and is purposed to help debugging. It makes P to show transferred frameends. -w -- Use a transmit window of length (Z) Affects only to Zmodem transmissions. It makes us to wait for an acknowledge for every transferred, when the default is sending data in full streaming, without acknowledges. Using this might be necessary if you're sending data through a network where sone nodes of that network might timeout if there isn't data transferred to one direction for some time. Using a small window size slows down the transfer somewhat. NOTE: Window size must be a multiple of 64, the minimum value is 256 and the maximum is 65472. With this parameter you define the protocol to be used and whether to send or receive files. The transmission direction is figured out from the first character of this parameter. 's' represents sending and 'r' receiving, any other will cause an error message. The second character represents the protocol type: x Xmodem y Ymodem g Ymodem-g z Zmodem [...] The rest of the command-line is for paths to files to be sent or received. If you have a lot of files to transfer you might want to use a list file instead specifying them all on the command-line. List files are plain ASCII files containing file paths on separate lines. List file paths are distinguished from the normal file paths from the preceding '@' character. You can mix up any number of files and list files on the command-line. When sending files, the use of these file paths is obvious, those files are to be sent. If the file specified can't be opened by P, either it doesn't exist or it's used by an another application, it will be skipped. You can specify any number of files to be transferred with protocols that support batch transmissions, that is all but Xmodem. With Xmodem you can specify only one file, whether you are receiving or sending. When receiving with a protocol supporting batch transfers you don't have to specify any files at all. However, if you will, only those files specified will be received. If you are receiving with Zmodem the files not found on the command-line will be skipped. With Ymodem, the transfer will be aborted, because the protocol does not support skipping. - - - If you intend to use P with a bulletin board software you might want to use a DSZ log. DSZ logs are used to tell the BBS software whether the file transfer was succesful or not. All you have to do is to define an enviroment variable DSZLOG that points to the file defined as DSZ log in your BBS's configuration. Refer to its manual for detailed information. If no DSZLOG variable has been defined, no DSZ log will be created. - - - Yup, that's it folks. Hope you find some use for this. If you have any problems, questions or you just want to give a comment, drop me a note: Internet: jytasa@jyu.fi FidoNet: Jyrki Salmi (2:225/12)