Preface:

	This is a text-only version of the Listen Operator's Manual.
	Sections pertaining to the Liscensing Agreement and Warranty
	apply only to registered versions of the product.  Unregistered,
	Shareware versions of Listen may be freely distributed and are
	distinquished from the registered version only by the addition
	of Registration Reminder Screens and a time limit placed on an 
	active monitoring session.


Listen... A Serial Data Line Monitor for Windows
1.	Introduction..A Word about Shareware

	1.1	What Shareware is
	1.2	Advantages of Registration.
	1.3	Registration of the Listen Application	
	1.4	Licensing Agreement
	1.5	Warranty
2.	Listen System Requirements

	2.1	Operational Overview
	2.2	System/Cabling Requirements
	2.3	.INI File Parameters

3.	Installation

	3.1	Making Backups
	3.2	Installing Listen

4.	Basic Menu Selections

	4.1	ToolBar
	4.2	Hardware Setup
	4.3	Display Preferences
		4.3.1	Color & Font Selection
		4.3.2	Non-Printing Character Display
	4.4	ASCII Table
	4.5	StatusBar

5.	Monitoring Data Communications

	5.1	Menu Options
	5.2	Scrolling Characteristics
	

6.	Browsing Captured Data
	
	6.1	Browse Menu Options
	6.2	Block Operations
		6.2.1	Print
		6.2.2	Copy to Clipboard
		6.2.3	Search/Find
		6.2.4	Checksum Calculator
	
7.	Using Filters

	7.1	Byte Filters
	7.2	Block Filters
	
8.	Trap Buffer Operation

	8.1	Trap Buffer Operation
	8.2	Trigger
	8.3	Browsing the Trap Buffer

9.	Technical Support
	
	9.1	Contacting WinTECH

1.	Introduction..A Word about Shareware
1.1	What is Shareware

Shareware is a distribution method, not a type of software.  Shareware
products may be freely distributed among potential users with each user
given an opportunity to fully evaluate the software over a specified
period of time. This distribution method gives users a chance to try
software before buying it.  If the particular shareware application
provides a service that the user wishes to continue beyond the specified
evaluation period, a registration payment to the software author is
required.

Copyright laws apply to both Shareware and commercial software, and
WinTECH Software retains all rights to its software products with the
following exception:

WinTECH Software specifically grants the right to copy and distribute
unregistered copies of the Listen Application to all interested parties
for an evaluation period not to exceed thirty-days.

1.2	Advantages of Registration
The Shareware distribution system depends upon the integrity of the user
to make the required registration payment only if the application proves
itself useful.  Shareware products have the ultimate money-back guarantee.
If the product is not used, no payment is required.  Registration of
Shareware products support this system of distribution and allow continued
development of low-cost high quality software solutions.

1.3	Registration of the Listen Application

Unregistered copies of the Listen Application are functionally equivalent
to registered copies with the following exception:
To encourage registration, a limit is placed on the amount of time data
may be collected during a monitoring session.  This limit does not effect
the ability of a user to fully evaluate either the functionality or
through-put of the application.  

Registration of the Listen Application requires a registration fee
of $49.95 be submitted to WinTECH Software.  The user shall receive in
return the most recent registered version of Listen with all time limit
constraints and registration reminder screens disabled.   The user
shall also receive a printed user manual, and free technical support
for a period of three months after registration.  Registered users also
have direct access to the Listen design engineer and a commitment from
WinTECH to consider product enhancements based on individual application
requirements.  In other words, if you can think of anything that would
make your life easier, let us know.  If it has general marketing appeal,
chances are it could be included in the next revision.

1.4	Licensing Agreement

Registered WinTECH software is protected by both United States Copyright
Law and International Treaty provisions.  Therefore, you must treat this
software just like a book with the following single exception.  WinTECH
Software authorizes you to make archival copies of the software for the
sole purpose of backing-up your software and protecting your investment
from loss.

By saying "just like a book," WinTECH means for example that this software
may be used by any number of people and may be freely moved from one
computer location to another so long as there is no possibility of it
being used at two locations at the same time.  Execution of two copies
of the same registered Listen application at the same time constitutes
a Copyright violation and is expressly prohibited.

1.5	Warranty

With respect to the physical diskette and physical documentation enclosed
herein, WinTECH Software warrants the same to be free of defects in
materials and workmanship for a period of 30 days from the date of
registration.  In the event of notification within the warranty period
of defects in material or workmanship, WinTECH will replace the defective
diskette or documentation.

