ComCap Data Capture Utility
===========================

Readme for Release 4.5 - 9th September 2009
-------------------------------------------

ComCap is a Windows application designed to capture data received on PC
serial communications ports or using network TCP and UDP streams and
write it to text files.  Captured data is shown in scrolling windows,
and may be printed, written to SQL database tables or echoed to other
PCs using network protocols or serial ports. Captured data can have text
added such as date and time, a serial number and remote IP address. Data
from up to 500 serial ports and network streams can be captured
simultaneously, in separate files, with various file rotation schemes to
start new files periodically. ComCap will capture to files on two
separate disk drives for redundancy and will send email and SMS alerts
if problems occur. ComCap is both a system tray and background service
application that can be set to start automatically when windows starts,
and remain unobtrusive.  When using the background service, captured
data may be still be viewed as it arrives.

ComCap features include:

- Capture from up to 500 serial COM ports, TCP/IP Server, TCP/IP Client
and UDP/IP network protocols simultaneously, with suitable hardware.
Many network appliances output log information, typically using the
UDP/IP 'syslog' protocol, and as telephone switches become network aware
(VoIP) they are offering network logging instead of the serial port.

- Capture from serial device servers that ‘convert’ serial port data to
network protocols, from Lantronix, Lavalink, RE Smith and Tysso eCov for
instance, easing data capture distances.

- Captured data is optionally shown in scrolling windows as it arrives,
and earlier data can be viewed as well.  Coloured tabs indicate which
channels have started capturing data and which are stopped.

- Capture files may be in separate directories for each capture port and
new files may be created daily or multiple per day (at specified times),
weekly (Monday), monthly, hourly, every few minutes, after an inactivity
period, when a new page character is received, or a fixed file name may
be used.  Multiple channels may optionally capture data into a common
file, to reduce the number of separate log files.

- Capture file names (and optionally paths) are automatically generated,
with a file name format customised with date and time in various ways,
numeric or alphabetic.

- Capture data may be written to a database, such as Microsoft SQL
Server or MySQL.  Data formats may be created to identify fields within
each line of data, as fixed width columns, character separated columns
(CSV) or variable named columns.  ComCap examines the SQL tables or
stored procedures for column names and types, and allows mapping of
which field of data is written to which SQL column.  ComCap protects
data that can not be immediately written to the database due to network
problems, and will write it once the database becomes available again.

- ComCap can echo captured data directly to serial communications ports
or parallel ports to drive printers, or echo to the network using UDP/IP
(syslog), TCP/IP Server or TCP/IP Client protocols.  Network echo can be
used to allow capture of the same data to a maximum of five PCs
simultaneously for redundancy or for remote capture with one PC near the
data source echoing data to a centralised location.

- ComCap displays the status of the serial port CTS, DSR and DCD lines,
and if a TCP/IP connection is established is connected, and flashes when
data is received.

- ComCap has options to safeguard captured data, closing the log after
each line to force it to write to disk, or after an inactivity period or
periodically every few seconds or minutes.

- A separate information log file is maintained showing when capture
starts and stops and other ComCap events, it will log capture status
hourly with the number of lines received from each port or stream and to
which logs it is being written. The information log may be sent to a
remote PC using network protocols, perhaps to another copy of ComCap,
to ease central monitoring of remote capture.

- A sound file may be played when each new line of data is captured
(with a minimum gap between sounds, in case of frequent data).

- Raw data may be captured unchanged from the COM port or network
stream, or the data may be cleaned up with non-printing characters,
trailing spaces and blank lines removed.

- When capture is started or stopped, command strings may be optionally
transmitted and periodically repeated, perhaps to trigger a remote
appliance to start or stop. Optionally, extra commands may be transmitted
on demand, perhaps to configure a remote capture device.

- Captured lines may have text added at the start or end, that can
include escape sequences to add a serial number (of specified length),
date and time in various formats, PC name, local or remote IP address.

- A comment may be added manually to any capture channel, using a pop-up
dialog, this is intended to assist in documenting batch captures,
perhaps from laboratory instruments.

- Alerts for problems are presented in a pop-up window and may be sent
by email and by SMS to mobile telephones, using either a GSM modem or
SMS internet gateway. Alerts may also be triggered for phrases in
captured data.

- Data loss checking, to detect if other windows applications caused
ComCap to possibly lose data.  An alert may be triggered if new data is
not captured after a period, configurable by time and day of week, or if
the PC appears to hang for a short period.

- For redundancy, ComCap will capture logs on two different disk drives
at the same time, and continue logging if one of the disk drives is
lost, the drives may be across a network with remote logon details
specified.  ComCap makes multiple attempts to open files, in case of
conflict problems such as backup and protects data until it can be
written to the capture file.  If disk space runs low, ComCap will send
an alert.

- ComCap is usually run as a Windows service that starts immediately the
PC starts without needing a user to log-on.  There is also a system tray
application which can configure, monitor and control the service
displaying data currently being captured, but which will also capture
data if the service is not used.

