ComCap - Magenta Serial Port Capture Utility
============================================

Readme for Release 2.3 - 5th November 2001
------------------------------------------

ComCap is a simple Windows application designed to capture any ASCII
data received on PC serial communications ports to text files.  Captured
data is optionally shown in scrolling windows, and may be copied to be
clipboard if required.  Data from up to eight serial COM ports can be
captured simultaneously, in separate files. The capture file names are
automatically generated in the format 'captureX-yyyymmdd.txt' in a
specified directory, with a new file being created each day, week or
month, or several times a day.  Captured data may be optionally echoed
to a local or network printer. ComCap is a system tray application that
can be set to start automatically when windows starts, and remain
unobtrusive.  ComCap will run on any 32-bit version of Windows, on
Windows NT4, 2000 and XP, ComCap may be run as a service, so it
automatically starts when the PC  boots without needing a user logged-on.

Although basic communications settings need to be specified (speed,
parity, data bits), there are no flow control settings and data will
be captured irrespective of the usual control lines (so just a 2-wire
serial cable is needed).

Provided that a reasonably continuous flow of data is being received,
the correct settings can usually be deduced within a minute or say, by
changing the speed until readable data appears.  Although ComCap
ignores the control lines, it does display the status of the CTS, DSR
and DCD lines, and also flashes when data is received.  ComCap sets
the DTR line when capture is enabled, RTS will also be raised, but
depending on the PC, it may always be raised.  ComCap never transmits
any data and does not support software flow control.

ComCap is primarily designed to capture telephone call logging data
from the serial port provided on most telephone switching systems
(PABXs), typically called Call Data Records (CDR).  Only ASCII data
is saved to the capture file.  The saved data may then be used as input
to telephone call management applications that will cost calls and
produce reports on telephone usage.  But ComCap is application non-
specific, and will capture anything that arrives on a serial port.

Please note that ComCap is not designed to monitor data between modems
and PC applications, it requires exclusive access to the serial port so
no other application can use the port at the same time.

The ComCap distribution includes a small application written by a user,
'Concatenation Utility', that allows multiple text file captured by
ComCap to be combined into a single text file that may be easier to
import into a telephone call management application.

ComCap should have a minimal overhead on the PC and can just be left
running minimised.  It will run on any PC or lap top capable of running
Windows 95, such as a 486 with 16 Mbytes of memory (which could be
dedicated for data capture).


Installation
------------

ComCap is usually distributed as a ZIP file which should first be
unzipped into a temporary folder.  If you do not already have it, the
Winzip application from http://www.winzip.com/ (or from most magazine
cover CD-ROMs, Tucows archives, etc) is strongly recommended.

The program SETUP.EXE should then be run to install ComCap.  About
450 Kbytes of disk space is required for the COMCAP.EXE program and
300 Kbytes for the NT service version COMCAPSVC.EXE (this is not
installed on Windows 9x).

If you have received an executable with the name COMCAPS.EXE, this
should be run just like SETUP.EXE to install the software.  If the
service version is already installed, please ignore the error saying so.



Use of Interactive ComCap
-------------------------

ComCap will be installed on the Programs menu, under Magenta Systems.
When first accessed, left or right click on the 'serial connector' icon
in the system tray to open the main ComCap window.  The window has tabs
above the log window, one for each installed COM port (whether or nor
free).  Clicking on a tab changes the log window and status display to
monitor that specific port.

Selecting a tab and clicking settings allows parameters to be specified
for each available communications port.  The directory for the capture
files may be specified  (if blank the program directory is used). 'Capture
Enabled' determines whether this data from this port will be captured.
'No Log Display' suppresses display of call records as they appear, which
may be useful for busy switches. 'Log Raw Data' allows all non-printing
characters to be logged.  'Add Date Daily' causes the date and time to be
added before the first call record each day, or when logging starts,
perhaps to verify the switch data and time is correct.  New logs may be
opened daily, weekly or monthly, or after a specified period of minutes.
The time of day at which daily logs start may be specified. The file name
of the last used into which data was captured is shown.  Captured data may
be echoed to a specified printer with a defined font name and size.

On the icon right click menu, 'Auto Capture' is a tick selection that
causes capturing to start immediately the program is run, for instance if
it's placed in the Startup folder to run when the PC is booted. Don't
use this option if the capturing is done with the service version of
ComCap.

Two buttons allow capture for any enabled ports to be started and
stopped.  Note that the serial port is only initialised when capture is
started, so the control signal lamps are meaningless when capture is
stopped.  The capture file is flushed to disk with a two minute inactivity
timeout to minimise data loss if the PC is powered off while capture is
still active.  The time the last line was logged is shown, together with
the number of lines logged since capturing was started (it is not the log
size).  The Close button hides the window, while Exit terminate ComCap.


