























                                   __________
                                  /\_\_\_\_\_\
                                 /\/         /\
                                /\/ 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.20 - July 30, 1989



                        Documentation by Matthew Thomas

























              Lynx 2.20 - 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 is
         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.



         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



                                          Page 1




              Lynx 2.20 - Copyright (C)1989 by Matthew Thomas & John Schuit



         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.

         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.




                                          Page 2




              Lynx 2.20 - Copyright (C)1989 by Matthew Thomas & John Schuit



         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.

         The Lynx engine program currently requires 48K of free RAM to
         operate.  If a large number of files are transferred in a single
         batch--say, more than 10--then more memory may be required to hold
         the path/file specification information for those files.

         When opening files, the Lynx engine uses the DOS filemode
         identifier to protect the files from outside tampering.  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, the file is closed and
         can be accessed by anyone for any operation.



         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.



                                          Page 3




              Lynx 2.20 - Copyright (C)1989 by Matthew Thomas & John Schuit




         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.

            /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.  Normally the default is
                   COM1, however, the default COM port may be specified
                   with a DOS environment variable, which is explained in
                   the next section.




                                          Page 4




              Lynx 2.20 - Copyright (C)1989 by Matthew Thomas & John Schuit



             /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).
                   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.

              /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



                                          Page 5




              Lynx 2.20 - Copyright (C)1989 by Matthew Thomas & John Schuit



                   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.
                   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.

           @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.
                   For example:

                   lynx r c:\telix\

                   will make Lynx receive files into the c:\telix
                   directory.  There must be a backslash at the end of the
                   specified path.

                   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.

                   NOTE:  Beginning at version 2.13 of the Lynx engine,
                   this parameter may also contain a filename.  Lynx
                   ignores the filename if it is specified, because
                   filenames are always passed through the communication
                   link.  But some BBS programs insist on using the
                   filename, so this is now acceptable to Lynx.  When you
                   ARE specifying a filename, there should be NO backslash
                   at the end.  For example:

                   lynx r c:\telix\myfile.ext




                                          Page 6




              Lynx 2.20 - Copyright (C)1989 by Matthew Thomas & John Schuit



                   will tell Lynx to receive a files into the c:\telix
                   directory.  The myfile.ext portion is tossed.



         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 can 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:  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.



                                          Page 7




              Lynx 2.20 - Copyright (C)1989 by Matthew Thomas & John Schuit



                     - 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.

                     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.20 - 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 Matt 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.

         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 me (Matt Thomas), and make
         sure the mail is echoed to other systems.  I will receive any
         public messages which are left in the Lynx support conference.

         I have recently been spending an enormous amount of time
         supporting the Lynx protocol, answering questions and adding
         requested features to the Lynx engine.  Since Lynx remains a free
         product, I still require no remuneration for its use.  However, if
         you feel that Lynx is a quality product, and you wish to see Lynx
         remain fully supported by the author, feel free to donate in any
         amount ($10 is a nice amount if you're one of those people who
         never knows how much or how little to donate).

         Remember that if you do not donate, you may still use the Lynx
         engine to an unlimited extent.

         Here's my (new!) mailing address:

          Matt Thomas
          4210 N. Main Street #226
          Racine, WI 53402













                                          Page 9




              Lynx 2.20 - 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.



         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.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.







                                         Page 10




              Lynx 2.20 - Copyright (C)1989 by Matthew Thomas & John Schuit



         2.13 (7/08/89) - Changed the "path" parameter to allow programs to
                          pass a full filename 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.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


