Programmer 7500

home *** CD-ROM | disk | FTP | other *** search

/ Programmer 7500 / MAX_PROGRAMMERS.iso / PROGRAMS / UTILS / COMMUNIC / K9X88D_3.ZIP / DOCS.ZIP / LYNX.TXT < prev next >

Wrap

Text File | 1989-07-02 | 29.9 KB | 793 lines

__________ /\_\_\_\_\_\ /\/ /\ /\/ L Y N X /\/ \/_ _ _ _ _/\/ \_\_\_\_\_\/ A full streaming/RLE compression/CRC-32 batch transfer protocol Copyright (C)1989 by Matthew Thomas & John Schuit All Rights Reserved Version 2.12 - July 1, 1989 Documentation by Matthew Thomas Lynx 2.12 - Copyright (C)1989 by Matthew Thomas & John Schuit W h a t i s L y n x ? _____________________________________________________________ Lynx, in my original definition, is a data transfer protocol which utilizes proven techniques of data compression, error recovery, and full-duplex communication to produce highly efficient and successful file transfers, regardless of the connection quality. Lynx also happens to be the name of the MS-DOS(TM) engine which I have provided in this package as a full implementation of the protocol. W h y i s L y n x P u b l i c D o m a i n ? _____________________________________________________________ In my theory--which no one finds particularly interesting, but I shall elucidate, regardless--there are two marketing schemes to make software available to a typical computer user: 1) Free software 2) Expensive software The similarity between the two is in the fact that there are benefits to each approach, generally befitting either the user, in the case of the first approach, or the vendor (or filcher) in the second approach. The difference between the two is not only in the spelling, but in the fact that expensive software isn't always the best, and doesn't typically make a programmer very popular, because his or her byline is generally lost in the inkblot of corporate copyright and legal mumbo-jumbo that is likely to present itself upon initial view of the documentation. * * * What this all boils down to is the fact that I beleive in both types of software marketing schemes, but I have chosen the first for Lynx because I would like everyone to benefit from the protocol, regardless of their budget. Page 1 Lynx 2.12 - Copyright (C)1989 by Matthew Thomas & John Schuit L e g a l i t i e s a n d L o n g W i n d _____________________________________________________________ The copyright notice on Lynx is present because I am proud of my work. I own all rights to the source code of the MS-DOS(TM) engine for Lynx, and presently no plans have been made to make it public domain. However, you--and anyone else reading this--may feel free to distribute the provided archive in unmodified form to whomever you wish, free of charge, no royalties or remunerations. What you can't do, is remove my name and my copyright notice from any portion of the archive or its contents for any reason. If you are actually reading this, you are an outstanding citizen, and likely realize that copyrights exist for a valid reason, not just to provide confusing legalese; or perhaps you are dropping off to sleep, in fervent hope that a dream will be more interesting than enduring these boring legalities..... W A K E U P ! It's getting interesting. H o w D o e s L y n x W o r k ? _____________________________________________________________ Lynx 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 checking the receive buffer for any interruptions from the other end. On half duplex links, this will not work. But since almost all modems in use today are capable of full-duplex operation, this specification is 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. This handshaking is in the best interest all parties because when errors occur, loss of synchronization is quite possible if the proper secret club handshake is not used. Lynx can transfer up to 255 files in a single batch. Information which is passed from sender to receiver concerning each file includes: Filename (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 selectable up to 115200 baud. Page 2 Lynx 2.12 - Copyright (C)1989 by Matthew Thomas & John Schuit Lynx transfers are protected with CRC-32 error checking, 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 receiver 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 retransferring the entire file. During the course of the transfer, 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 everhead 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 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 occurance during error recovery) Lynx tests each block for compressability before transmitting it. An RLE (Run-Length-Encoding) compression technique is used for this operation. Generally, a block containing text type information will be compressable. Archived 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 fully supports buffered and high-speed MNP modems with CTS/RTS hardware handshaking. Throughput on these modems is extremely high using the Lynx protocol. Page 3 Lynx 2.12 - Copyright (C)1989 by Matthew Thomas & John Schuit H o w D o I U s e 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: +-----------------------------------------------------------+ |Parameters: none. | | | |Usage: LYNX S [options] [@file] [[file] [file] [...]] | | LYNX R [options] [path] | | | | [options] : /baud - set the baudrate 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 | | | | [@file] : file containing list of files to send | | [file] : file to transmit (sender only) | | [path] : drive and path location for received files | | | |Default: Current baud - COM1 - carrier checking enabled | +-----------------------------------------------------------+ The following is a complete explanation of all parameters, and how each is used: 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. /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, /57600, and /115200 If this parameter is not used, Lynx will autosense the current baud rate of the port in use. Page 4 Lynx 2.12 - Copyright (C)1989 by Matthew Thomas & John Schuit /com : This parameter allows you to specify which COM port to use. Values from 1 to 4 are legal. For example, to use COM2, use the parameter /2. The default COM port may also be specified with a DOS environment variable, which is explained in the next section. /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. /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. This sounds rather 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. /B : This option causes Lynx to sound a bell upon completion. The bell will sound regardless of whether the transfer was successful or not. /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. /D : When this parameter is used, all received files will be stamped with the current time and date when they are closed (when transfer is complete). Normally--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. /T : When this parameter is specified, Lynx will drop the DTR and RTS signals to the modem when the transfer is completed. Normally, these two signals are left in their original state upon completion. Page 5 Lynx 2.12 - Copyright (C)1989 by Matthew Thomas & John Schuit /H : This option causes Lynx to use CTS/RTS handshaking during the transfer. This is desirable when using high-speed buffered modems or MNP error correcting modems, because of the full-streaming nature of the Lynx protocol. Using this option with these modems allows data to be transmitted as fast as the modem will accept it, without causing data errors. /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 next section. @file : This parameter can be used by the sender to specify a list file that contains a list of path/filenames of files to be sent in a batch. In the list file, each filename must be separated by a carriage return/linefeed combination. Blank lines are ignored. For example, the command: lynx s @listing.lst tells Lynx to send all the files which are listed in the file 'listing.lst'. DOS wildcards are supported inside the list of files only. The filespec which follows the @ must be an absolute filename. file : This parameter may consist of a full path and filename of a file to send. DOS wildcards are fully supported. A total of 255 individual files may be send in a single batch. This parameter may be repeated on the command line to send multiple files. path : This parameter may specify a DOS drive and path location where Lynx should place all files which are received. 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. Page 6 Lynx 2.12 - Copyright (C)1989 by Matthew Thomas & John Schuit U s i n g E n v i r o n m e n t 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 may use either the DOS 'SET' command, or build the variables into the DOS environment table using a high-level language. The first technique is probably the easiest and most widely used. 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: 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 filename. Example: 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 occured 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. Page 7 Lynx 2.12 - Copyright (C)1989 by Matthew Thomas & John Schuit 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. For example: LYNXP3=2E8,3 tells Lynx to configure COM3 for base port address 2E8 and for interrupt 3 (irq3). The default configuration for COM3 is base address 3E8 and interrupt 4 (irq4). 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 Page 8 Lynx 2.12 - Copyright (C)1989 by Matthew Thomas & John Schuit 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 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. Q u e s t i o n s ? _____________________________________________________________ If you have any questions or comments regarding Lynx, feel free to leave mail to Matthew Thomas on PC Access BBS in Racine, WI at (414) 634-5776. I am a regular caller of this BBS, and I will attempt to answer any mail received. If you feel like donating money to support future releases and upgrades of Lynx and other related projects, feel free to do so in whatever amount seems adequate. Remember that you are not required to donate anything to use Lynx. Donations are completely voluntary (and equally unlikely). Here's the mailing address: Matthew Thomas 144 Westminster Square Racine, WI 53402 Page 9 Lynx 2.12 - Copyright (C)1989 by Matthew Thomas & John Schuit K u d o s _____________________________________________________________ I would like to express my appreciation to the people who aided me during the Lynx project: Chuck Dennis PC Access Systems Racine, Wisconsin (414) 634-5776 -Thanks for the use of your MNP modem for handshaking, as well as the time you spent testing Lynx and offering moral support! Gary Huff Capitol City BBS Springfield, Illinois (217) 529-6452 -Thanks for alerting me to previous incompatibilities with RBBS (which are now eliminated), and for spreading the word about Lynx! John Schuit Racine, Wisconsin -Thanks for contributing greatly to the project. The Lynx color window display was designed and implemented by John Schuit. Page 10 Lynx 2.12 - Copyright (C)1989 by Matthew Thomas & John Schuit V e r s i o n U p d a t e s _____________________________________________________________ The following releases and upgrades have been made to Lynx since its first release: 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.77MHz) PC's. 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 public release 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. Page 11