Use of ComCap Service (NT4, W2K and XP only)
--------------------------------------------

The ComCap Service is controlled from the Service applet (in Control
Panel or Computer Management), where is appears as Magenta ComCap Service.
The applet allows it to started, stopped, paused or continued.  If it does
appear in the applet service list, trying re-installing it by typing
'COMCAPSRV.EXE -INSTALL' from a command prompt.  The ComCap Service is
installed to be started automatically when the PC boots, but this may
be changed from the Services applet.

The capture settings used are those specified for the interactive
version, so that must be accessed and set-up correctly before starting
the service version.  The NT Event Log will contain entries for
ComCapServ, showing when it was started and stopped, and any errors.  To
print using the ComCap Service, service properties must be set-up to
logon with the account of a user that has the required printers installed,
otherwise printing will fail.  Using an account also means dates will be
correctly formatted in the capture logs.

The most common errors are no settings found (use the interactive ComCap
first), or COM port in use (perhaps by another application).  It is only
possible for either the interactive or service version to capture from
the same port at the same time, otherwise the 'Port Already Being
Captured' appears (in both versions).  Note that the interactive version
is not used to control the service version, they simply share settings.

Uninstalling ComCap should remove the service version from the NT
database automatically.  If it only the interactive version is required,
the service may be removed manually by typing 'COMCAPSRV.EXE -UNINSTALL'
from a command prompt.


Release History
---------------

Release 2.3, 5th November 2001

1 - Added the ability to echo captured data to any installed Windows
local or network printer, using a specified font and size.  Only one
channel can be printed at a time.  Page printers may be used, subject to
the printer perhaps timing out waiting for new data and printing partial
pages, but this feature is really designed for impact printers.  To print
using the ComCap Service, service properties must be set-up to logon with
the account of a user that has the required printers installed, otherwise
printing will fail.  Using an account also means dates will be correctly
formatted in the capture logs.

2 - The opening of new logs has always been difficult to test, since it
needed ComCap to be running for days or weeks to see if the new log was
correctly opened.  There were reports of problems in 2.2 opening logs at
other than 00:00, and at 00:00 in 2.1.  So it was time for a redesign to
make this all more reliable.  The next log time is now determined when
capture starts and shown after the current file name in the window or in
the Event Log for the service version, so it's immediately obvious whether
ComCap is configured and working correctly.   In addition, a new option
has been added to open a new log every X minutes (which is also very
convenient for testing).  New logs are now opened irrespective of data
being received.

3 - Now ensure that the log directory has been created when opening logs.


Release 2.2, 9th August 2001

1 - Made various cosmetic changes by replacing several buttons by main
menu options, allowing further options to be easily added (no space for
more buttons).  When capture is started, only those tabs actively capturing
data are visible, ports that are disabled are hidden.  The tab now also
highlights to indicate data is being displayed in the window.  If 'Stop
Update' is ticked the highlight is removed to indicate the window is no
longer being updated.

2 - Added a new Common Settings window.  This now includes the 'Auto Start
Capture' option that was previously on the icon right click menu.

3 - Added a new Common Setting to change the inactivity period before the
log file is closed.  Closing the file forces captured data to be flushed
to disk.  Previously the period for fixed at 120 seconds, but may now be
set down to one second or up to 999 seconds.  The shorter the time, the
safer the data, but there's always an overhead opening and closing files.

4 - Added two new Common Settings that reflect how much data the log
window shows, and how often it's cleared.  'Maximum log lines to display'
defaults to 10,000 lines to restrict the amount of memory used by CompCap,
but may be set between 100 and 9,999,99 lines.  If the log becomes larger
than specified, it is automatically reduced in size by 'Lines to remove
when display overflows', which must be less lines than the maximum. The
setting used in previous releases has varied, but the 2.1 cleared all
lines when 10,000 were reached, which was not very satisfactory.

5 - The log display window right click menu includes a new 'Stop Update'
tick option.  This is always disabled when capture starts. but if ticked
will temporarily stop new captured data being added to the log window,
allowing earlier data to be located.  Unticking the option will refresh
the log display with any new data captured.

6 - Fixed a display problem that caused lines containing null characters
to be truncated.  Null characters are also now removed from the log file,
unless 'Log Raw Data' is ticked.

7 - Fixed a problem introduced in 2.1 that meant a new log was not
always created each day if 'New Log Time' was set as 00:00.  The same
problem meant daily log file names also included the time.


Release 2.1, 6th April 2001

1 - Any file errors when stopping capture are now ignored.

2 - Fixed a major bug introduced in 2.0 that prevented capture with
paramaters other than 8 data bits and 1 stop bit (which is  fortunately
what most systems use).