WinTECH Software disclaims all other warranties,
expressed or implied, including without limitation, the warranties or
merchantability and of fitness for any purpose.  WinTECH Software assumes
no liability for damages, direct or consequential, which may result from
the use of this program.

2.	Listen System Requirements
2.1	Operational Overview

Listen is a Windows application designed to monitor serial data
communications utilizing the receive line of one or more serial COM ports.
Windows 3.1, Windows for Workgroups  3.11, or Windows '95 is required.
At least one free serial port is required, however, to be an effective
communications monitor two ports are necessary. 

Listen was designed to operate on RS-232 based systems that utilize
software protocols involving half-duplex, block oriented data transmissions
whereby data is only transmitted by one device at a time. The RS-232
electrical protocol provides two distinct and physically separate transmit
lines between two communicating devices.  (i.e. Transmit from Device A to
Receive Device B and vice versa.)  By tapping in to each of these transmit
signals via two separate PC receive lines, Listen can easily monitor all
activity between the two original devices, maintaining all timing
characteristics,  without effecting communications integrity.

The communications system being monitored does not have to be RS-232,
nor half-duplex in nature.  Listen simply enables the receiver for the
specified serial port and captures all data that shows up.  

Multidrop communications protocols, (RS-485, Current Loop, etc.), are
available for PC's and should operate with the Listen application using
a single serial port.  However, since data is identified by the port
number on which it is received, all character data would be displayed
using the same display attributes, (color & font).

2.2	System/Cabling Requirements

This manual assumes  RS-232  based communications systems are to be
monitored using standard PC Serial hardware.  Listen utilizes the
standard Windows communications drivers to access the COM ports.  This
may be somewhat slower than accessing the serial ports directly, but
maximizes compatibility across PC platforms.  

The colors and fonts used to display character data are selectable by
the user to best take advantage of the available display technology.
Portable PC's are ideally suited for monitoring applications.

The passive nature of the Listen design, will not degrade communications
performance if the monitoring device proves too slow to capture all the
data.  Data may be missed by the Listening Device, but the integrity of
the original link will be maintained.  


Cabling requirements for the Listen Application, assuming RS-232, consist
of 2 wires for each COM port.  The RXD and  GND signals, (Receive Data &
Ground), for one port are connected to the TXD & GND of a single
transmitting device. The RXD & GND for the second port are connected
to TXD & GND for the second transmitter.  RS-232 control signals, if used,
remain in place.  Since the TXD signal for one device is always connected
to the RXD signal for the other device, all monitoring connections may be
made at the same end of the cable.  Clipleads are commonly used for cable
connections.

2.3	.INI File Parameters

The default values for the size of the capture buffer and trap buffer
allocated by Listen during startup are 16K bytes and 1K bytes respectively.
Global memory is allocated by Listen during startup and returned to Windows
on termination of the application.  The user may change the allocated
buffer sizes by modifying the [MEMORY] section of the Listen.ini file.

[MEMORY]
BUFFERSIZE = 16
TRAPBUFFERSIZE = 1024
TRAPBUFFERPLACEMENT = MID

The capture buffer size is specified in 1K increments up to 64K.  The trap
buffer size is specified in bytes up to a maximum of 16K.

Trap Buffer Placement specifies the position of the trigger with respect
to data contained in the trap buffer.  The valid selections are:

PRE - The trap buffer represents the contents of the capture
	buffer prior to the trigger point,  (i.e. when the trigger occurs,
	the trap buffer is immediately filled with data existing at the
	time of the event).

MID - The trap buffer represents data surrounding the trigger point.
	When the trigger condition occurs, half the trap buffer is filled
	with existing data, with the remainder filled with data received
	after the trigger.

POST - The trap buffer represents data collected immediately after the
	trigger point.


3.	Installation
 
3.1	Making Backups

The distribution diskette is not copy-protected, and the registered user
may make backup copies as required.  The Listen application may be moved
from one PC to another so long as the basic licensing agreement of only
one copy in use at a  time is maintained.  Site licenses are available for
commercial users by contacting WinTECH Software.

3.2	 Installing Listen

Installation of the Listen Application involves simply copying the
Listen.exe & Listen.hlp files from the distribution diskette to a
working directory on the hard disk.  Listen.ini may also be copied if
desired.  After running the application for the first time, a
configuration file will be created on the working directory.  Listen.cfg
represents the user configurable selections, (character font, colors,
baudrate, etc.), in effect at the time the program terminated. These
settings will be restored the next time Listen is started.  

