The Puma Protocol(TM) v1.00 User's Manual Copyright (C)1990 by Matthew Thomas All Rights Reserved The Puma Protocol(TM) v1.00 User's Manual T a b l e o f C o n t e n t s __________________________________________________________________ 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 1 Features. . . . . . . . . . . . . . . . . . . . . . . . . . 1 Licensing . . . . . . . . . . . . . . . . . . . . . . . . . 1 Customer Support. . . . . . . . . . . . . . . . . . . . . . 2 2. Getting Started. . . . . . . . . . . . . . . . . . . . . . . 3 The Help Screen . . . . . . . . . . . . . . . . . . . . . . 3 The Setup Program . . . . . . . . . . . . . . . . . . . . . 3 3. The Puma Program . . . . . . . . . . . . . . . . . . . . . . 4 Running Puma. . . . . . . . . . . . . . . . . . . . . . . . 4 Program Options . . . . . . . . . . . . . . . . . . . . . . 4 A+/- Delete aborted downloads. . . . . . . . . . . . . . 5 B+/- Beep upon completion. . . . . . . . . . . . . . . . 5 CDSx Log to a CDS file . . . . . . . . . . . . . . . . . 5 D+/- Stamp with current date . . . . . . . . . . . . . . 5 Ex Effective baud rate . . . . . . . . . . . . . . . . 6 F+/- Enable 16550A FIFO buffers. . . . . . . . . . . . . 6 HF Handshake fast. . . . . . . . . . . . . . . . . . . 7 HD Handshake on disk writes. . . . . . . . . . . . . . 7 HN No handshaking. . . . . . . . . . . . . . . . . . . 8 HS Handshake slow. . . . . . . . . . . . . . . . . . . 8 Lx Log to a DSZ file . . . . . . . . . . . . . . . . . 8 N+/- monitor the carrier signal. . . . . . . . . . . . . 9 O+/- allow overwriting received files. . . . . . . . . . 9 Px COM port number . . . . . . . . . . . . . . . . . . 9 R+/- allow resumed transfers . . . . . . . . . . . . . . 9 Sx UART baud rate. . . . . . . . . . . . . . . . . . . 10 M+/- Hangup modem when finished. . . . . . . . . . . . . 10 W+/- Wait for keystroke when finished. . . . . . . . . . 10 X+/- Enable RLE compression. . . . . . . . . . . . . . . 10 Sender File Specifications. . . . . . . . . . . . . . . . . 11 Receiver File Specifications. . . . . . . . . . . . . . . . 12 Exit Codes. . . . . . . . . . . . . . . . . . . . . . . . . 12 Examples. . . . . . . . . . . . . . . . . . . . . . . . . . 13 4. The Puma Display . . . . . . . . . . . . . . . . . . . . . . 14 Screen Access . . . . . . . . . . . . . . . . . . . . . . . 14 Colors. . . . . . . . . . . . . . . . . . . . . . . . . . . 14 The Help Screen . . . . . . . . . . . . . . . . . . . . . . 14 Batch Status. . . . . . . . . . . . . . . . . . . . . . . . 15 Current File Status . . . . . . . . . . . . . . . . . . . . 15 Throughput Efficiency . . . . . . . . . . . . . . . . . . . 15 UART. . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 Stats . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 Display Footer. . . . . . . . . . . . . . . . . . . . . . . 17 Messages. . . . . . . . . . . . . . . . . . . . . . . . . . 17 The Puma Protocol(TM) v1.00 User's Manual 5. The Setup Program. . . . . . . . . . . . . . . . . . . . . . 21 Main Menu . . . . . . . . . . . . . . . . . . . . . . . . . 21 Change Default Options. . . . . . . . . . . . . . . . . . . 21 Adjust Screen Colors. . . . . . . . . . . . . . . . . . . . 22 Install Registration Information. . . . . . . . . . . . . . 22 Quit and Save Settings. . . . . . . . . . . . . . . . . . . 23 6. Acknowledgments. . . . . . . . . . . . . . . . . . . . . . . 24 Inside. . . . . . . . . . . . . . . . . . . . . . . . . . . 24 Outside . . . . . . . . . . . . . . . . . . . . . . . . . . 24 Trademarks and Products . . . . . . . . . . . . . . . . . . 25 Appendices A. Log File Formats . . . . . . . . . . . . . . . . . . . . . . 26 Enhanced DSZ Log Format . . . . . . . . . . . . . . . . . . 26 CDS Log Format. . . . . . . . . . . . . . . . . . . . . . . 26 B. Benchmarks . . . . . . . . . . . . . . . . . . . . . . . . . 29 C. Puma Auto-Start Receive. . . . . . . . . . . . . . . . . . . 31 D. Suggested Reading. . . . . . . . . . . . . . . . . . . . . . 32 The Puma Protocol(TM) v1.00 User's Manual 1 - I n t r o d u c t i o n __________________________________________________________________ FEATURES The Puma Protocol(TM) is a powerful tool for getting your data from one place to another through a serial link. Whether downloading or uploading files to and from a bulletin board system, or moving files between PC compatible computers over a serial cable without a modem, you will find that Puma will do the job, and will do it quickly and accurately. Puma offers many advanced features: þ Full color screen display of transfer status. þ Standalone setup program for changing default options, configuring screen colors, and installing registration information. þ UART (serial port) baud rates up to 115200 bps. þ Auto-sensing of 8250, 16450, 16550, and 16550A UARTs. Full support for 16550A FIFO buffers. þ The ability to use COM ports 1 through 4, with each port's IRQ and base I/O address fully configurable. þ Call Data Standard (CDS) logging of file transfers. þ Enhanced DSZ compatible logging of file transfers. þ All screen operations use direct video memory access, or DESQview, TaskView, OmniView, TopView, Microsoft Windows, and IBM 3270 PC multi-tasking video buffers (MTVB), if present. þ Optional auto-start of Puma receiver. þ Optional data compression on a block level using RLE techniques. þ Fast and reliable recovery from line and data errors. þ Dynamic block scaling for optimal data throughput. þ Up to 99 files transferred in a batch. þ and many more features... LICENSING The Puma Protocol and its accompanying documentation have been released as Shareware. This gives you the chance to experience the performance of the software for a 30 day evaluation period. If you continue to use Puma beyond this period, you are required to register. Information on becoming a registered user of the Puma Protocol can be found in the file LICENSE.TXT. The author specifically disclaims all warranties, expressed or implied, including but not limited to implied warranties of merchantability and fitness for a particular purpose and the program license granted herein in particular, and without limiting operation of the program license with respect to any particular application, use, or purpose. In no event shall the author be liable for any loss of profit, lost savings, commercial damage, or Page 1 The Puma Protocol(TM) v1.00 User's Manual other incidental or consequential damages arising out of the use or inability to use Puma even if the author, Matthew Thomas, or an authorized distributor of the Puma Protocol has been advised of the possibility of such damages, or for any claim by any other party. This agreement shall be governed by the laws of the state of Wisconsin. CUSTOMER SUPPORT Full support to users of the Puma Protocol is available through three channels. To contact the author with questions, suggestions, problems, or other comments, 1) Call the PC Access BBS at (414) 634-5776, and send E-Mail to Matt Thomas. PC Access supports up to 2400 baud MNP modems. or 2) Call the Exec-PC BBS at (414) 789-4210, and send E-Mail to Matt Thomas. or 3) Contact any bulletin board system that carries the MetroLink Lynx/Puma conference. Leave a message to Matt Thomas, and make sure to echo the message when you send it. Messages left in this conference will reach the author through the message network. or 4) Drop a note via US Mail to: Matt Thomas Lynx Development 144 Westminster Square Racine, WI 53402 The author offers limited support to unregistered users of The Puma Protocol, in order to help them get the program installed for evaluation. If you have a problem installing or using Puma, and you have read this entire User's Manual (please do read the manual before requesting help; many times problems can be cleared up by finding the answer in the manual), then feel free to request help through any of the channels mentioned above. The author of Puma will make an attempt to answer all mail received, but please be aware that registered users have first priority for support. Page 2 The Puma Protocol(TM) v1.00 User's Manual 2 - G e t t i n g S t a r t e d __________________________________________________________________ For experienced users who wish to get a quick start using the Puma Protocol, this brief chapter has been included to help you along. For a complete explanation of how to use Puma and the Puma setup program, continue reading beyond this chapter. THE HELP SCREEN When you run Puma the first time, try executing PUMA.EXE without parameters. You will see a screen full of information about command line options. This screen is your "quick reference" card, so to speak. It will help you to get Puma running if you choose not to read the rest of the documentation right away. THE SETUP PROGRAM Also included with Puma is a file called PUMASET.EXE. This program allows you to change Puma's default options and screen colors, and to enter registration information. In order for the setup program to operate, you must be logged to the drive and directory containing the PUMA.EXE file (the Puma Protocol program). Type PUMA, and press enter. If the setup program cannot read the PUMA.EXE file in the current directory, or the file has been corrupted, you will be alerted. Much of the setup program is self-explanatory, but a few things might not be obvious without some explanation: þ When choosing a baud rate for the UART, the value of "Current" will cause Puma to sense and use the current baud rate of the UART when PUMA.EXE is executed. þ When choosing an "effective" baud rate, the value of "UART" will cause Puma to use the UART baud rate (whether specified or auto-sensed) as the "effective" baud rate. þ In the "Adjust screen colors" mode, pressing the M key will cause the color scheme to change to monochrome. If you use a monochrome monitor, you may wish to use this option immediately upon entering the color set screen. To return to the default color set, press the C key. Note that both of these keys will destroy any changes you have made to the color set before saving! þ In the "Change default options" screen, the options that you choose will be written to the PUMA.EXE file as defaults. When running Puma, you may override any of these defaults by using command line parameters, detailed in Chapter 3. Page 3 The Puma Protocol(TM) v1.00 User's Manual 3 - T h e P u m a P r o g r a m __________________________________________________________________ This chapter will familiarize you with the Puma Protocol, and its features and command line parameters. RUNNING PUMA To load and run the Puma program, a command line must be given. This command line can come from the keyboard, at the MS-DOS prompt, from a batch file, or from a calling program, such as a BBS, which loads Puma directly without using the DOS command.com program. This command line has a specific syntax. Here are the three general formats for the Puma command line: puma [options] s filespec [filespec] [filespec] [...] puma [options] s @listfile puma [options] r [path] Anything appearing in square brackets is optional, and may not need to be specified for proper operation of Puma. Note that Puma completely ignores the "case" of the command line, which means that both upper- and lowercase characters may be mixed in any combination. The word "puma" at the beginning of each command line is required in all cases. This is what tells MS-DOS to load the PUMA.EXE program file. The "options" are outlined below, in the "Program Options" section. The "s" and "r" letters, which follow the options, are required on the command line. The letter "s" tells Puma to send files to another computer, while "r" tells Puma to receive files from another computer. The "filespec", "@listfile", and "path" portions of the command lines are described below, in the sections entitled "Sender File Specifications" and "Receiver File Specifications". PROGRAM OPTIONS The Puma Protocol offers a number of features and settings. This section will explain each command line option, and how each affects Puma operation. Note that a plus (+) in the syntax enables an option, while a minus (-) disables it. Page 4 The Puma Protocol(TM) v1.00 User's Manual Following is a description of each option: ------------------------------------ A+ or A- (delete aborted downloads) ------------------------------------ If enabled (A+), this setting will cause Puma to delete the transferred portion of any files that were not fully received. If disabled (A-), this setting will cause Puma to leave any partially received files on the disk. This gives the user the option of continuing the transfer later, by using the "Allow Resumed Transfers" option. Note: This parameter has no effect when used in the Puma send mode. -------------------------------- B+ or B- (beep upon completion) -------------------------------- Enabling this setting causes Puma to emit a series of beeps to alert the user when a transfer is finished. The beeper will sound regardless of whether the transfer was a success. Disabling this setting causes Puma to remain silent at all times. ------------------------- CDSx (log to a CDS file) ------------------------- This option allows the user to specify a log file where Puma will create a CDS log entry for each file transferred. You may replace "x" with any valid DOS drive:\path\file combination. If only "CDS" is specified, with no value for "x", a CDS log entry will not be written to any file. For example, the following command line will receive files, and each will be logged using CDS to the file "c:\logs\pumalog": puma CDSc:\logs\pumalog r Whereas, the following receiver command line will not log the files in CDS format: puma CDS r For information on the CDS log format, see Appendix A, "Log File Formats". ----------------------------------- D+ or D- (stamp with current date) ----------------------------------- This setting, when enabled, will cause Puma to stamp each received file with the current time and date of the transfer. Page 5 The Puma Protocol(TM) v1.00 User's Manual When this setting is disabled, Puma will stamp the file with the original time and date that are passed in a header packet at the beginning of each file transfer. This is a useful setting for BBS SysOps who wish to date-stamp their files according to when they were uploaded. Note: The D+/- option has no effect when used in the Puma send mode. ------------------------- Ex (effective baud rate) ------------------------- When using this option, the "x" may be replaced by a numeric value between 0 and 115200, inclusive. A non-zero value will adjust the effective baud rate to the specified value. A value of zero will cause Puma to set the effective baud rate to the same value as the UART baud rate. See the section below entitled, "Sx (UART baud rate)" for information on UART baud rates. * * * * * * * * * * * Effective Baud Rates * * * * * * * * * * * Typically, the baud rate of the UART (serial port) is displayed and logged by communications programs as the baud rate used during the session. However, many modems communicate with the computer at one baud rate, while communicating over the phone line at a different baud rate. For example, the USRobotics Courier 14400 HST modem can communicate with another Courier HST modem at an effective baud rate of 14400 bits per second. However, the modem is actually communicating with the UART at 19200 bps. Because of this difference in UART baud rate and effective baud rate, Puma allows each to be specified separately. Puma will use the effective baud rate to calculate estimated transfer times and efficiency percentages which are displayed during a transfer. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * -------------------------------------- F+ or F- (enable 16550A FIFO buffers) -------------------------------------- This option is only effective when the COM port in use has a 16550A UART installed. When enabled, this setting allows Puma to enable the FIFO buffers on the 16550A, and to use them during the transfer. When this setting is disabled, the FIFO buffers will be disabled during the transfer. Puma will always return the UART to the state it was in when Puma began. In almost all cases, this setting should remain enabled. The disable option is provided for users who wish to emulate the 16450 UART with a 16550A UART during Puma transfers. Page 6 The Puma Protocol(TM) v1.00 User's Manual -------------------- HF (handshake fast) -------------------- This setting enables fast hardware handshaking during Puma file transfers. If you are unsure whether to use hardware handshaking, it is a good idea to consult your modem manual. Most 300, 1200, and 2400 baud modems do not use hardware handshaking. However, MNP modems do, as do high-speed modems, such as the USR Courier 14400 HST, and the USR HST/Dual Standard. When using Puma to transfer files over a direct-connect link between two computers, hardware handshaking may not be necessary, but should be enabled in case one computer sends faster than the other can receive. * * * * * * * * * * * Hardware Handshaking * * * * * * * * * * * Hardware handshaking uses two pins on the serial port, called CTS (an input), and RTS (an output) to arbitrate data flow to and from the serial port. The rules of CTS/RTS handshaking are fairly easy to understand: 1) Data may be sent to a serial port as long as the CTS line is high. If the CTS line goes low, the sender must stop transmitting data until CTS again goes high. 2) When ready to receive data, the receiver must raise the RTS line. If, at some point, the receiver cannot receive data, it must lower the RTS line until data can be received again. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * ------------------------------ HD (handshake on disk writes) ------------------------------ This setting enables fast hardware handshaking and disk write handshaking. Disk write handshaking causes Puma to lower the RTS line whenever data is being written to disk. This setting is useful for computers that have BIOS or DOS disk drivers that cause hardware interrupts to be disabled for extended periods of time. Puma can not read data from the UART while interrupts are disabled. As a result, it is not uncommon at baud rates of 9600 or more, to get "overrun errors". If the disk drivers are the cause of this problem, then this setting will very likely solve the problem. If overrun errors are continually occurring, you may need to use the HS parameter (detailed below). Page 7 The Puma Protocol(TM) v1.00 User's Manual Note: The HD parameter is typically used by the receiver (where disk writes occur). However, the sender may use this setting to force the receiver (on the other end) to use disk write handshaking. -------------------- HN (no handshaking) -------------------- This option completely disables CTS/RTS handshaking. -------------------- HS (handshake slow) -------------------- This setting enables slow hardware handshaking and disk write handshaking. Slow handshaking is useful for receiving files on a computer that is too slow to process received characters at the UART baud rate. In this situation, the RTS line is toggled to pace the sender to a speed suitable for the slow machine to process the data. If you are experiencing overrun errors while receiving files with Puma, try using the HD parameter (detailed above), or the HS parameter. If the errors continue, another possible solution is to install a 16550A UART in your serial port or internal modem. Puma supports the 16550A UART's provisions for buffering received data, which takes part of the load off of the CPU. Note: The HS parameter is typically used by the receiver. However, the sender may use this setting to force the receiver (on the other end) to use slow handshaking. ----------------------- Lx (log to a DSZ file) ----------------------- This option allows the user to specify a log file where Puma will create a DSZ log entry for each file transferred. You may replace "x" with any valid DOS drive:\path\file combination. If only "L" is specified, with no value for "x", a DSZ log entry will not be written to any file. For example, the following command line will receive files, and each will be logged using the DSZ format to the file "c:\logs\pumalog": puma Lc:\logs\pumalog r Whereas, the following receiver command line will not log the files in DSZ format: puma L r For information on the DSZ log format, see Appendix A. Page 8 The Puma Protocol(TM) v1.00 User's Manual -------------------------------------- N+ or N- (monitor the carrier signal) -------------------------------------- This setting, when enabled, will cause Puma to end if the DCD signal (carrier) is lost during a transfer. When this setting is disabled, Puma will ignore the state of the DCD signal. Note: BBS SysOps should enable this setting, so if a user drops carrier during a transfer, Puma will end, and control will be immediately restored to the BBS software. -------------------------------------------- O+ or O- (allow overwriting received files) -------------------------------------------- This setting, when enabled, allows Puma to overwrite existing files. For example, if a file header is received for "foo.bar", and a file of the same name already exists in the receive path, Puma will delete the old file and write the new one under the same name. If this setting is disabled, Puma will not allow a received file to overwrite another file. --------------------- Px (COM port number) --------------------- This setting tells Puma which COM port to use. The "x" may be replaced by a value between 1 and 4, inclusive. If the specified COM port is not installed, Puma will not attempt to use it. For information on COM port configurations, see Chapter 5, "The Puma Setup Program". ----------------------------------- R+ or R- (allow resumed transfers) ----------------------------------- This setting, when enabled, allows the Puma receiver to request a resumed transfer. For example, if a file header is received for "foo.bar", and a file of the same name already exists in the receive path, Puma will check to see if it is shorter than the expected length. If it is, a resume request will be sent, which will cause the transmitter to only send the remaining portion of the file. This feature is useful for recovering from a lost carrier signal, or an abnormal amount of line noise. When this setting is disabled, Puma will not attempt to resume any transfers. In this case, if a header for an existing file is received, Puma will check the "allow overwriting received files" setting before writing the new file to disk. Page 9 The Puma Protocol(TM) v1.00 User's Manual -------------------- Sx (UART baud rate) -------------------- When using this option, the "x" may be replaced by a numeric value between 0 and 115200, inclusive. A non-zero value will adjust the UART baud rate to the specified value. A value of zero will cause Puma to auto-detect and use the current UART baud rate when the Puma program is executed. * * * * * * * * * * * * UART Baud Rates * * * * * * * * * * * * * The UART is an integrated circuit that resides in a serial adaptor card, internal modem, or sometimes on the motherboard of your computer. UART is an acronym for Universal Asynchronous Receiver- Transmitter. This is a complicated way of saying "serial port". The serial port can communicate with external devices at various speeds, or baud rates. The UART baud rate setting of Puma adjusts this speed. If you're unsure about which value to use for the UART baud rate, try using the auto-detect value (0). You may wish to consult your modem manual for more information about which baud rates can be used to communicate with your modem. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * -------------------------------------- M+ or M- (hangup modem when finished) -------------------------------------- When this setting is enabled, Puma will lower the RTS and DTR signals at the end of the session. Most modems can be configured to "hang up" when the DTR signal is lowered. When this setting is disabled, Puma will end with the RTS and DTR signals set high. -------------------------------------------- W+ or W- (wait for keystroke when finished) -------------------------------------------- This setting, when enabled, causes Puma to wait for a keystroke at the end of a transfer before returning to DOS. If this setting is disabled, Puma will return control to DOS immediately after the session ends. ---------------------------------- X+ or X- (enable RLE compression) ---------------------------------- This setting, when enabled, allows Puma to use RLE compression where possible when transferring data. If either end of the Puma connection (sender or receiver) disables this parameter, RLE compression will not be used. Page 10 The Puma Protocol(TM) v1.00 User's Manual * * * * * * * * * * * * * RLE Compression * * * * * * * * * * * * Puma uses RLE compression techniques in an attempt to shorten blocks of data before they are transferred. Puma will never transmit a compressed block of data unless the compressed block is shorter than the original block. The compression routines in Puma are written in Turbo Assembler, and are quite efficient. However, at very high baud rates, when transferring pre-compressed files (such as those created by PKZIP) the overhead that is caused by Puma analyzing each block for compressibility can slow throughput slightly (especially on slower machines). Therefore, RLE compression can be disabled to allow for the greatest possible throughput on compressed files at high baud rates. Note that disabling RLE compression is typically only beneficial at baud rates above 9600 baud. Even most slow machines are fast enough to analyze and output data with compression enabled at baud rates up to 9600 baud very efficiently. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * SENDER FILE SPECIFICATIONS This version of the Puma Protocol is capable of sending up to 99 individual files in a single batch. Each file which is transmitted by Puma is preceded by a header packet which contains the name of the file, its length, the original time and date stamp, and other control information. The receiver reads these header packets to determine what the sender is transmitting. When invoking the sender command line, there are two distinct syntaxes for specifying files to transmit: puma [options] s filespec [filespec] [filespec] [...] puma [options] s @listfile In the first syntax, at least one file specification must be placed on the command line. Additional file specifications may be placed after the first. These file specifications may be actual filenames, including drive letter, and sub-directories, or may include wildcard characters (ie. *.*). Puma will parse each wildcard specification into individual file names. If more than 99 files are specified, Puma will send the first 99 files found. In the second syntax, a single absolute file specification (no wildcards) is specified on the Puma command line, immediately preceded by the @ symbol. Puma will read this file, expecting to find that it contains a list of file specifications (which may contain wildcard characters) each separated by CR/LF characters. For example, for the command line, puma s @c:\file.lst A file named "file.lst" must be placed in the root directory of drive C, which contains a list of file specifications to send. Page 11 The Puma Protocol(TM) v1.00 User's Manual RECEIVER FILE SPECIFICATIONS When receiving files with Puma, the syntax for the command line is as follows: puma [options] r [path] The "path" portion is optional, and may be any single drive:\path\filename combination. The purpose of the "path" is to tell Puma where to place all the files it receives. If a file name is specified in the "path" parameter, the file name portion will be ignored, because Puma determines file names from the information packet it receives for each file from the sender. Therefore, when specifying only a path (no filename), this parameter MUST end with a backslash character (\). For example, both of the following command lines are valid, and will cause the same result: puma r c:\download\myfile.ext puma r c:\download\ Because the first command line has no terminating backslash on the path parameter, the "myfile.ext" portion will be ignored, and all received files will be placed in the "c:\download\" directory. Puma allows a file name to be specified only because certain calling programs insist on passing it along with the receive path. If more than one path specification appears on the Puma command line in receive mode, the first one following the "r" parameter will be used. The remainder of the command line will be ignored. EXIT CODES When the Puma Protocol returns control to DOS at the end of a transfer, it will return a DOS exit code to the calling program. The following codes are returned by Puma: 0 Transfer was completed successfully 1 Transfer began, but ended without completing 2 Session ended before transfer began 3 Puma detected invalid registration information 4 Puma was invoked without any command line parameters Page 12 The Puma Protocol(TM) v1.00 User's Manual EXAMPLES Following are some examples of command line syntaxes: puma s c:\file1.txt (send a file using default options) puma hf s p1.exe p2.exe (send two files, use fast handshaking) puma s d:\*.* (send all files in root dir of d:) puma x+ s *.txt (send text files, allow compression) puma x- s *.zip (send ZIP files, don't try to compress) puma n- s @files.lst (send files in a list, ignore carrier) puma s9600 e2400 s *.* (send at 9600 bps, effective 2400 bps) puma p3 cdspuma.log r (receive files from COM3, log with CDS) puma r c:\files\ (receive into "c:\files\" directory) puma r \ (receive into root of current drive) puma a+ r (receive files, delete aborted downloads) puma ldsz.log r (receive with DSZ logging) puma r+ o+ r (receive, allow resume and overwriting) Page 13 The Puma Protocol(TM) v1.00 User's Manual 4 - T h e P u m a D i s p l a y __________________________________________________________________ This chapter will familiarize you with the Puma display, and the meaning of each item shown during a Puma session. SCREEN ACCESS When Puma is executed, the first thing it does is to put up a full screen display. If Puma is run under normal DOS conditions, all accesses to the screen will use direct memory access. In other words, Puma will put updated screen information directly into the memory on board the resident display adaptor, bypassing the slow BIOS and DOS routines that are the alternatives to this technique. Since protocol programs are often used in multitasking environments, where direct video access can cause conflicts on a "shared" monitor, Puma offers an alternative. When Puma is executed, the program checks for the presence of one of the following multitasking sub-systems: DESQview TaskView OmniView TopView Microsoft Windows IBM 3270 PC If one of these systems is active, and the Multitasking Video Buffers (MTVB) are enabled for the current process, Puma will direct all video access to the corresponding MTVB, instead of the physical memory on the display adaptor. This technique allows for complete display compatibility with the above list of multitasking sub-systems. COLORS The color scheme of the Puma display can be easily customized for color or monochrome displays by using the Puma Setup program. See Chapter 5, "The Setup Program", for more details. THE HELP SCREEN The help screen will appear when Puma is executed without any command line parameters. It is always available for quick reference to command line syntaxes. For detailed information about the options shown on the help screen, see Chapter 3, "The Puma Program". * * * Page 14 The Puma Protocol(TM) v1.00 User's Manual When Puma is executed with command line parameters, a status display will appear, filling the screen with information concerning the status of each transfer. The next few sections will explain the contents of each area of the display. BATCH STATUS This display area contains information on the entire batch transfer at hand. On the left side of the Batch status window are totals for the batch, and an estimated time of transfer. This is, as are all other estimates, based on the "effective baud rate", not the "UART baud rate". See Chapter 3, "The Puma Program", for more information on baud rates. On the right side of the window are current values for the progress of the batch. The Batch progress meter at the bottom reflects the percentage of completion for the entire batch. CURRENT FILE STATUS This display window contains information on the file which is currently being transferred. Of particular interest in this window is the "Last message" item. This is where all verbal messages are shown regarding Puma status. Message descriptions are discussed below, in the section entitled, "Messages". THROUGHPUT EFFICIENCY This window shows information concerning the estimated efficiency of the file transfer in progress. The "Compression" item shows "RLE" if the current block of data is compressed, or "none" if it is a normal block of data. This item may also show "disabled" if either end of the connection has specified the "X-" option on the command line, or disabled RLE compression using the setup program. The "Block size" meter reflects the length of the current block, from 64 bytes to 1024 (1K) bytes. Also shown in this window are average speed in characters per second, and an estimated efficiency in percentage of theoretical "maximum" efficiency. UART The UART status, or "modem light" display, gives the status of the signals that Puma uses on the serial port. Page 15 The Puma Protocol(TM) v1.00 User's Manual At the top of the UART window is shown the type of UART that is installed in the COM port that Puma is using. The recognized UARTs are: 8250B (INS8250 or INS8250-B) 16450 (NS16450, NS16C450, NS8250A, or INS82C50A) 16550 (NS16550) 16550A (NS16550A, NS16550AF) Puma will optionally use FIFO buffers, if the "enable 16550A FIFO buffers" option is enabled, and the UART type is 16550A. See Chapter 3, "The Puma Program", for more information on using the FIFO buffers. The remainder of the UART display shows the status of the transmit line (TXD), the receive line (RXD), the carrier detect line (DCD), the clear to send line (CTS), and the request to send line (RTS). The indicator next to each item will light when the corresponding signal is high or active. STATS The stats window shows some miscellaneous information about options. The indicator beside each item will normally be lit if the item is enabled, unless otherwise noted. Following is a brief description of each item: Beep - status of the "beep upon completion (B+/-)" option. Date - status of the "stamp with current date (D+/-)" option. DCD - status of the "monitor the carrier signal (N+/-)" option. Dele - status of the "delete aborted downloads (A+/-)" option. Hang - status of the "hangup modem when finished (M+/-)" option. FIFO - this indicator will be lit when FIFO buffers are used. Over - this indicator will be lit when the "allow overwriting received files (O+/-)" option is enabled. If the Puma receiver actually overwrites a file, this indicator will blink for the remainder of the transfer of that particular file. Resu - this indicator will be lit when the "allow resumed transfers (R+/-)" option is enabled. If the Puma receiver actually resumes a file, this indicator will blink for the remainder of the transfer of that particular file. Page 16 The Puma Protocol(TM) v1.00 User's Manual Virt - this indicator will be lit if Puma is using an MTVB (virtual screen) for display access. For more information on this item, see the section entitled, "Screen Access" near the beginning of this chapter. Wait - status of the "wait for keystroke when finished (W+/-)" option. DISPLAY FOOTER The footer line of the Puma display indicates miscellaneous items of interest. We'll cover them from left to right, as displayed on the screen: The far left section will contain "S" or "R", to indicate send or receive mode. Next is the COM port which Puma is using. The following two items are UART baud rate, labeled Ubps, and effective baud rate, labeled Ebps. These values are shown in bits per second. Next is the handshaking indicator. This will show the type of handshaking in use: N = None S = handshake slow D = handshake disk F = handshake fast Finally, on the far right, is the version number and User ID of the remote Puma Protocol driver. This item will show "unknown" until synchronization has been established with the remote protocol. MESSAGES There are a number of messages which may be conveyed to the user by the Puma Protocol. This section gives the most important messages and their meanings: SYNCHRONIZING Puma is attempting to communicate control information with the connecting protocol. This occurs at the beginning of each file being transferred. SYNCHRONIZATION FAILED Puma was unable to synchronize with the connecting protocol. SENDING/RECEIVING FILE Puma is synchronized and has begun the file transfer. Page 17 The Puma Protocol(TM) v1.00 User's Manual filename.ext DONE Transfer of "filename.ext" has completed successfully. filename.ext DELETED The partially received file, "filename.ext" has been deleted. This will only occur if the "delete aborted downloads" option is enabled. ERROR WRITING CDS/DSZ LOG FILE Puma had problems writing to a log file. ERROR AT BYTE xxxx: errortype This message indicates that Puma is attempting to recover from some type of line error. The value of xxxx shows the byte position in the current file where the error occurred. The errortype indicates what caused the error. There are seven causes for line errors: CRC - Puma detected an error when comparing CRCs. This is usually causes by line noise on a bad connection. Long - The Puma receiver received a block longer than 1K in length. This is typically a result of line noise "adding" spurious garbage characters into the bit stream. Short - The Puma receiver got a partial block, which was not complete. Duplicate - The Puma receiver received a block of data that had already been received successfully. Waiting - The Puma receiver is waiting for the next logical block in the sequence. Timeout - The receiver has not received a block of data within a reasonable time frame. Overrun - The Puma receiver has experienced a UART buffer overrun error. This is usually caused by slow receiver CPU's at high baud rates, slow disk BIOS or drivers, or multitasking receiving computers without a 16550A UART. For information on correcting this problem, see Chapter 3. ERROR READING FILE: filename.ext The Puma sender could not read the current file from disk. CANCELLED BY SENDER/RECEIVER The transfer was cancelled by the other end of the connection. CANCELLED The transfer has been cancelled locally by pressing the ESC key. Page 18 The Puma Protocol(TM) v1.00 User's Manual CARRIER LOST The DCD signal was lowered during the transfer. This will only be reported if the "monitor the carrier signal" option is enabled. FATAL TIMEOUT The sender received no response from the receiver within a reasonable amount of time. TOO MANY ERRORS More than twenty consecutive line errors occurred during the transfer. NOT ALLOWED TO OVERWRITE FILE The receiver got a file header for an existing file, and the "allow overwriting received files" option is disabled. CAN'T CREATE FILE The receiver can't create the file to be received. CAN'T WRITE TO DISK The receiver can't write received information to the disk file. * * * The following messages can occur only before the transfer begins, and will cause an ERRORLEVEL 2 to be returned to DOS. INVALID REGISTRATION INFORMATION The PUMA.EXE file contains an invalid UserID/Serial number combination. INVALID PARAMETER: xx An invalid parameter (xx) has been given on the command line. INVALID SPEED: xxxxx An invalid speed (baud rate) has been specified. INVALID HANDSHAKING An invalid handshaking option has been specified. INVALID PORT: x An invalid COM port has been specified. This will occur if Puma cannot identify an active UART in the specified port. SEND/RECEIVE NOT SPECIFIED The "s" or "r" parameter was not given on the command line. ERROR READING LIST FILE The Puma sender could not read the specified list file (@listfile). Page 19 The Puma Protocol(TM) v1.00 User's Manual FILE NOT FOUND: filename.ext Puma could not locate the file filename.ext as specified in a list file, or on the command line. NO FILES SPECIFIED The Puma sender found no file specifications on the command line or in a list file. Page 20 The Puma Protocol(TM) v1.00 User's Manual 5 - T h e S e t u p P r o g r a m __________________________________________________________________ Accompanying the Puma Protocol program is a setup program called PUMASET.EXE, which allows the user to customize the PUMA.EXE file. The setup program accomplishes this by reading the PUMA.EXE file, which must reside in the default directory, and updating it with the custom setup information. Using the PUMASET program is easy. First, log to the directory where the PUMA.EXE file resides. This can be done in DOS by using the "chdir" or "cd" command. Next, execute the PUMASET.EXE program. This program can reside anywhere on your hard disk, or on a floppy disk. The setup program will first attempt to read the PUMA.EXE file. If it is not present in the current directory, or is somehow corrupted, you will be alerted. When the PUMA.EXE file has been found and read successfully, you will be presented with the setup program's main menu. MAIN MENU The main menu contains the following information: -> Change default options Adjust screen colors Install registration information Quit and save settings From here, you have four options from which to choose. You may select an option by moving the arrow that is shown on the screen to point at the option you wish to select. The up and down arrow key move the arrow. Press Enter to choose the selected item. From the main menu, you may also press the ESC key. The results of this action are the same as selecting the "Quit and save settings" option. CHANGE DEFAULT OPTIONS After selecting this item, you will be presented with a screen showing a number of options and their current defaults, as they are currently set in the PUMA.EXE file. An explanation of each of these options is detailed in Chapter 3, so we won't repeat ourselves in this section. Page 21 The Puma Protocol(TM) v1.00 User's Manual A few things to note about setting options: The UART baud rate - When choosing a UART baud rate, the setting "Current" will cause Puma to use the baud rate at which the UART is operating when the program is executed. The Effective baud rate - The setting "UART" will cause Puma to match the effective baud rate to the UART baud rate when Puma is executed. IRQs and Base addresses - The IRQ settings adjust the hardware interrupt for each COM port. The base address settings adjust the base I/O address where the UART is mapped for each COM port. Base addresses must be entered in hex format. These settings allow customization of non-standard COM ports. See your internal modem or serial port manual for more information on IRQs and Base address settings. The CDS and DSZ log files - These settings allow default log files to be specified. All default settings except for COM port base addresses and IRQs can be overrided by using command line parameters when executing Puma. ADJUST SCREEN COLORS Selecting this item causes a portion of the Puma Status screen to be shown, along with a menu of items that can be colorized. Using the up and down arrow keys, you can position the arrow to point to an item to be adjusted. The following keys affect the "selected" item: Enter - changes the foreground color Space - changes the background color ESC - return to main menu The following two keys affect the entire display: C - select default color scheme M - select monochrome scheme INSTALL REGISTRATION INFORMATION This item allows registered Puma users to install their User ID and serial number. For information on registering, please read the file, LICENSE.TXT. Page 22 The Puma Protocol(TM) v1.00 User's Manual Registered Puma users: When you receive your User ID and serial number in the mail, you can use the "Install registration information" option to install the information into PUMA.EXE. When typing the UserID, you may use mixed upper and lower case letters, all CAPS, or all lower case, whichever you desire. Enter the serial number EXACTLY as it is shown on your registration certificate. Puma will not run with improper User ID or serial number information. If you receive the message, "Invalid registration information" when running Puma, double check the ID and serial number on your certificate with the information entered into PUMASET. Registered Lynx Users: You may use the LYNXPUMA.EXE program to extract the registration information from LYNX.EXE for use with The Puma Protocol. You must first place your REGISTERED LYNX.EXE file into the current directory, and then execute the LYNXPUMA.EXE program. Follow screen instructions for more details. QUIT AND SAVE SETTINGS This option causes PUMASET to prompt you for a response: Save new settings in PUMA.EXE ? Responding with "N" will cause PUMASET to end without updating PUMA.EXE. Responding with "Y" will cause PUMASET to end after writing the new setup information into the PUMA.EXE file. * * * When running Puma after using PUMASET, note that the "Stats" window will reflect the default settings that you have specified. These defaults can be overrided by command line parameters. Page 23 The Puma Protocol(TM) v1.00 User's Manual 6 - A c k n o w l e d g e m e n t s __________________________________________________________________ This chapter is dedicated to the people who made the Puma project possible, including all the users who registered as Lynx Protocol users, all those who helped test Lynx and Puma, and those who contributed in other ways. . . INSIDE A large percentage of the development time on Puma was spent coding and tuning the UART interface routines using Turbo Assembler 1.0. Repeated tests have revealed that Puma operates quite reliably on a 115200 baud direct link between an 8 Mhz 80286 and a 12 Mhz 80286, even with a 16450 UART. Hats off to Borland International for a fine assembler! The remainder of the project was coded in Turbo Pascal 5.5, Borland's award-worthy compiler and development system. The speed of the display in Puma is attributed to the QWIK toolbox from Eagle Performance Software - QWIK is an irreplaceable kit full of goodies that makes programming without the CRT unit a genuine pleasure. Good work, Eagle! TheDraw from TheSoft Programming Services was used to develop everything visual in the Puma software package. TheDraw proved to be an invaluable tool for designing the user displays. Kudos to Mr. Ian Davis for his quality screen design software! OUTSIDE Puma has made it to the Shareware marketplace only after very extensive testing by the author, and by these fine people, who kindly volunteered their testing services: Nick Anis Kevin Bass Mike Callahan (AKA Dr. File Finder!) Chuck Dennis Charles Edstrom Ken Flower Shawn Johnson Scott Kuntzelman Al Maynard Lee Pollard Bob Rapp John Schuit Ken Standard Thanks, folks! Page 24 The Puma Protocol(TM) v1.00 User's Manual TRADEMARKS AND PRODUCTS The Courier HST and HST/Dual Standard are products of USRobotics DESQview is a product of Quarterdeck Office Systems DSZ is a product of Omen Technology, Inc. IBM 3270 PC and Topview are trademarks of International Business Machines MS-DOS and Microsoft Windows are registered trademarks of Microsoft Corporation PC Access is a trademark of PCA Systems PKZIP is a registered trademark of PKWARE, Inc. QWIK is a product of Eagle Performance Software SuperK is a product of Crater Rim Software Taskview is a product of Sunny Hill Software TheDraw is a trademark of TheSoft Programming Services The Puma Protocol is a trademark of Matthew Thomas Turbo Assembler and Turbo Pascal are registered trademarks of Borland International, Inc. Page 25 The Puma Protocol(TM) v1.00 User's Manual Appendix A - L o g F i l e F o r m a t s __________________________________________________________________ ENHANCED DSZ LOG FORMAT The Enhanced DSZ logging that Puma uses is provided for some compatibility with programs that recognize this type of logging. The log file consists of a single line of text for each file transferred. Following is a sample entry: S 217837 57600 bps 5050 cps 0 errors 0 1024 PUMA100.ZIP Puma The format of this each field in this entry is as follows, beginning with the leftmost field: - 'S' for send, 'R' for receive, 'E' for aborted transfer, or 'L' for lost carrier. - The length of the file, in bytes. - The effective baud rate. Puma follows the DSZ format of using '65535' to represent an actual baud rate of 115200. - The average transfer rate, in characters per second. - The total number of errors which occurred during transmission. - The number of flow control restrictions, as specified in the DSZ documentation. Puma does not record this value, so this field will always contain a zero. - The length of the last block transferred in the file. - The name of the file which was transferred. -*The name of the protocol used. -*The last field is either empty, or contains '(resumed)' to signify that the file was resumed. * These fields are not part of the original DSZ specification. CDS LOG FORMAT CDS logging is a standard of recording online activities of all types. It was developed in an attempt to standardize the interface between various communication utilities, such as terminal emulators, BBS software, external protocols (such as Puma), and phone bill analyzers. Page 26 The Puma Protocol(TM) v1.00 User's Manual By supporting CDS logging, Puma's activities can be tracked by any utility that will read a CDS file. Following is an example of a CDS log entry made by Puma: 90-01-04 00:46:11 020 Puma COM port 1 Comm parameters 2400 8 N 1 Sent file AUTOEXEC.BAT File size 142 Protocol Puma Ended 90-01-04 00:46:11 (call ended abruptly) Transfer Errors 1 Efficiency 0.0 % Average CPS 0 The first line is the record header, which gives the date and time the transfer began, the record number (020), which identifies the record as a file transfer entry, and 'Puma', the name of the program that created the entry. Following the header are single-line entries describing the transfer: COM port N The communications port used for the transfer. N will have a value from 1 to 4. Comm parameters 2400 8 N 1 Designates the effective baud rate, data bits, parity check, and stop bits during a transfer. Each parameter is separated by a space. Puma always uses '8 N 1' for data type. Sent file FILENAME Rcvd file FILENAME The name of the transferred file. File size NNN The size of the transferred file. NNN is the size in bytes (not kilobytes). Protocol Puma The file transfer protocol used. Page 27 The Puma Protocol(TM) v1.00 User's Manual Ended YY-MM-DD HH:MM:SS Ended YY-MM-DD HH:MM:SS (aborted by sender) Ended YY-MM-DD HH:MM:SS (aborted by receiver) Ended YY-MM-DD HH:MM:SS (call ended abruptly) Tells when the transfer terminated, and shows if the sender or receiver aborted the transfer, or if the carrier signal was lost (call ended abruptly). Transfer Errors NNN Provides the total number of errors encountered during the transfer. If the entry is missing, no errors occurred during the transfer. Efficiency NNN % Provides the efficiency of the file transfer. "NNN" is the efficiency as a percentage ("96.2 %" for example). Average CPS NNNN Provides the average characters transmitted per second for the file. "NNNN" is the CPS average as a whole number, "239" for example. Page 28 The Puma Protocol(TM) v1.00 User's Manual Appendix B - B e n c h m a r k s __________________________________________________________________ Following are benchmark results comparing Puma to some of the other protocols in use today. Please note that these results were obtained under a direct serial cable link, where line noise was not a factor. The performance of these protocols may vary widely when tested over various modem connections, baud rates, and CPU speeds. File transferred: A file created with PKZIP, all contents imploded, 217837 bytes in length All readings are in characters per second as reported by the receiver protocol. RLE Compression was disabled in Zmodem and Puma. Jmodem and Lynx do not offer provision to disable their RLE compression. The following programs were used for benchmark testing: Puma 1.00 (Puma) Lynx 3.02 (Lynx) DSZ 12-14-89 (Zmodem, True Ymodem, Xmodem) SuperK R4.47 (Jmodem, Super8K) -------- Test #1 -------- Sender: Receiver: 8 MHz Tandy 1000TX 12.5 MHz Western Digital WDM2 Internal 16450 UART Internal 16450 UART Protocol 9600bps 19200bps 57600bps 115200bps -------- ------- -------- -------- --------- Puma 935 1858 5050 7851 Lynx 931 N/A 1034 N/A Zmodem 927 1846 3514 3961 Ymodem 896 1676 3458 4538 Xmodem 734 1217 2075 2075 Jmodem 923 1771 N/A N/A Super8K 963* 1898* 4130* 4054* Super8K 947 1862 4034 4111 <-Timed by hand Page 29 The Puma Protocol(TM) v1.00 User's Manual ------- Test #2 ------- Receiver: Sender: 8 MHz Tandy 1000TX 12.5 MHz Western Digital WDM2 Internal 16450 UART Internal 16450 UART Protocol 9600bps 19200bps 57600bps 115200bps -------- ------- -------- -------- --------- Puma 938 1867 3661 5102 Lynx N/A N/A N/A N/A Zmodem 927 1846 3068 3756 Ymodem 919 1786 3157 3961 Xmodem 801 1353 1729 1928 Jmodem N/A N/A N/A N/A Super8K 967* 1914* 2440 2135 Super8K 947 1894 2421 2135 <-Timed by hand Test results marked "N/A" were not available due to one of the following situations: - The transfer failed - The baud rate for the test was not supported * When timing Super8K transfers with a stopwatch, actual transfer times did not match reported cps rates. For reported cps rates to be considered valid, they must be derived from the following formula: cps = bytes / seconds In this formula, "bytes" must be equal to the actual number of bytes in the transferred file, and "seconds" must be equal to the total number of seconds which elapsed from the time that the first byte of file data was received to the time that the last byte of file data was received and accepted by the receiver protocol. If these criteria are met, "cps" will return the actual throughput of the file transfer. The transfers in question were repeated, and timed by hand with a stopwatch. The resulting cps rates are provided in the above chart. Page 30 The Puma Protocol(TM) v1.00 User's Manual Appendix C - P u m a A u t o - S t a r t R e c e i v e __________________________________________________________________ Puma has a feature that allows the sending protocol to alert the receiver to start download synchronization. This can decrease the number of required keystrokes to start a download. At this time, none of the terminal programs that were evaluated by the author directly support any type of auto-receive mode for external protocols, other than Zmodem. It may be possible for some terminals to support Puma auto- receive by using their built-in script language to wait for the Puma auto-packet, and then beginning the external Puma receiver protocol. Following is the format of the Puma auto-packet, which the Puma sender transmits at one-second intervals at the beginning of a batch transfer: Turbo Pascal format: #24#8#24#8#24'Puma'#24#8#24#8#24 Hex format: 24 08 24 08 24 50 75 6D 61 24 08 24 08 24 When this string of characters is received during a terminal session, the Puma receive protocol should be initiated. Perhaps we will see this type of feature supported in future releases of the popular terminal programs. But for now, it has to be done using scripts. Page 31 The Puma Protocol(TM) v1.00 User's Manual Appendix D - S u g g e s t e d R e a d i n g __________________________________________________________________ For in-depth information on all aspects of computer telecommunications, the author recommends the following book: "Dvorak's Guide to PC Telecommunications" By John C. Dvorak and Nick Anis Published by Osborne/McGraw-Hill, 1989 This book has over 1000 pages, and contains two 5.25" floppy disks. Included on the first disk is "Telix SE", a complete and powerful communication package, along with a Modem Tutor Program. The second disk is packed (zipped, actually) with a number of very useful shareware programs. Suggested retail price is $49.95. Check your local computer or book store for this excellent source of information! Page 32