

                            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:

        <com device|com handle>

        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.

        <com speed>

        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<bytes> -- 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<dir>   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<bytes> -- Use a transmit window of <bytes> length (Z)

        Affects only to Zmodem transmissions. It makes us to wait for
        an acknowledge for every <bytes> 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.
        
        <protocol>

        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

        [<file|@listfile>...]

        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)

