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

Readme for Release 2.4 - 22nd March 2002
----------------------------------------

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 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 Windows 98 and later 32-bit versions
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 RTS and DTR lines when capture is enabled and use RTS for flow
control.  ComCap never transmits any data and does not support software
flow control (Xon/Xoff).

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).  Generally, only ASCII
data is saved to the capture file, although there is a raw option. 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. But ComCap may be used to capture any ASCII
data and is used for a variety of purposes, such as logging output from
test and monitoring equipment and serial printer data.

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 98 such as a low end Pentium with 16 Mbytes of memory (which
could be dedicated for data capture).  Although ComCap will probably run
on Windows 95, it is no longer officially supported because the Delphi
compiler is not longer supported on that OS.


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 capture log window, one for each installed COM port (whether
or nor free).  Clicking on a tab changes the capture log window and
general informational messages about which channels are being captured
and to which log files. A splitter between the windows allows the widths
of each to be adjusted.

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 capture log files may be opened daily, weekly or monthly, after a
specified period of minutes, after a period during which no data is
captured or whenever a form feed symbol is found in the captured data.
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.

The Common Settings windows includes 'Auto Capture' which allows capture
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. Other
settings allow the inactivity period before which the capture log is
temporarily closed to be specified, and allows the log to be periodically
flushed to disk.

In the main window, two buttons allow capture for all 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 Close button hides the window.  The File menu
includes 'Stop and Exit' which actually terminates ComCap.

Data is captured into automatically named files, optionally in a different
directory for each channel. If a new file is being created monthly, weekly
or once a day at 00:00, the file name format is 'captureX-yyyymmdd.txt'
where X is the channel number (1 to 8) and yyyymmdd is the date, ie
'capture1-20020312.txt'.  if daily log files are created at times other
than 00:00 or if there are multiple files per day, the time is added in
the format hhmmss, ie 'capture1-20020312-151302.txt'.

There is also an information log file containing historic information on
when capture was started and stopped, and which capture log files have
been written.  This is a monthly file, kept in a specified directory with
the file name format 'info-yyyy-mm.txt', ie 'info-2002-03.txt'.


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 some errors.
More detailed information about ComCap activities ares saved to a monthly
info log with a file name format 'info-yyyy-mm.txt', ie 'info-2002-03.txt'.

If the service is set-up to logon to the local system account, ComCap has
some limitations: network resources can be not accessed (so the capture
and log files must be on the local PC), no printing is available nor are
regional settings so dates will be formatted in American style.  If the
service is set to logon to a specified user account, all functionality
becomes available.

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.4, 22nd March 2002

1 - Fixed a problem introduced in ComCap Release 2.0 relating to capture
and display of large amounts of data. This problem did not effect the
service version which never displays data. To avoid excessive memory use,
the main log window showing captured data periodically has old lines of
data removed.  This became more complicated in 2,0 when multiple capture
channels were supported since the log file itself had to be loaded when
changing display channel and old lines then removed before being
displayed.  On slow PCs log reloading could cause capture problems. This
has all been optimised with 2.4, so the log is not loaded from disk unless
the displayed channel is changed, and even then it now only loads part of
the log file, which is rather more efficient.  The size of the download
data buffer for each channel has been doubled to about 62,000 bytes which
is about one minute of data at 9.600 bits/sec, after which hardware flow
control should stop new data being received.  Note that the higher the
number log lines displayed, the more likely there are to be problems on
slow PCs, a maximum of 1,000 lines is recommended, with remove 500 lines
on overflow.

2 - It is now possible to capture log files free of any extra ComCap
comments.  There is a new information log window beside the main data
capture window.  A splitter allows the widths of the two windows to be
adjusted.  All ComCap informational messages are now displayed in this
new window and written to a new monthly log file, kept in a directory
specified in Common Settings with the file name format 'info-yyyy-mm.txt',
ie 'info-2002-03.txt'.  The new log also contains the names of all
capture log files, with their sizes and number of lines added and file
size when closed.  Common Settings includes new options 'Info Messages on
Capture Log' which effectively allows backward compatibility with earlier
releases, and 'Log Diagnostic Messages' which should not be needed unless
there are logging problems.

