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