File: @(#)r3ctmcREADME.txt	1.1 - 03/18/02

PROGRAM: Recon3 C/C++ Trace Manager Client (r3ctmc)

SYNOPSIS:
The Recon3 C/C++ Trace Manager consists of two parts:
  - The Trace Manager Interface (r3ctmi) consisting of functions which
    are linked into the program that the user wants to trace. Calls
    to these functions cause trace records to be written to shared
    memory.
  - The Trace Manager Client (r3ctmc), a program that runs concurrently
    with the user's program. r3ctmc reads the trace records from
    shared memory and writes them to files (or elsewhere). r3ctmc
    also provides extensive facilities to control tracing on the
    fly, including turning tracing on and off selectively, changing
    the data content of each trace record, switching output from
    one file to another, etc.

This README file refers primarily to the Trace Manager Client r3ctmc.

USAGE:
Normally two r3ctmc processes are run concurrently in two different
command line windows (e.g. a Windows "command prompt" window or
a Sun shelltool window). The user's instrumented program may be
running in yet a third window.

The first r3ctmc process reads trace records from shared memory,
performs any appropriate consolidation or processing, and writes them 
to a trace file or other destination. To start this process give
the command:
   r3ctmc start [configurationFile]

The r3ctmc process will continue running until stopped by the second
r3ctmc process. Tracing is controlled by a set of configuration values whose
defaults are specified at compile time in the file r3ctminf.h. The
optional configurationFile may contain r3ctmc commands to change
these defaults.

The second r3ctmc process is used to give commands to control or
stop tracing. Such commands may be given any time after the first
process has had an opportunity to create the shared memory used
for communication (typically less than one second).

For example, suppose the user wants to run two tests of his program
and get a trace file for each. Here is a possible sequence
of trace manager commands:

   FIRST WINDOW         | SECOND WINDOW          | THIRD WINDOW
 -----------------------|------------------------|-----------------
 r3ctmc start           |                        |
                        |                        | <start user's program>
                        | r3ctmc mode c          |
                        | r3ctmc newtrace t1.r3t |
                        |                        | <enter data for test 1>
                        | r3ctmc newtrace t2.r3t |
                        |                        | <enter data for test 2>
 <msg tracing stopped>  | r3ctmc stop            | 
                        |                        | <stop user's program>
 -----------------------|------------------------|-----------------

In this sequence, the r3ctmc was started in the first window, and
then the user's program started in the second window. The trace mode
was set to "count" so that a count is kept of the number of times
each event occurs. The "newtrace" command gives the trace file
name to use for each test. Finally the "stop" command is used
to stop the first r3ctmc process.

The complete list of r3ctmc commands is given in Table 3 of the
"Recon3 C/C++ Trace Manager - SRS", file r3ctsrs.htm.

KNOWN BUGS OR LIMITATIONS:

Occasionally when running r3ctmc the shared memory gets into an
inconsistent state which causes the program to stall when
attempting to stop and which does not allow r3ctmc to
be started again. On Unix, to free up the shared memory you
may use the following command:
  ipcs - gives the status of all interprocess communications
to identify the shared memory or semaphore causing the problem, and
then use one or more of:
  ipcrm -m <shared memory id> - removes a segment of shared memory
  ipcrm -s <semaphore id>     - remove a semaphore
to fix the problem.

SEE ALSO:

  r3ctmiREADME.txt - README file for the Recon3 C/C++ Trace Manager Interface

The following documentation used by the Recon3 development team
provides detailed specifications which may be useful:

  r3uarch.htm - The Architecture of Recon3.
     Provides an overall description of the toolset, its design
     criteria, the relationships between the different tools,
     the different architectures (Basic, Extended, etc.), the
     different kinds of program events which may be traced,
     trace record and file formats in different modes, etc.

  r3csrs.htm - Recon Instrumentor for C/C++ - SRS.
     Provides a detailed Software Requirements Specification (SRS) for
     the Recon3 C/C++ instrumentor (r3cinst).

  r3ctsrs.htm - Recon3 C/C++ Trace Manager - SRS
     Provides a detailed Software Requirements Specification (SRS) for
     the Recon3 C/C++ trace manager (r3ctmc).