The MPt Protocol v1.10 User's Manual Copyright (c)1990 by Matthew Thomas All Rights Reserved The MPt Protocol v1.10 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 MPt Program. . . . . . . . . . . . . . . . . . . . . . . 4 Running MPt . . . . . . . . . . . . . . . . . . . . . . . . 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 . . . . . . . . . . . . . . 6 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 MPt 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 MPt Protocol v1.10 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. MPt Auto-Start Receive . . . . . . . . . . . . . . . . . . . 29 C. Suggested Reading. . . . . . . . . . . . . . . . . . . . . . 30 D. Software Revisions . . . . . . . . . . . . . . . . . . . . . 31 The MPt Protocol v1.10 User's Manual 1 - I n t r o d u c t i o n __________________________________________________________________ FEATURES The MPt Protocol 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 MPt will do the job, and will do it quickly and accurately. MPt 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 the protocol 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 MPt 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 this product beyond this period, you are required to register. Information on becoming a registered user 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 MPt Protocol v1.10 User's Manual other incidental or consequential damages arising out of the use or inability to use the MPt Protocol even if the author, Matthew Thomas, or an authorized distributor of the product 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 Product support is available through three channels. To contact the author with questions, suggestions, problems, or other comments, 1) Call the Programmer's Guild BBS at (414) 639-8456 and send E-mail to Matt Thomas. or 2) Call the Exec-PC BBS at (414) 789-4210, and send E-Mail to Matt Thomas. or 3) Drop a note via US Mail to: MPt Software Company Matthew Thomas PO Box 4694 Racine, WI 53404 The author offers limited support to unregistered users of the MPt Protocol, in order to help them get the program installed for evaluation. If you have a problem installing or using the software, 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 either of the channels mentioned above. We will make an attempt to answer all mail received, but please be aware that registered users have first priority for support. Page 2 The MPt Protocol v1.10 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 MPt Protocol, this brief chapter has been included to help you along. For a complete explanation of how to use the protocol and the setup program, continue reading beyond this chapter. THE HELP SCREEN When you run MPt the first time, try executing MPT.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 the software running if you choose not to read the rest of the documentation right away. THE SETUP PROGRAM Also included with MPt is a file called MPTSET.EXE. This program allows you to change the software'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 MPT.EXE file (the MPt Protocol program). Type MPT, and press enter. If the setup program cannot read the MPT.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 the software to sense and use the current baud rate of the UART when MPT.EXE is executed. þ When choosing an "effective" baud rate, the value of "UART" will cause MPt 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. Both of these keys destroy any changes made to the color set before saving! þ In the "Change default options" screen, the options that you choose will be written to the MPT.EXE file as defaults. When running MPt, you may override any of these defaults by using command line parameters, detailed in Chapter 3. Page 3 The MPt Protocol v1.10 User's Manual 3 - T h e M P t P r o g r a m __________________________________________________________________ This chapter will familiarize you with the MPt Protocol, and its features and command line parameters. RUNNING MPT To load and run the MPt 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 MPt directly without using the DOS command.com program. This command line has a specific syntax. Here are the three general formats for the MPt command line: MPT [options] s filespec [filespec] [filespec] [...] MPT [options] s @listfile MPT [options] r [path] Anything appearing in square brackets is optional, and may not need to be specified for proper operation of MPt. Note that MPt completely ignores the "case" of the command line, which means that upper and lowercase characters may be mixed in any combination. The word "MPT" at the beginning of each command line is required in all cases. This is what tells MS-DOS to load the MPT.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 MPt to send files to another computer, while "r" tells MPt 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 MPt Protocol offers a number of features and settings. This section will explain each command line option, and how each affects MPt operation. Note that a plus (+) in the syntax enables an option, while a minus (-) disables it. Page 4 The MPt Protocol v1.10 User's Manual Following is a description of each option: ------------------------------------ A+ or A- (delete aborted downloads) ------------------------------------ If enabled (A+), this setting will cause MPt to delete the transferred portion of any files that were not fully received. If disabled (A-), this setting will cause the protocol 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 send mode. -------------------------------- B+ or B- (beep upon completion) -------------------------------- Enabling this setting causes MPt 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 the program to remain silent at all times. ------------------------- CDSx (log to a CDS file) ------------------------- This option allows the user to specify a log file where MPt 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\mptlog": MPT CDSc:\logs\mptlog r Whereas, the following receiver command line will not log the files in CDS format: MPT CDS r For information on the CDS log format, see Appendix A, "Log File Formats". Page 5 The MPt Protocol v1.10 User's Manual ----------------------------------- D+ or D- (stamp with current date) ----------------------------------- This setting, when enabled, will cause MPt to stamp each received file with the current time and date of the transfer. When this setting is disabled, MPt 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 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 MPt 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, MPt allows each to be specified separately. MPt 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 or equivalent UART installed. When enabled, this setting allows MPt 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. MPt will always return the UART to the state it was in when MPt began. Page 6 The MPt Protocol v1.10 User's Manual 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 MPt transfers. -------------------- HF (handshake fast) -------------------- This setting enables fast hardware handshaking during 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 MPt 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 the protocol 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. MPt 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 Page 7 The MPt Protocol v1.10 User's Manual likely solve the problem. If overrun errors are continually occurring, you may need to use the HS parameter (detailed below). 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 MPt, 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. MPt 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 MPt 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 to the file "c:\logs\log": MPT Lc:\logs\mptlog r Whereas, the following receiver command will not write a log file: MPT L r For information on the DSZ log format, see Appendix A. Page 8 The MPt Protocol v1.10 User's Manual -------------------------------------- N+ or N- (monitor the carrier signal) -------------------------------------- This setting, when enabled, will cause MPt to end if the DCD signal (carrier) is lost during a transfer. When this setting is disabled, MPt will ignore the state of the DCD signal. Note: BBS SysOps should enable this setting, so if a user drops carrier during a transfer, MPt will end, and control will be immediately restored to the BBS software. -------------------------------------------- O+ or O- (allow overwriting received files) -------------------------------------------- This setting, when enabled, allows MPt 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, MPt will delete the old file and write the new one under the same name. If this setting is disabled, MPt will not allow a received file to overwrite another file. --------------------- Px (COM port number) --------------------- This setting tells MPt 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, MPt will not attempt to use it. For information on COM port configurations, see Chapter 5, "The MPt Setup Program". ----------------------------------- R+ or R- (allow resumed transfers) ----------------------------------- This setting, when enabled, allows the MPt 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, MPt 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, MPt will not attempt to resume any transfers. In this case, if a header for an existing file is received, MPt will check the "allow overwriting received files" setting before writing the new file to disk. Page 9 The MPt Protocol v1.10 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 MPt to auto-detect and use the current UART baud rate when the MPt 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 MPt 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, MPt 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, MPt will end with the RTS and DTR signals set high. -------------------------------------------- W+ or W- (wait for keystroke when finished) -------------------------------------------- This setting, when enabled, causes MPt to wait for a keystroke at the end of a transfer before returning to DOS. If this setting is disabled, MPt will return control to DOS immediately after the session ends. ---------------------------------- X+ or X- (enable RLE compression) ---------------------------------- This setting, when enabled, allows MPt to use RLE compression where possible when transferring data. If either end of the MPt connection (sender or receiver) disables this parameter, RLE compression will not be used. Page 10 The MPt Protocol v1.10 User's Manual * * * * * * * * * * * * * RLE Compression * * * * * * * * * * * * MPt uses RLE compression techniques in an attempt to shorten blocks of data before they are transferred. MPt will never transmit a compressed block of data unless the compressed block is shorter than the original block. The compression routines in MPt 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 MPt 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 MPt Protocol is capable of sending up to 99 individual files in a single batch. Each file which is transmitted by MPt 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: MPT [options] s filespec [filespec] [filespec] [...] MPT [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. *.*). MPt will parse each wildcard specification into individual file names. If more than 99 files are specified, MPt will send the first 99 files found. In the second syntax, a single absolute file specification (no wildcards) is specified on the MPt command line, immediately preceded by the @ symbol. MPt 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, MPT 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 MPt Protocol v1.10 User's Manual RECEIVER FILE SPECIFICATIONS When receiving files with MPt, the syntax for the command line is as follows: MPT [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 MPt 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 MPt 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: MPT r c:\download\myfile.ext MPT 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. MPt 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 MPt 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 MPt 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 MPt: 0 Transfer was completed successfully 1 Transfer began, but ended without completing 2 Session ended before transfer began 3 MPt detected invalid registration information 4 MPt was invoked without any command line parameters Page 12 The MPt Protocol v1.10 User's Manual EXAMPLES Following are some examples of command line syntaxes: MPT s c:\file1.txt (send a file using default options) MPT hf s p1.exe p2.exe (send two files, use fast handshaking) MPT s d:\*.* (send all files in root dir of d:) MPT x+ s *.txt (send text files, allow compression) MPT x- s *.zip (send ZIP files, don't try to compress) MPT n- s @files.lst (send files in a list, ignore carrier) MPT s9600 e2400 s *.* (send at 9600 bps, effective 2400 bps) MPT p3 cdsmpt.log r (receive files from COM3, log with CDS) MPT r c:\files\ (receive into "c:\files\" directory) MPT r \ (receive into root of current drive) MPT a+ r (receive files, delete aborted downloads) MPT ldsz.log r (receive with DSZ logging) MPT r+ o+ r (receive, allow resume and overwriting) Page 13 The MPt Protocol v1.10 User's Manual 4 - T h e M P t D i s p l a y __________________________________________________________________ This chapter will familiarize you with the MPt display, and the meaning of each item shown during a MPt session. SCREEN ACCESS When MPt is executed, the first thing it does is to put up a full screen display. If MPt is run under normal DOS conditions, all accesses to the screen will use direct memory access. In other words, MPt 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, MPt offers an alternative. When MPt 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, MPt 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 MPt display can be easily customized for color or monochrome displays by using the MPt Setup program. See Chapter 5, "The Setup Program", for more details. THE HELP SCREEN The help screen will appear when MPt 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 MPt Program". * * * When MPt is executed with command line parameters, a status display will appear, filling the screen with information concerning the status of each transfer. Page 14 The MPt Protocol v1.10 User's Manual 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 MPt 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 MPt 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 MPt uses on the serial port. Page 15 The MPt Protocol v1.10 User's Manual At the top of the UART window is shown the type of UART that is installed in the COM port that MPt is using. The recognized UARTs are: 8250B (INS8250 or INS8250-B) 16450 (NS16450, NS16C450, NS8250A, or INS82C50A) 16550 (NS16550) 16550A (NS16550A, NS16550AF) MPt will optionally use FIFO buffers, if the "enable 16550A FIFO buffers" option is enabled, and the UART type is 16550A. See Chapter 3, "The MPt 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 MPt 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 MPt receiver actually resumes a file, this indicator will blink for the remainder of the transfer of that particular file. Page 16 The MPt Protocol v1.10 User's Manual Virt - this indicator will be lit if MPt 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 MPt display indicates miscellaneous items of interest. We'll cover them from left to right, as displayed on the MPt screen: The far left section will contain "S" or "R", to indicate send or receive mode. Next is the COM port which MPt 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 MPt 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 MPt Protocol. This section gives the most important messages and their meanings: SYNCHRONIZING MPt is attempting to communicate control information with the connecting protocol. This occurs at the beginning of each file being transferred. SYNCHRONIZATION FAILED MPt was unable to synchronize with the connecting protocol. SENDING/RECEIVING FILE MPt is synchronized and has begun the file transfer. Page 17 The MPt Protocol v1.10 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 MPt had problems writing to a log file. ERROR AT BYTE xxxx: errortype This message indicates that MPt 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 - MPt detected an error when comparing CRCs. This is usually causes by line noise on a bad connection. Long - The MPt 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 MPt receiver got a partial block, which was not complete. Duplicate - The MPt receiver received a block of data that had already been received successfully. Waiting - The MPt 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 MPt 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 MPt 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 MPt Protocol v1.10 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 MPT.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 MPt 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 MPt sender could not read the specified list file (@listfile). Page 19 The MPt Protocol v1.10 User's Manual FILE NOT FOUND: filename.ext MPt could not locate the file filename.ext as specified in a list file, or on the command line. NO FILES SPECIFIED The MPt sender found no file specifications on the command line or in a list file. Page 20 The MPt Protocol v1.10 User's Manual 5 - T h e S e t u p P r o g r a m __________________________________________________________________ Accompanying the MPt Protocol program is a setup program called MPTSET.EXE, which allows the user to customize MPt. The setup program accomplishes this by reading the MPT.EXE file, which must reside in the default directory, and updating it with the custom setup information. Using the MPTSET program is easy. First, log to the directory where the MPT.EXE file resides. This can be done in DOS by using the "chdir" or "cd" command. Next, execute the MPTSET.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 MPT.EXE file. If it is not present in the current directory, or is somehow corrupted, you will be alerted. When the MPT.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 keys 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 MPT.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 MPt Protocol v1.10 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 MPt 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 MPt to match the effective baud rate to the UART baud rate when MPt 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 MPt. ADJUST SCREEN COLORS Selecting this item causes a portion of the MPt 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 MPt users to install their User ID and serial number. For information on registering, please read the file, LICENSE.TXT. A note to registered MPt (or Puma) users: When you receive your User ID and serial number in the mail, you can use the "Install registration information" option to install Page 22 The MPt Protocol v1.10 User's Manual the information into MPT.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. MPt will not run with improper User ID or serial number information. If you receive the message, "Invalid registration information" when running MPt, double check the ID and serial number on your certificate with the information entered into MPTSET.EXE. Registered Lynx Users: You may use the LYNX_MPT.EXE program to extract the registration information from LYNX.EXE for use with The MPt Protocol. You must first place your REGISTERED LYNX.EXE file into the current directory, and then execute the LYNX_MPT.EXE program. Follow screen instructions for more details. QUIT AND SAVE SETTINGS This option causes MPTSET to prompt you for a response: Save new settings in MPT.EXE ? Responding with "N" will cause MPTSET to end without updating MPT.EXE. Responding with "Y" will cause MPTSET to end after writing the new setup information into the MPT.EXE file. * * * When running MPt after using MPTSET, 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 MPt Protocol v1.10 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 MPt project possible, including all the users who registered as Lynx Protocol users, all those who helped test Lynx and MPt, and those who contributed in other ways. . . INSIDE A large percentage of the development time on MPt was spent coding and tuning the UART interface routines using Turbo Assembler 1.0. Repeated tests have revealed that MPt 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 MPt 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 MPt 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! The MPt Protocol is distributed in ZIPPED format, a technology made possible by the wonderful PKZIP shareware product from PKWARE, Inc. Thanks to Mr. Phil Katz for a top-notch shareware product! OUTSIDE MPt 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 Chuck Dennis Charles Edstrom Ken Flower Shawn Johnson Scott Kuntzelman Al Maynard Lee Pollard Bob Rapp John Schuit Thanks, folks! Page 24 The MPt Protocol v1.10 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 PKZIP is a registered trademark of PKWARE, Inc. QWIK is a product of Eagle Performance Software Taskview is a product of Sunny Hill Software TheDraw is a trademark of TheSoft Programming Services The MPt Protocol is a trademark of Matthew Thomas Turbo Assembler and Turbo Pascal are registered trademarks of Borland International, Inc. Page 25 The MPt Protocol v1.10 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 MPt 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 MPT110.ZIP MPt The format of 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. MPt 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. MPt 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 MPt), and phone bill analyzers. Page 26 The MPt Protocol v1.10 User's Manual By supporting CDS logging, MPt'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 MPt: 90-01-04 00:46:11 020 MPt COM port 1 Comm parameters 2400 8 N 1 Sent file AUTOEXEC.BAT File size 142 Protocol MPt 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 'MPt', 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. MPt 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 MPt The file transfer protocol used. Page 27 The MPt Protocol v1.10 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 MPt Protocol v1.10 User's Manual Appendix B - M P t A u t o - S t a r t R e c e i v e __________________________________________________________________ MPt 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 MPt auto-receive by using their built-in script language to wait for the MPt auto- packet, and then beginning the external MPt receiver protocol. Following is the format of the MPt auto-packet, which the MPt sender transmits at one-second intervals at the beginning of a batch transfer: Turbo Pascal format: #24#8#24#8#24'MPt '#24#8#24#8#24 When this string of characters is received during a terminal session, the MPt 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 29 The MPt Protocol v1.10 User's Manual Appendix C - 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 30 The MPt Protocol v1.10 User's Manual Appendix D - S o f t w a r e R e v i s i o n s __________________________________________________________________ The following revisions have been made to the MPt Protocol Software package: v1.00 (01-15-90) This was the initial release of the protocol. The name of the software was "Puma" in its first release. v1.10 (08-07-90) This release was made only to change the name of the protocol to "The MPt Protocol", due to a trademark problem with the previous name. Page 31