L Y N X A windowed batch data transmission protocol Release 3.02 - September 16, 1989 Copyright (C) 1989 by Matthew Thomas All Rights Reserved Lynx 3.02 is a S H A R E W A R E product I n t r o d u c t i o n _____________________________________________________________ Thank you for your interest in the Lynx protocol! You have discovered a powerful communication tool that has lots of features in a small package. Lynx is a windowed batch data transmission protocol which utilizes proven techniques of efficiency, reliability and flexibility: * RLE data compression on a block by block basis * 32-bit CRC on each block for reliable error detection * Fast recovery from data transmission errors * Continuous data flow from the sender * Dynamic block scaling for noisy connections * Resume mode for recovery of crashed transmissions * Passing full file name, size, date and time * Up to 99 files may be transferred in a single batch * Retaining exact file size * Stamp received files with current or original time/date * CTS/RTS handshaking In order for the Lynx protocol to be useful, the protocol has been implemented in an MS-DOS executable file, called LYNX.EXE, which is included in this package. With this program, you can perform data transfers over a dial-up modem line, or over direct RS-232 links. R e g i s t r a t i o n _____________________________________________________________ In order for Lynx to be distributed to a wide range of potential users, the protocol engine is being marketed as a SHAREWARE product. This SHAREWARE Lynx package may be freely copied and distributed to anyone, by anyone, in its original, unmodified form (LYNX302.ZIP). When a potential user unZIPs a copy of this Lynx package, they are free to use it for a trial period of three weeks, in which duration they must decide whether Lynx is a product they can benefit from, and will use beyond the three week trial period. If the individual continues to use the Lynx program beyond the three week trial period, then the product must be registered. Registration of your copy of the Lynx software entitles you to a copy of Lynx which is serialized in your name. Once you have registered your copy of Lynx, Lynx Version 3.02 Page 1 you are entitled to use any future revisions of the Lynx engine, with no further licensing fee. To register your copy of the Lynx engine, send a check or money order (U.S. funds, please!) in the amount of fifteen dollars ($15) payable to Matthew Thomas to the following address: Lynx Development c/o Matthew Thomas 4210 North Main Street #226 Racine, WI 53402 When your order is received, we will send you the newest release of the Lynx engine, serialized in your name. If, in future, you obtain a shareware copy of Lynx that is newer than the one you receive when you register, you may use the LYNXNEW.EXE file (included on your registration disk) to upgrade the shareware version to a registered version. Note! Lynx 3.00 is the first version which requires registration. You may continue to use any version of Lynx PRIOR to 3.00 without registering that copy. L e g a l i t i e s _____________________________________________________________ The Lynx engine program has been tested under many conditions--on various CPU types, clockspeeds, modems, and dial-up lines. However, as with any software, it is impossible to guarantee that all bugs or incompatibilities have been discovered and corrected. Therefore, Lynx Development and Matthew Thomas can not be held responsible for any errors, anomalies, bugs, or imcompatibilities which may occur under any conditions when using the Lynx engine. There is no warrantee, expressed or implied, as to the suitability of the Lynx engine or protocol for any express purpose. By registering Lynx, you are purchasing a single user license to use the Lynx engine program. It is expressly forbidden for any registered copies of the Lynx engine to be distributed to other potential users. The SHAREWARE (UNREGISTERED) version of Lynx may be distributed, in unmodified form, to anyone who wishes to evaluate it. Lynx Version 3.02 Page 2 T h e P r o t o c o l _____________________________________________________________ The Lynx protocol is based on the assumption that a connection between two sites is capable of full-duplex transmission. Lynx will send a stream of data while simultaneously polling the receive-buffer for any interruptions from the other end. On half duplex links, this will not work. But almost all modems in use today are capable of full-duplex operation, so this specification is typically not a problem. The reason that Lynx makes use of full-duplex operations is to insure optimum transfer speed. When transmitting information, Lynx spends very little time waiting for the other end to respond. On certain occasions--after a file header is transmitted or after recovering from a line error-- Lynx will wait for the other end to resynchronize. Lynx can transfer up to 99 files in a single batch. Information which is passed from sender to receiver concerning each file includes: File name (8 character body, 3 character extension) Original time/date stamp (optional) File length (exact length of files is preserved by Lynx) Lynx version number (practically useless) The Lynx engine supports COM1 thru COM4, with adjustable configuration for COM3 and COM4. Baud rates are adjustable up to 57600 baud. Lynx data transmissions are protected with CRC-32 error detection, and are recoverable either automatically by the protocol (Lynx will attempt to recover from up to twenty contiguous errors) or manually, by reconnecting--hopefully with a cleaner connection--and using the resume option of Lynx. The resume option alerts the Lynx receive protocol to automatically test for the presence of a partially downloaded file before beginning the transfer, and to initiate the download at the point in the file where the last one ended, instead of resending the entire file. During the course of the transmission, Lynx will dynamically adjust the block size from 2 packets up to 16 packets to optimize for speed on clean connections. Incidentally, a packet contains 64 bytes of data. The benefit of increasing the block size on error-free connections is in the fact that the overhead of block numbers, control sequences, and CRC-32 bytes is decreased for the entire file, actually decreasing the total number of bytes that must be transferred. Lynx Version 3.02 Page 3 Lynx will also dynamically shrink block sizes if continuous errors are detected in the connection. The benefit of this technique is that on an error-prone connection, short blocks take less time to retransmit (which is a natural occurrence during error recovery) Lynx tests each block for compressibility before transmitting it. An RLE (Run-Length-Encoding) compression technique is used for this operation. Generally, a block containing text information will be compressible. Archived, ZIPPED, or other compressed files will likely not be further condensed by this technique. Note that Lynx will always optimize transmission of each block--if RLE decreases the block length, it will be used; otherwise, the uncompressed packet will be sent. In some implementations of RLE encoding, the compression technique may actually increase the length of the data being encoded. This is not the case with Lynx. Lynx supports CTS/RTS hardware handshaking. This type of handshaking is generally required when using Lynx at high speeds (9600 baud or faster). Modems such as the ATI 2400etc, the USR HST 14400, and other MNP or buffered modems require this type of handshaking. The Lynx engine program currently requires 48 kilobytes of free RAM to operate. Lynx 3.02 does not allocate any memory dynamically, so memory requirements no longer change with additional command line parameters. When opening files, the Lynx engine uses the DOS file mode identifier to protect the files from external access. While a file is being received (written to the disk), Lynx opens it as write-only, locked access (only writable by Lynx, and not readable by anyone). While a file is being transmitted (read from the disk), Lynx opens it as read-only, shared access (readable by anyone, writable by no one). Once the transfer of each file is complete, that file is closed and can be accessed by anyone for any operation. U s i n g L y n x _____________________________________________________________ The MS-DOS(TM) engine for Lynx is a program which can be called either directly from the DOS command line, or via batch files, such as from a communication program or BBS program. A help screen outlining the command line options for Lynx is shown by running the LYNX.EXE program without any command line parameters. The help screen looks something like this: Lynx Version 3.02 Page 4 +-----------------------------------------------------------+ |Parameters: none. | | | |Usage: LYNX S [options] [@file] [[file] [file] [...]] | | LYNX R [options] [path] | | | | [options] : /baud - set the baud rate to 'baud' | | /com - use COM port 'com' (1 - 4) | | /NC - no carrier checking | | /R - enable resume option (receiver only) | | /B - ring bell upon completion | | /W - wait for a keystroke upon completion | | /D - stamp files with current time/date | | /T - drop DTR and RTS upon completion | | /S - use color window screen display | | /H - use CTS/RTS handshaking | | /L -*use long blocks at start of transfer | | /G -*use LYNXLOG instead of DSZLOG | | | | * = option requires registration | | | | [@file] : file containing list of files to send | | [file] : file to transmit (sender only) | | [path] : drive and path location for received files | | | +-----------------------------------------------------------+ Following is a complete explanation of all parameters, and how each is used. In the example command lines shown, the option which is being demonstrated is shown in CAPS. When using Lynx command lines, case is not important. Upper and lower case are treated equally. ------------------------- S or R : These two parameters specify whether Lynx should send or receive files. Note that one of the two must be used, and must appear as the first parameter on the command line. All other parameters may appear in any order. EXAMPLE: To send a file called FOO.BAR, which is in the current directory, use the command: lynx S foo.bar To receive the same file, the "foo.bar" portion of the command line can be removed: lynx r (the transmitter specifies filenames, not the receiver.) Lynx Version 3.02 Page 5 /baud : With this parameter, you may specify a baud rate to use for the Lynx transfer. Legal values are: /300,/1200,/2400,/4800,/9600,/19200,/38400, and /57600 Note: If this parameter is not used, Lynx will run at the current baud rate of the serial port. EXAMPLE: To send all files in the current directory, using a baud rate of 9600 bps, use the following command: lynx s /9600 *.* ------------------------- /com : This parameter allows you to specify which COM port to use. Values from 1 to 4 are legal. If this parameter is not specified in the command line, the default COM port will be used. Note that the default port is 1, unless the DSZPORT variable is used. For information on this variable, see the section entitled "Variables." EXAMPLE: To receive files over COM2, at the current baud rate, use the command: lynx r /2 ------------------------- /NC : This parameter specifies that Lynx should ignore the DCD (carrier signal) from the serial port. Without this parameter, Lynx will abort the transfer if the carrier signal is lost. EXAMPLE: To receive files over COM1, at 19200 bps, without monitoring the carrier signal, use the following command: lynx r /19200 /1 /NC ------------------------- /R : This parameter enables the Lynx resume option. When this parameter is used, Lynx will automatically check the receive path for the presence of each file for which a file header is received. If the file already exists (in partial form) Lynx will alert the sender to begin the transfer at the end of the partial file. Lynx Version 3.02 Page 6 This sounds more complicated than it really is. The fact is, the /R (resume) option makes it possible to partially download a file, abort the transfer (perhaps in the case of a bad connection), and continue the download later at the same point where it left off. This parameter is only effective in Lynx receive mode. EXAMPLE: To send the files MYFILE and HISFILE, which are in the directory C:\FILES; using COM2, at 1200 baud, while monitoring the carrier signal and allowing Lynx resumes, use the following command: lynx s /1200 /2 /R c:\files\myfile c:\files\hisfile ------------------------ /B : This option causes Lynx to sound a bell upon completion. The bell will sound regardless of whether the transfer was successful or not. EXAMPLE: To receive files into the current directory, and ring the bell when the transfer is done, use the command: lynx r /B ------------------------- /W : This parameter tells Lynx to wait for a keystroke before exiting at the end of a transfer (whether successful or otherwise). This is useful if Lynx is executed from a DesqView(TM) window or some similar environment, and the user wishes to see how Lynx finished before the window closes. EXAMPLE: To send all files in the directory C:\FILES that have the extension EXE, and wait for a keystroke when complete, use the command: lynx s /W c:\files\*.exe Lynx Version 3.02 Page 7 /D : When this parameter is used, each file that is received will be stamped with the current time and date when that file is closed. If /D is not used, Lynx will stamp each file with the actual time and date of the original file, which is passed via the header packet at the start of each file in a batch. The /D parameter is only effective in Lynx receive mode. EXAMPLE: To receive files into the current directory, and stamp each of them with the current time and date, use the command: lynx r /D ------------------------- /T : When this parameter is specified, Lynx will drop the DTR and RTS signals to the modem when the transfer is completed. This will generally cause a modem to go "on-hook". If you wish Lynx to hang up the modem when complete, you can use this parameter. Without the /T parameter, the DTR and RTS signals are returned to their original state upon completion. EXAMPLE: To cause the modem to hang up once all files in the current directory are transmitted, use the command: lynx s /T *.* ------------------------- /H : This option causes Lynx to use CTS/RTS handshaking during the transfer. This is usually required when the baud rate is 9600 bps or faster. Also when using buffered modems, such as the ATI 2400etc, or the USR HST 14400, you will need to use the /H parameter. BBS OPERATORS: If the modem you are using on your BBS supports CTS/RTS handshaking, you will need to use the /H parameter. The handshaking will only come into effect when the modem is running at a speed that requires it CTS/RTS flow control. EXAMPLE: To receive files with CTS/RTS handshaking enabled, use the command: lynx r /H Lynx Version 3.02 Page 8 /S : When this option is used, Lynx will use direct memory screen writes for all screen updates, instead of BIOS screen writes. Generally, direct screen access is faster than BIOS access. This switch also enables a pop up window view instead of the normal "teletype" display that Lynx otherwise uses for feedback. The colors of this pop-up window may be configured using the LynxCo environment variable (explained in the section entitled "Variables.") When using a multi-tasking environment like DesqView(TM), this parameter should NOT be used. This will avoid screen/window conflicts between Lynx and other tasks which are running at the same time. EXAMPLE: To send the file FOO.BAR using the color status window, use the command: lynx s /S foo.bar ------------------------- /L : This parameter forces Lynx to begin transmitting 1024 byte blocks instead of 128 byte blocks. This should only be used if the connection is clean. Dynamic block scaling is still in effect if errors occur. This parameter is effective only in Lynx transmit mode. The /L parameter is available only on registered copies of the Lynx engine. EXAMPLE: To send the file MYFILE.TXT over a clean connection, use the command: lynx s /L myfile.txt ------------------------- /G : This parameter forces Lynx to use the LYNXLOG environment variable instead of the DSZLOG variable for its log filename. This is handy if you wish to keep your Lynx log file separate from your DSZ(TM) log file. The /G option is available to registered users only. ------------------------- @file : This parameter can be used by the sender to specify a file that contains a list of path/file names of files to be sent in a batch. In the list file, each file name must be separated by a carriage return/line feed combination. Blank lines are Lynx Version 3.02 Page 9 ignored. DOS wildcards are supported inside the list of files only; the file name following the @ must be an absolute filename (no wildcards). EXAMPLE: To send all the files listed in the file LISTING.LST, use the command: lynx s @LISTING.LST In this case, the file LISTING.LST must be located in the current directory (because no path is specified), and when typed with the DOS "type" command, may look something like this: *.exe *.com readme.txt This will cause Lynx to transmit all files with the extension EXE, all files with the extension COM, and the file named README.TXT. ------------------------- file : This parameter may consist of a full path and file name of a file to send. DOS wildcards are fully supported. A total of 99 individual files may be send in a single batch. This parameter may be repeated on the command line to send multiple files. EXAMPLE: To send the file MYFILE.DOC (located in the current directory) and the file FOO.BAR (located in the directory C:\FILES), use the command: lynx s MYFILE.DOC C:\FILES\FOO.BAR ------------------------- path : This parameter may specify a DOS drive and path location where Lynx should place all files which are received. There must be a back-slash (\) at the end of the specified path! EXAMPLE: To force Lynx receive files into the C:\TELIX directory, use the command: lynx r C:\TELIX\ If this parameter is not specified in the receiver's command line, all received files will be placed in the current DOS drive and directory. Lynx Version 3.02 Page 10 NOTE: This parameter may also contain a file name. Lynx will ignore the file name if it is specified, because file names are always passed through the communication link. But some programs insist on passing the file name as well as the receive path to external protocols, so this is acceptable to Lynx. When you ARE specifying a file name, there should be NO back-slash at the end. EXAMPLE: To force Lynx to receive a file into the C:\TELIX directory, you may use the command: lynx r C:\TELIX\MYFILE.EXT The MYFILE.EXT portion will be tossed. V a r i a b l e s _____________________________________________________________ There are some DOS environment variables which are recognized by the Lynx engine program. To set these variables, you can use the DOS 'SET' command. You may wish to place the SET commands in your autoexec.bat file, so once they're set, you can forget about them. The first two variables have been named the same as two of the DSZ(TM) variables to maintain some compatibility between the two engines. DSZPORT - This variable, if defined, specifies the default COM port for Lynx to use. It's value may be set to 1, 2, 3, or 4. EXAMPLE: To force the default COM port to be 1, use the DOS command: SET DSZPORT=3 ------------------------- DSZLOG - If this variable contains a legal DOS filespec, Lynx will maintain a DSZ(TM) compatible log file at the specified path and file name. Lynx Version 3.02 Page 11 EXAMPLE: To tell Lynx to maintain a log in the C:\BBS directory, under the filename LYNXLOG.TXT, use the DOS command: SET DSZLOG=C:\BBS\LYNXLOG.TXT The format of the log file is one line for each file transferred, with the following information in each entry line: - The First field is 'x' for Lynx send, or 'X' for Lynx receive. - Next is the length of the file which was transferred. - After that is the baud rate. - Then the average transfer rate, shown in characters per second. - Followed by the total number of errors which occurred during transmission. - The next field is always 0. This was specified in the DSZ(TM) documentation as the number of flow control restrictions which occurred during transmission. Lynx does not record this value. - Next is the length of the last block which was transferred for the file in question. - The last field in the log entry contains the filespec which was transferred. ------------------------- LYNXP3 - This variable defines the port configuration of COM port 3. This is only effective if Lynx is using COM3 during a transfer. This variable specifies the base address (in hex) and the interrupt (irq) that the port will use. EXAMPLE: To tell Lynx to configure COM3 for base port address 2E8 and for interrupt 3 (irq3), use the DOS command: SET LYNXP3=2E8,3 The default configuration for COM3 is base address 3E8 and interrupt 4 (irq4). Lynx Version 3.02 Page 12 LYNXP4 - This variable is exactly the same as LYNXP3, except it affects COM4. The default configuration for COM4 is base address 2E8 and interrupt 3 (irq3). ------------------------- LYNXCO - This variable defines the screen colors when the /S command line option is used. To use this variable, you must pass 6 values, 3 digits each, separated by spaces or commas. The parameters set the following colors (in order of appearance): - Status attribute - Status label attribute - Fatal error message attribute - Window frame attribute - Window header attribute - Window footer attribute To calculate the color attributes, use the following formula: attribute = (background * 16) + foreground The following values can be used for color combinations: Black = 0 Dark Gray = 8 Blue = 1 Light Blue = 9 Green = 2 Light Green = 10 Cyan = 3 Light Cyan = 11 Red = 4 Light Red = 12 Magenta = 5 Light Magenta = 13 Brown = 6 Yellow = 14 Gray = 7 White = 15 The default configuration is equivalent to: LYNXCO=014,015,012,014,011,010 It is the author's opinion that using the public domain program called LCS (Lynx Color Set), by John Schuit, is the easiest and best way to set the LYNXCO environment variable. LCS is menu driven, and allows the user to view the Lynx window as the colors change, giving a better idea of what the end result will look like. Lynx Version 3.02 Page 13 LYNXLOG - This environment variable is only used if the /G parameter is specified on the Lynx command line, in which case, this variable takes the place of the DSZLOG variable (described above). This allows Lynx to keep a log separate from the DSZ log file. E x i t C o d e s _____________________________________________________________ When Lynx is finished, it will set the DOS errorlevel code to alert a calling program to success or failure of the transfer. If Lynx is successful in the transfer, an errorlevel of 0 will be returned. If correct parameters are given, but Lynx fails to successfully transfer any or all of the requested files, an errorlevel of 1 will be returned. If Lynx is invoked without parameters (to show the help screen), an errorlevel of 2 will be returned. S u p p o r t _____________________________________________________________ If you have any questions or comments regarding Lynx, feel free to leave mail to Matt Thomas on The Harbor Master BBS in Racine, Wisconsin at (414) 681-1123. An attempt will be made to answer any mail received on this system. Another mode of support is now available via Bulletin Board Systems which carry MetroLink and the Lynx support conference. Address any questions or suggestions to Matt Thomas, and make sure the mail is echoed to other systems. If you wish to write to the author, you may do so: Lynx Development c/o Matthew Thomas 4210 North Main Street #226 Racine, WI 53402 No guarantee is offered that letters from unregistered users will be answered. REGISTERED Lynx users have number-one priority for support. Lynx Version 3.02 Page 14 U p d a t e s _____________________________________________________________ Any new releases of the Lynx engine are made available immediately on the Harbor Master BBS in Racine, WI at (414) 681-1123 and on Exec-PC in Milwaukee, WI at (414) 964-5160. When you register your copy of Lynx, you will receive an upgrade program which will allow you to convert any SHAREWARE version of Lynx to a REGISTERED version. The following updates have been made since initial release: 3.02 (9/16/89) - Repaired bug that caused lockups on QMODEM Version 4.0. - Repaired bug that caused carrier drops on certain modems when Lynx loaded. - Changed memory allocation. All memory allocated statically at run time. Memory requirement for this version is 48K bytes. - Changed max number of files per batch to 99. 3.01 (9/3/89) - Repaired a bug that caused Lynx to misbehave on some UARTS. - Added "File number" on window display (registered copies only!) - Removed 115200 baud option. Highest baud rate is now 57600. 3.00 (8/27/89) - First SHAREWARE RELEASE ($15 registration) - Rewrote COM port routines in assembly language for faster throughput on high-speed connections. - Added "modem lights" on /S display - Added progress meter on /S display - Lynx now properly senses the presence of the requested COM port, be it 8250 or 16450, and aborts with an appropriate message if one is not present. - Added /L parameter for clean connections. - Added LYNXLOG support and the /G parameter. - Fixed a bug in the RTS handshaking code. 2.20 (7/30/89) - Fixed COM services to allow Lynx to access UARTS other than the Intel 8250. - Improved transmit speed when /H is used on MNP modems in non-buffered mode. - Lengthened the bell at the end of a transfer (enabled with the /B command parameter). - Fixed the COM routines to keep concurrently executing programs from disabling Lynx's COM port interrupts. - Updated documentation. Lynx Version 3.02 Page 15 2.13 (7/08/89) - Changed the "path" parameter to allow programs to pass a full file name on the receiver command line (although only the path is used). This was a problem with RBBS systems in particular. 2.12 (7/01/89) - Hopefully all MNP problems fixed for good! - Fixed COM routines to restore 8250 interrupts to their exact original state. This affected older versions of ProComm, and RYBBS systems. 2.11 (6/21/89) - Added window option in /S parameter - Added LYNXCO environment variable support. - Fixed bug in sender--sometimes would not respond to receiver cancellations. - Improved error recovery - Increased transmitter throughput for multi- tasking systems and slow (4.77 MHz) computers. 2.10 (6/14/89) - Added CTS/RTS handshaking for MNP modems and high-speed buffered modems - Added 115200 baud option - Removed DIRRX environment variable, due to problems. - Fixed bug in sender mode: lockup on lost carrier. - Added /S parameter for fast screen writes 2.00 (6/3/89) - Added list file compatibility - Added /B, /W, /D, and /T switches - Optimized communication routines - Added configuration environment variables for COM3 and COM4 - Added DIRRX environment variable - Added a faster baud rate (57600 baud) - Support for up to 255 files per batch instead of only 35. 1.3 - First official release Lynx Version 3.02 Page 16 T r a d e m a r k s _____________________________________________________________ MS-DOS is a trademark of Microsoft Corporation. DSZ is a trademark of Omen Technologies, Inc. DesqView is a trademark of QuarterDeck Systems. The USR HST 14400 is a product of USRobotics The ATI 2400etc modem is a product of ATI Lynx Version 3.02 Page 17