Listen may be started from the program manager, file manager, or program
group icon.  Consult the Windows user's manual for details.  The
background Listen display represents a simplistic cabling diagram
describing the interconnections between the PC used to monitor serial
communications and two separate RS-232 communicating devices.  


4.	Basic Menu Selections

4.1	ToolBar
The Listen toolbar provides convenient access to commonly used
functions as described below.  The toolbar may be enabled/disabled via
a menu option.
 
Open   Save   Go    Stop   Copy  Print About
            (New) (Browse)


4.2	Hardware Setup

To setup the serial ports in preparation for a monitoring session,
activate the Setup, Hardware options from the Listen Main Menu.
Listen will present a dialog box containing the current settings for
each of the four PC COM ports.  Dropdown list box edit controls allow
selection of baudrate, parity, number of data bits and number of stop
bits for each port.  The information for a particular COM port is only
displayed if the port is available for use by the Listen application.
If the port is not installed, or in use by another Windows application,
the associated portion of the dialog box will be greyed, (disabled).

Configuration of the hardware characteristics for a serial port does
not enable the port for communications. These settings will be used to
actually initialize the port whenever a monitoring session is initiated
by exercising the New menu option.

4.3	Display Preferences

During an active monitoring session, Listen displays data across the
screen as it becomes available from the respective communications ports.
Configuration options define the colors and fonts used to display this
data, as well as the ASCII character representation.

4.3.1	Color & Font Selection

To configure the foreground and background colors used to display data
from each COM port, select the Setup, Preferences, Colors options from
the Listen Main Menu.

Listen will respond with a dialog box representing the current color
selections for each of the four communications ports as well as the
foreground and background colors to be used for block marking operations
on captured data.  The text marker colors are used during cut and print
operations to distinguish the data effected by the operation.

The display in the center of the dialog box displays examples of the
current pen colors.  To change the colors used to represent data received
from a given port, press the appropriate foreground or background button
and pick a new color from the color selection dialog.

Selection of character fonts occurs in much the same way by initiating
options under the Setup, Preferences, Fonts branch of the Main Menu.
A separate font selection dialog box is activated for each individual
Com port.

4.3.2	Non-Printing Character Display

The default implementation of Listen displays captured byte data as
the ASCII equivalent character codes for data between 033-126, (decimal).
This includes all alpha-numeric data plus special keyboard characters such
as $, %, etc.  Control character data, including the SP character, (000-032),
is displayed as a two or three character alpha representation surrounded
by square brackets, (such as [SP], [SOH], [ETX], etc.)  8-Bit data is
displayed as a bracketed decimal value such as [128], [129], etc.  If
square brackets are included in the capture data, they are represented
as their decimal equivalent, ([91],[93]).

Two menu selections allow customization of character data display.

Selection of the Setup, Preferences, Num Base menu option will allow the
user to configure the numeric base, (Octal, Decimal, Hexadecimal, or
Binary), used to display non-printing characters.  This option not only
effects character display, but also determines how byte data is specified
during configuration of filters, triggers, and search strings.

If square brackets have some special meaning within the protocol being
monitored and the user wishes to use different characters to surround
non-printing character data, the Setup, Preferences, Brackets menu option
presents a dialog box that allows selection of both the leading and trailing
character.

Any ASCII code may be selected for the opening and closing bracketing
character.  They do not have to match and the same code could be selected
for both if desired, (i.e. /000/,/128/).  Which ever character is selected
for use as a bracket, the representation for that character, if it appears
in the data stream itself, would always be displayed as a bracketed numeric.  For example, using the above illustration, the byte representation of a slash character would be /47/ using the decimal numeric base.

4.4	ASCII Table

If the flexibility for configuring the display as described in previous
sections is not sufficient, Listen provides the user with the option
of explicitly defining the character representation to be used for each
byte code. The View, ASCII Table menu selection activates a Listen Child
Window that displays the current display settings for each of the 256
byte codes.  The ASCII Table displays the numeric values for each
byte code in decimal, octal, hex, and binary notation.  Scrollbars
are supported and the window may be resized and positioned on the
screen to maintain as reference during monitoring or browsing
operations.  Selecting a byte code representation and double-clicking
with the left mouse button presents a dialog box that allows the
character representation for a given byte code to be modified.

Character strings of up to 10 bytes may be used for each code.
Any or all character codes may be overridden in this fashion.
All changes are maintained in the Listen.cfg file and will remain
in effect the next time Listen is started.