- Captured data may be filtered, so that lines containing unwanted content
are ignored.

- ComCap is supported on Windows 2000, XP, 2003, Vista, 2008 and 7, both
32-bit and 64-bit editions. The minimum recommended PC is a Pentium III
with 128 Mbytes of memory.  ComCap is normally run with a higher priority
than other windows applications, to ensure stable data capture, although
a dedicated PC is recommended for valuable information.

There are two editions of ComCap version 4:

- ComCap v4 Standard edition is limited to three simultaneous serial or
network channels
- ComCap v4 Unlimited edition has no channel restriction and adds
database and data filtering support

ComCap was originally designed to capture telephone call logging data
from the serial port provided on most telephone switching systems
(PABXs), typically called Call Data Records (CDR).  The saved data may
then be used as input to telephone call management applications that
will cost calls and produce reports on telephone usage or for security
audit purposes.

ComCap is application non-specific and will capture any data that
arrives on a serial port or using network protocols.  It has been used
for a wide variety of purposes, such as logging output from test, alarm
and monitoring equipment and serial printer data (but it can not process
printer control characters).

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 the 'ComGen Data Stream Generator'
application which is designed to generate various types of test streams
using any or all of the PC serial COM ports and potentially dozens of
network streams, UDP Client, TCP Client or TCP Server, and has been used
extensively for testing ComCap capturing multiple channels.  There is
also a small ‘Test RS232 Signals’ utility that may be useful in testing
communication port and cabling problems.  If the requirement is to capture
serial data from another application on the same PC, ComCap includes a
Null_Modem_Emulator_(com0com) from http://com0com.sourceforge.net/ that
installs a linked pair of virtual serial ports, instead of needing to use
a physical pair of COM ports and a null modem cable.


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

ComCap is usually distributed as a ZIP file COMCAP.ZIP, which should
first be unzipped into a temporary folder.

The program SETUP.EXE should then be run to install ComCap.  About 10
Mbytes of disk space is required for applications, help and supporting
files.

If you have received an executable with the name COMCAPS.EXE, this
should be run to install the software.

ComCap is normally installed into the program files directory, in the
comcap sub-directory.  A user with administrative level privileges must
install ComCap, and configure the service version.

ComCap 4 may be accessed by users without administrator access to the
PC, provided file permissions are set-up accordingly for the directories
being used by ComCap.  Note that only administrators may start and stop
Windows services.  If ComCap is configured to run as a service, non-
administrators will be able to run the system tray application and
monitor the service, but not start or stop it (the buttons are hidden).
The PC name, user name and security level are logged on start-up, for
the service it will say: User: SYSTEM (Administrator).

All ComCap settings are stored in files, rather than in the registry, to
ease sharing between users and back-up.  Actual configuration settings
are stored in the Windows common application path, which will usually
be:

C:\Documents and Settings\All Users\Application Data\Magenta-
Systems\ComCap4

The actual files are comcap.config and comcap.current.  The former file
is only updated when configuration changes occur, the latter file
contains dynamic information updated ever few seconds, such as log names
and serial numbers.

User specific information such as windows sizes and positions, fonts,
etc, for the tray application is stored separately for each user:

C:\Documents and Settings\User\Application Data\Magenta-Systems\ComCap4

The actual file is comcap.forms.  If access to directories is blocked,
or they don't exist, then the configuration files are stored in the
ComCap program directory.

On Windows Vista, the base directory is now C:\ProgramData\Users.

ComCap is run from Start, Programs, Magenta Systems, then click ComCap4.
The ComCap icon will appear in the System Tray, which should be clicked
to restore the main application window.  ComCap may be set-up to auto
start each time windows is booted through Common.

Although the ComCap Background Service may be used logged-on to the
‘local system account’, it is better to specify a specific user account
with a password.  This ensures that dates and times in ComCap will be
formatted according to that user’s preferences, rather than the American
default, and allows access to network resources.  Windows Echo printing
is only possible when using the account of a user that has the required
printer installed.

Note that the ComCap PC must be running continually for data to be
captured.  Any power saving features, such as the hard disk being
powered down, should be disabled, and suspending the PC will also stop
anything being captured.


Uninstalling
------------

ComCap may be removed from the Control Panel, Add/Remove Programs, or by
running the program UNINSTAL4.EXE in the installation directory.  The
uninstaller will remove all installed programs and files.  It will not
remove any capture or log files that ComCap has created.


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

This is now in the help file.


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

Until registered, ComCap will only run for one hour 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 as an email attachment,
which should be copied into the ComCap program 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.  The registration
status is shown in the information log on start-up and when capture
starts.  The Order form may also be used to request a temporary one week
license key for extended testing.


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

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/
HTTP Download: http://www.magsys.co.uk/download/software/comcap.zip
FTP Download: ftp://www.magsys.co.uk/software/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/ or http://www.conferencing.co.uk