3 - Added a new Common Setting 'Flush capture logs to disk periodically'
which specifies that capture logs will be closed every so many minutes
flushing them to disk.  If the PC subsequently locks up (as an old P133
running Windows 98 did during testing), less information will now be
lost.  Note this setting is separate to the inactivity delay that closes
the log file, it's designed for when data is arriving continually and
there is no inactivity.

4 - Added the option to create a new log each time the 'Inactivity Delay'
on new data expires.  Note a new log is also created after the new
'Flush capture logs to disk periodically' expires so care may be needed
choosing the two settings.

5 - Added the ability to optionally create a new capture log file if the
captured data contains a form feed or new page control character.  Note
the new file will have a date/time file name, so there is a restriction
of one new page per second.  It may be necessary to reduce bits/sec if
this becomes an issue so each page takes at least one second.

6 - A lot of users have been frustrated during set-up of ComCap where the
data indicator shows something arriving, but nothing is ever displayed.
This usually happened because ComCap buffers each line of data before
displaying it, waiting for a carriage return control character to signify
end of line.  If the bits/sec were incorrect, CR was never seen and
nothing was displayed.  A maximum of 253 characters are now buffered, so
random data (due to incorrect bits/sec) should also appear.  The CR check
may also have caused problems with file created by UNIX systems, which
typically only have line feed characters, so a new option 'Line Feed end
of Line' has been added for each channel. This might solve a couple of
cases where no data has been seen.  Normal ASCII files have both CR and
LF, so either option will work.

7 - If the directories for info or capture logs are not specified or are
not available, ComCap has always placed the logs in the program directory
instead.  It now also logs the original error in the new info log.

8 - The main capture log window is now only updated while visible.  If
the ComCap window is minimised or closed, data is still captured to file
but not to the non-displayed log window.  This avoids needing to clear
the log window periodically as it overflows.  When the ComCap window is
opened, the log window is refresh from disk.

9 - Added an option 'Auto Scroll' to right click menu in the main capture
window.  This stop ComCap forcing scrolling to the end of the window
before adding a new line of captured data, but the behaviour will depend
upon the version of Windows.  It does not seem to have any effect on W2K,
but with Windows 98 the log window will flicker less.

10 - Improved the behaviour when ComCap is run unregistered.  A warning in
info log window shows that capture will cease after 15 minutes, and when
that happens the Start button disappears, rather than ComCap closing down
completely, so the captured data can still be seen.

11 - Successfully tested ComCap with a Lava Computer DSerial PCI card
which adds an extra two serial ports, COM4 and COM5 on my test PC (COM3
is an USB serial port).  Lava also sells four and eight port serial
cards, which should also work with ComCap, http://www,lavalink.com/.

12 - This release has been tested over several days with 20 to 30 megs of
CDRs being captured daily, on both Windows 98 and 2000.  The Windows 2000
PC were doing a dozen other tasks while capturing data, peak memory usage
was only 4.5 Mbytes, CPU usage was 1% over 40 hours (23 minutes) on a
PIII/850. The capture data source was the Plessey Call Simulator that
creates CDRs for three types of large switch (BTS 7#2, iSDX, Ericsson),
it can be downloaded from: http://www.magsys.co.uk/comcap/callsim.zip
Note the file is not indexed on the web page.  The Call Simulator outputs
data from a serial port, so a null modem cable will be needed to feed the
ComCap port.

13 - Apologies for the quality of the documentation for ComCap, it is
getting more complicated with each release and this readme is no longer
really suitable.  A proper help file will be added real soon.


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
parameters 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 2000

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 capture
is automatically stopped.  It will be necessary to restart ComCap to
continue capture.  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, 2002.

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://net.nextra.co.uk/conferencing/ or http://www.conferencing.co.uk