4.5	StatusBar

The Listen statusbar represents the condition of the trap buffer,
trigger status, filter activation status, and enabled COM ports.
It may be turned off via a menu selection.
5.	Monitoring Data Communications

5.1	Menu Options

A monitoring session is initiated by clicking the "Go" button on the
toolbar or by selecting the New/Collect option from the Main Menu.

If no ports have been enabled, Listen will prompt for the port ids
to monitor.  If this is a re-initiation of a previous monitoring
session, Listen will automatically enable those ports that were in
use the last time.  Ports are disabled whenever a monitoring session
ends, (Browse Enabled), to prevent unnecessary Windows messaging while
connected to a live communications system.   During a monitoring
session, the Files Menu selections change to represent the enabled
state of each COM port.  To enable or disable a port, simply click
on the appropriate menu selection.    
  
5.2	Scrolling Characteristics

Listen displays characters to the screen in the font selected for
the respective COM port.  Since most Windows fonts are variable width,
the end of each display line will not necessarily be aligned.  If a
fixed-width font, (such as Courier), is selected, the end of line
may still not be aligned due to the variable number of characters
used to display non-printing or user configured character string data.

Listen will always attempt to maintain the integrity of the display
for each data byte.  If the entire character string representation
for a data byte cannot be displayed to the end of a display line,
Listen will advance to the next line.

If different fonts are used for different COM ports, Listen will
calculate the y-pixel line height based on the tallest font included
in the line.

Italicized fonts present some problems when scrolling backward in
the Browse mode of operation.  The scrolling operation works well,
but the entire width of the display line may not be used since Listen
calculates the x-pixel coordinates a character at a time in reverse.
The calculation for the sum of individual character widths for
Italicized fonts is greater than the width calculated for a line
containing the same characters, (i.e. the top and bottom of successive
characters overlap).  


6.	Browsing Captured Data

6.1	Browse Menu Options

The Browse mode is the startup mode of operation for Listen and is the
default mode of operation when not actively monitoring a communications
link.  Menu options allow the display view to be switched back and forth
between the capture and trap buffers.  Data may also be saved to a
disk file or restored from a previous session.

Either memory buffer may be saved to disk.  Data may only be restored
into the capture buffer.  Data is written to disk in a straight byte
binary form without color, font, or display preferences.  A 128 byte
header is used to identify the file as a Listen byte data file and
provide details concerning buffer size requirements.  Starting at
byte 129, data is written in alternating byte locations as data
byte followed by port number, (1-4).  

When restoring a data file, the buffer size information is used to
provide a user warning message if the disk file contains more data
than will fit in the existing memory buffer.


6.2	Block Operations

Block operations are used when displaying a captured buffer to
mark a section of data for copy and print operations, or to use as
input to the Checksum Calculator.  Blocks are marked by clicking the
left mouse button on an area of the display and dragging it to the
end of the area to be manipulated.  Dragging the mouse past the
bottom of the display or over the top will cause the display to be
automatically scrolled up or down.  Marked data blocks are displayed
in the foreground/background color specified via the color selection
dialog.

6.2.1	Printing

Portions of the capture or trap buffers may be printed by selecting
a block and pressing the Print menu option.  The selected data will
be routed to the printer using the same display colors as selected
for the screen.  These colors may be temporarily adjusted via the
color selection menu to allow proper printing using a dot matrix or
non-color printer.

Byte data will be printed using the default font selection for
the printer.  The fonts used for display of data to the screen will
not be used for the hard-copy.


6.2.2	Copying to Clipboard

Portions of data may also be copied to the Windows Clipboard by
selecting a block and pressing the Copy menu option.  Data is
copied to the Clipboard in a block-oriented fashion with data
received from different COM ports displayed on different lines.
The port identification appears on the front of each line as in the
following example:

Port 1: [SOH]0001[STX]00120120110[ETX][190][EOT]
Port 2: [SOH]0001[STX]READY[ETX]A[EOT]
Port 1: [SOH]0010[STX]00009009900990[ETX]F[EOT]
Port 2: [SOH]0010[STX]READY[ETX]A[EOT]


6.2.3	Search/Find

A marked block of data may also be used as input for the search
algorithm.  Search may be initiated based on a used defined search
string as well.  Searches may be performed forward or reverse through
the displayed buffer.  If a match is found, the buffer is advanced
to the appropriate location and the matching block of data is highlighted.

6.2.4	Checksum Calculations