3 - A new option 'New Log Time' has been added that allows logs to be
restarted at a time other than midnight. If the time is specified as a
time other than 00:00:00, the log file name will also include the time.
Only one log per calendar date will be created, so if this option is
set before the specified time, it will not create a log file dated
'yesterday'.


Release 2.0, 14th January 2001

1 - ComCap will now capture data from up to eight PC serial COM ports
(hardware permitting) simultaneously, into separate files.  The main
interactive window now has a tabs above the log window, one for each
installed COM port (whether or nor free).  Clicking on a tab changes the
log window and status display to monitor that specific port. Clicking
settings shows a dialog for that port. Settings are separate for each
port, the log files can be in the same directory for different ports, or
different directories.  A new tick box 'Capture Enabled' determines
whether ComCap will try and capture from each port. Clicking the Start
button will start capture from all enabled ports at the same time,
likewise Stop halts collection from all ports.  Sorry, but all settings
need to be redone, again.

Please note that capture has only been tested to two simultaneous serial
ports, since more ports are rare, and even that needed a birds nest of
null modems, gender benders, 25-9 pin converters and cables to link two
PCs together.

2 - 'Auto Capture' has moved from the Settings window to a tick option on
the icon menu, since it applies to all ports.

3 - Unless 'No Log Display' is set, ComCap now displays data from the
current log file when started.  The current log file name is now displayed
in Settings.  These features make it easier for the interactive ComCap to
be used to view the logs from the service version.

4 - The ComCap distribution includes a small application written by a
user, 'Concatenation Utility', that allows multiple text file captured
by ComCap to be combined into a single text file that may be easier to
import into a telephone call management application.

5 - A bug has been fixed in the service version of ComCap, so that the
capture file name is now only written to the event log when capture
starts, rather than each time it is opened (the log closes automatically
after two minutes of inactivity).

6 - An About window has been added.


Release 1.4, 20th August 2000

1 - A Windows NT4 and 2000 service version of ComCap has been added, as
detailed above.  Note that it shares the same settings as the
interactive version.

2 - ComCap settings will need to be respecified for this version,
because they are now held in the HLM section of the registry rather than
HCU, to allow sharing with the service version (which works without a
user logon).

3 - A line is now written to the log file when ComCap is started and
stopped, to assist is determining whether empty log files mean no data
being received or capture not being enabled.  These lines are currently
preceded by ****, if this causes a conflict with real data please say
so and it will be made configurable.


Release 1.3, 3rd August 2000

1 - A problem where auto start did not always work has been fixed.
This seemed to only effect some PCs.  The main window will now flash
briefly as capture is started.

2 - The internal receive buffer has been increased in size
substantially, in case the PC is too busy to flush data to disk.  In
addition, hardware DTR flow control has been enabled in case the
buffer does full up (highly unlikely).

3 - The expiry date has been removed.


Release 1.2, 26th July 2000

1 - Added registration system, so ComCap is now a commercial software
package, see below.  Please note that 1.2 has an expiry date of 30th
September, to ensure the new registration system is working correctly.
Once this is confirmed, a new release without an expiry date will be
issued.

2 - Added traps when resizing the main ComCap window to prevent it
becoming too small.  The window position is now correctly saved when
closing the window.


Release 1.1, 17th February

1 - The new file name is now correctly displayed for a new day, and
captured data from the previous day correctly cleared from the window.


Ordering ComCap
---------------

Until registered, ComCap will only run for 15 minutes before exiting
without any warning.  ComCap may be registered using a secure order
form at the web site, http://www.magsys.co.uk/comcap/.  Once the order
has been processed, a small file 'userreg.txt' is returned by email,
which should be copied into the ComCap directory.  If ComCap is
already running, it should be exited and restarted to see the new
file.  When started, ComCap will show the name of the individual or
company that registered the software and will run continually.


Distribution
------------

ComCap may be freely distributed via web pages, FTP sites, BBS and
conferencing systems or on CD-ROM in unaltered zip format, but no
charge may be made other than reasonable media or bandwidth cost.  Any
notifications must state that ComCap is shareware until registered
with Magenta Systems Ltd.  Please email Magenta Systems Ltd if you
distribute ComCap in some way, so you can be notified of upgrades or
other important changes.


Copyright Information
---------------------

Copyright Magenta Systems Ltd, England, 2001.

Magenta Systems Ltd
9 Vincent Road
Croydon
CR0 6ED
United Kingdom

Phone 020 8656 3636, International Phone +44 20 8656 3636
Fax 020 8656 8127, International Fax +44 20 8656 8127

Email: comcap@magsys.co.uk
Web: http://www.magsys.co.uk/comcap/
Download: http://www.magsys.co.uk/comcap/comcap.zip

There is also a support conference on the CIX conferencing system,
cix:magsoft.  Information on joining CIX may be found at
http://www.cix.co.uk/.