During trouble shooting of a communications link, it is often beneficial
to double-check a checksum calculation for a string of data bytes to
ensure proper response by the receiving device.  Listen provides a
built-in calculator for several widely used checksums.  Marking a
block of data and clicking on the appropriate checksum menu selection
will generate a dialog box detailing the results of the calculation.


7.	Using Filters

7.1	Byte Filters

Listen supplies four byte filters, one for each COM port.  Each byte
filter consists of an eight bit mask that may be applied to all incoming
data to prevent selected data from entering the capture buffer.  Each
bit in the mask is specified with either a '1', '0', or "don't care"
designation.  If a Byte Filter is enabled for a given COM port, Listen
compares each byte received with the bit mask and excludes all data that
fails the comparison.  

The Setup, Filters, Bytes menu selections generate a dialog box that
displays the current settings for each bit mask with an enable/disable
check box.

Selecting the button corresponding to one of the four COM ports
allows the bit mask to be changed.

Each check box associated with a data bit represents one of three states.
A checked box equates to a '1'.  An unchecked box equates to '0'.
If the "Apply to All Ports" option is used, the specified bit mask
will overwrite the current selection for all four COM ports.

7.2	Block Filters

Block filters may be used in protocols operating in half-duplex mode.
A block filter consists of a string of bit masks applied to the start
of each data communications block.  The start of a block is always
identified by a transition of data direction as determined by the
port identification of the data received.  Timing of data transmissions
has no effect on the determination of the start of a block.  Listen
simply compares the port number of each data byte received with the
port identification of the last byte received, and if it's different
begins a new block filter comparison.

As an example, assume the protocol being monitored operates as follows:  

Device A transmits 10 bytes to Device B.
Device B transmits a single byte acknowledgment.
Device B then transmits a 10 byte response back to A.
Device A acknowledges the response.

If Listen is connected to Device A via port 1 and Device B via port 2,
it would receive 10 bytes from A, followed by 11 bytes from B, followed
by 1 byte from A.

This would be interpreted as three data blocks.  If Device A initiates
a new message to B, Listen would assume the data is a continuation of
block #3.  Since the port identification is used to determine block
transitions, block filters may not be used in applications using a
single COM port to monitor communications.

To configure block filters, select the Setup, Filters, Block menu options.

Block filters may be enabled/disabled by simply checking the associated
box in the dialog described above.  Modifications to the byte string may
be made by selecting the appropriate port button. 

Byte strings may be entered to specify block filters in the same format
as used by Listen to display byte data.  Alpha-Numeric characters,
bracketed control characters, or bracketed numeric values may be used.
In addition, bit patterns may be specified by entering a bracketed
8 digit notation representing a binary value, (i.e.[1010xxxx]).

As with byte filter specification, a single block filter may be applied
to each COM port by checking the appropriate box in the specification
dialog.

8.	 Trap Buffer Operation

8.1	Trap Buffer Operation

Listen makes available a block of memory separate from the normal
capture buffer called a trap buffer.  The purpose of the trap buffer
is to obtain and maintain a "snapshot" of the capture buffer based on
a configurable event called a trigger.  The trigger is a string of
data bytes, (including don't care bit masks), which is compared to
received data for determination of the event.  

When triggered, data is copied from the capture buffer to the trap
buffer and held indefinitely, or until the same trigger event occurs
again.  Continued data collection will eventually wrap around the
capture buffer, but the contents of the trap buffer is always available
for browsing.  This provides an effective trouble-shooting aide for
trapping infrequent communications faults.  

8.2	 Trigger

The trigger is specified in a dialog box similar to that used for
byte string entry for block filters.  Data may be entered as
alpha-numeric characters or as bracketed numeric values.  Bit
patterns may be entered in bracketed binary notation using 'X' for
don't care bits.

A trigger comparison may be associated with data received from a
specific port or a global comparison may be made with data received
from any COM port.  A trigger comparison does not have to begin with
the start of a data block, but may not span data from two devices.
A block transition will always reset the comparison logic counters.


8.3	Browsing the Trap Buffer

A menu selection available from the Listen Main Menu allows the
browse display to be switched between the capture and trap buffers.  

9.	Technical Support

9.1	Contacting WinTECH

If it ever becomes necessary to contact WinTECH concerning a
technical question or to offer comments or suggestions for improving
the Listen application please call or write to the address below:

	WinTECH Software
	P.O.Box 907
	Lewisburg, WV  24901
	(304) 645-5966

For quickest response, email questions/comments to:

	listen@win-tech.com

