userman.html

这是一个C程序分析工具

        -v = Very verbose mode
        -s = Output is the sets each branch is in instead 
             of the annotated source listing
</PRE>

<P>If the &quot;-s&quot; option is used, the analysis program writes a
set report (See SECTION&nbsp;7.2 for more information on the Set Output
Report) to standard output with a list of the executed branches in all
files of the source program. Each branch is tagged with the sets it belongs
to in the &quot;functionality view&quot; of the software. This option is
intended primarily for statistical analysis of the software system. See 
Section 7.2 for more information on the Set Reports. </P>

<P><A NAME="r2end"></A><B>R2END</B>
- This program deletes the <CODE>r2tmp.dat</CODE> file. </P>

<P><A NAME="r2inst"></A><B>R2INST</B>
- This program instruments the target program source code files inserting
statements that write to the trace file as each branch is executed.  
The switch options are not case sensitive. </P>

<PRE><CODE>
     r2inst source dest [-V (or -v)[level]] [-E (or -e)]

</CODE></PRE>
where
<PRE>
        source - C/C++ language source file to be instrumented.

        dest - destination file for the instrumented source.

        -V or -v (verbose) - write progress messages to the screen.
          level - {'A'|'F'|'S'|'T'} each level adds info to previous level:
             A = Admin, writes only high level messages (file names, etc).
             F = Function names.
             S = Statements instrumented.
             T = Tokens recognized.

        -E or -e (entry) - instrument function entry points.
         
</PRE>

<P><A NAME="r2protos"></A><B>R2PROTOS.C</B>
- <CODE>r2protos.c</CODE> is a C file that must be compiled with the user's target program.
It contains instrumentation routines required by the instrumented source
code. </P>

<P><A NAME="r2test"></A><B>R2TEST
</B>- This program is run before each test case. It places the trace file
path name and the trace comment in a temporary file named <CODE>r2tmp.dat</CODE> in
the current working directory. When the instrumented target program executes,
it reads this file and uses its contents to set the trace file pathname.
If it cannot find <CODE>r2tmp.dat</CODE>, it will name the file <A HREF="#unknown"><CODE>unknown.r2t</CODE></A>.
The option switches are not case sensitive and there must be a space between the 
option switch and the option value.</P>

<PRE><CODE>
    r2test -T/-t &lt;trace file name&gt; [-C/-c &quot;trace comment&quot;]</TT> </CODE>
</PRE>
where
<PRE>
        -T/-t  - use a specific trace file
              &lt;trace file name&gt; - valid file name (We recommend
                 using a &quot;.r2t&quot; extension)
        -C/-c  - Inset a comment
              &quot;trace comment&quot; - A comment including the &quot;s
                 inserted as the first line of a trace file.
</PRE>
<P>The optional comment will become the first line of the trace file to
remind you which test case produced the file. </P>

<P><B>7.2 Recon Files</B> </P>

<P>This section gives the format of all of the RECON files, including those
that the user needs to create. All RECON files are ASCII text files (i.e.
each line ends with a carriage return/line feed combination in MS-DOS or
a carriage return in UNIX). </P>

<P><B>Annotated
Listing Outputs</B> - These files are ASCII formatted sequential files
with <TT>.out</TT> extensions. They consist of the original source code
(before <A HREF="#instrumentation">instrumentation</A>) with analysis information
records inserted where branches implementing the feature may be located.
These records are inserted directly before the point at which the original
code was instrumented (i.e. before the if statements, etc.). The analysis
information records will have the following format: </P>

<DL>
<P><BR>
Cols. 1 - 5 <BR>
</P>

<DD>These characters delineate the analysis information record. They are
specified by the user and are found in record 2 of the list file. </DD>
</DL>

<DL>
<P>Col. 6 <BR>
</P>

<DD>Blank space for readability </DD>
</DL>

<DL>
<P>Cols. 7 - 8 <BR>
</P>

<DD>Branch probability (in percentage) - this field is left blank when
using <A HREF="#deterministic">deterministic</A> method of analysis </DD>
</DL>

<DL>
<P>Cols. 9 - end <BR>
</P>

<DD>Branch Value (T, F, TF, or ordinal value for switch). Additional ordinal
value - this field is repeated as many times as needed. A space shall separate
each value. </DD>
</DL>

<P>The annotated listing output files will be in the analysis output directory
specified by the -p variable when running <CODE>r2analyz</CODE>. The annotated listings
will be named the same as the original source files except with a <TT>.out</TT>
extension. </P>

<P>An example of an annotated listing output file is shown in the document
<B><A HREF="overview.html">RECON - OVERVIEW</A></B>. </P>

<P><A NAME="r2anl"></A><B>List
File - Analysis phase specification</B> - The list file contains the information
necessary to control the analysis phase. The analysis program, <CODE>r2analyz</CODE>,
reads the test case trace files included in list file and keeps two counts
for each branch that is mentioned in any file: a count of the number of
test cases &quot;with&quot; the feature that executed the branch and a
count of the number of test cases &quot;total&quot; that executed the branch.
</P>

<P>You may select either a &quot;deterministic&quot; or a &quot;probabilistic&quot;
analysis. In a deterministic analysis, RECON will tell you about branches
that are only executed when the feature is present and never otherwise.
They are likely to be involved in implementing the feature in some way.
</P>

<P>In a probabilistic analysis, you set a probabilistic threshold given
as a percentage. RECON will tell you about branches for which: </P>

<DL>
<DD>threshold&lt;(test cases &quot;with&quot;) x 100 / (test cases &quot;total&quot;)
</DD>
</DL>

<P>This formula can be interpreted as a conditional probability that the
feature and the branch appear together. </P>

<DL>
<P><BR>
Record 1 <BR>
</P>

<DD>In column 1, an <em>uppercase</em> letter to specify the type of analysis, either &quot;P&quot; for
<A HREF="#probabilistic">probabilistic</A> or &quot;D&quot; for <A HREF="#deterministic">deterministic</A>.
</DD>
</DL>

<DL>
<P>Record 2 <BR>
</P>

<DD>In columns 1 to 5, up to five characters that will be used to mark
the branches of interest in the annotated listing output. </DD>
</DL>

<DL>
<P>Record 3 <BR>
</P>

<DD>In columns 1 to 3, the probabilistic threshold, expressed as an integer
(1 to 100). This record needs to be present, but the value is disregarded
if deterministic analysis is selected. </DD>
</DL>

<DL>
<P>Subsequent Records <BR>
</P>

<DD>The remaining records are in pairs, one pair for each test case that
should be analyzed. The first record of each pair contains the full path
name of the test case trace file. The second record of each pair contains,
in column 1, an <EM>uppercase</EM> &quot;Y&quot; if the test case exhibits the feature or an
<EM>uppercase</EM> &quot;N&quot; if it does not.</DD>
</DL>

<P>An example list file could be <CODE>multiply.lst</CODE> that contains: </P>

<PRE>
    D
    &gt;&gt;&gt;&gt;&gt;
    95
    /usr/cs/&lt;usrname&gt;/proj/out/add.r2t
    N
    /usr/cs/&lt;usrname&gt;/proj/out/divide.r2t
    N
    /usr/cs/&lt;usrname&gt;/proj/out/subtract.r2t
    N
    /usr/cs/&lt;usrname&gt;/proj/out/multiply.r2t
    Y
</PRE>

<P><A NAME="r2tmp"></A><B>Temporary Data File</B>
- File <code>r2tmp.dat</code> contains the trace file path name and the trace comment as
a result of running R2TEST. </P>

<P><B>Set
Output Report</B> - This file is produced by the analysis phase when the
&quot;-s&quot; option is specified when executing <code>r2analyz</code>. There is
one line for each branch in the source program that was executed in any
test case. The line shows the sets containing the branch in the functionality
view of software, described in the report <B>Augmenting Program Understanding
Strategies with Test Case Based Methods</B>, by M. Scully, SERC-TR-68-F,
Software Engineering Research Center, University of Florida, Gainesville,
Florida 32611, July 1993. </P>

<P>Each output line has the following blank separated fields: </P>

<P>- source file index (3 digits, with leading zeros) </P>

<P>- line number of the if, switch, while, etc. in the source file that
created the branch. (5 digit integer with leading zeros) </P>

<P>- type of condition, which is &quot;T&quot; or &quot;F&quot; for if,
and while statements and &quot;S&quot; for switch statements </P>

<P>- if the type of condition field was &quot;S&quot;, then the next field
is the switch value (sign plus 9 digit integer, with leading zeros) </P>

<P>- set fields. There will be one field for each set the branch is in,
coded as follows: </P>
<BLOCKQUOTE>
<P>&quot;#IC#&quot; - is in ICOMPS(f)<BR>
&quot;#II#&quot; - is in IICOMPS(f)<BR>
&quot;#CC#&quot; - is in CCOMPS<BR>
&quot;#RC#&quot; - is in RCOMPS(f)<BR>
&quot;#SH#&quot; - is in SHARED(f)<BR>
&quot;#UC#&quot; - is in UCOMPS(f)<BR>
</BLOCKQUOTE>

<P>Three typical output lines could be: </P>

<BLOCKQUOTE>
<P>003 00015 T #IC# #II# #CC#<BR>
003 00042 S -000000001 #IC# #II# #UC#<BR>
002 00123 F <BR>
</P>
</BLOCKQUOTE>

<P>Note that this format is designed to be easily sorted. Also the branches
in any particular set can be extracted using grep. </P>

<P><B>Trace
file</B> - This file is produced at run time when the instrumented code
is executed with a specific test case. The name of this file is determined
by the user on the command line when <CODE>r2test</CODE> is run. The following is a
description of the format of this file. </P>

<DL>
<P>Record 1 <BR>
</P>

<DD>Contains the trace comment specified by the user when <CODE>r2test</CODE> was run
just before test case execution. (If no comment was specified, the record
contains &quot;#NO COMMENT.&quot;) </DD>
</DL>

<DL>
<P>Remaining records<BR>
</P>

<DD>One record for each time a branch is executed. (If the user specified
the <A HREF="#mintrace">Minimum Trace</A> option during compilation, duplicate
records will be eliminated.) Each record contains space separated fields
with the first field containing a T for true, F for false, E for function entry, 
S for switch or a # for comment. When a # is used in the first field, the remaining
inputs on the line are ignored. If a T, F or S is in the first field, the
next field contains the line number for the control statement (&quot;if&quot;,
&quot;while&quot;, &quot;switch&quot;, etc.) that created the branch. For
a switch, the next field contains the value of the switch. Then for the
true, false or switch the next field is the string length of the original
source code file name. The last field contains the original source code
file name. An example of this is shown in section 3.6. </DD>
</DL>

<P><A NAME="unknown"></A><B>Default Trace File</B>
- This file is produced if <CODE>r2test</CODE> cannot find <CODE>r2tmp.dat</CODE>. The default
trace file name is <STRONG><CODE>unknown.r2t</CODE></STRONG>.</P>

<P><A NAME="glossary"></A><B>8. Glossary</B>
</P>

<P><A NAME="deterministic"></A><B>Deterministic analysis </B>- This option
tells the user the branches that are only executed when the feature is
used and never otherwise. They are the most likely to be involved in implementing
the feature. </P>

<P><B>Functionality</B> - A feature of a software system that may be used
or not used as determined by the user. </P>

<P><A NAME="instrumentation"></A><B>Instrumentation</B> - C language constructs
added to the original source code that will provide information to RECON
as to which components were executed during a test case execution. </P>

<P><A NAME="mintrace"></A><B>Minimum trace </B>- As each decision in the
instrumented source program is executed, <CODE>r2protos.c</CODE> stores the information
in memory. When the program terminates, one line is written to the trace
file for each branch (true or false or value of the switch variable) of
each decision that has been executed. This option greatly reduces the size
of the trace file and may also execute faster. It does require more memory
and the user must ensure that the program terminates by calling <CODE>&quot;exit()&quot;</CODE>
somewhere in the instrumented code. The <CODE>exit()</CODE> statement is instrumented
to make sure that the trace data are written to the trace file. </P>

<P><A NAME="normtrace"></A><B>Normal trace</B> - As each decision in the
instrumented source program is executed, one line is written to the trace
file. This option can create a very large trace file (but requires little
memory) since each decision will produce one line for each time it is executed.
<B>This is the default option.</B> </P>

<P><A NAME="probabilistic"></A><B>Probabilistic analysis</B> - The user
specifies a probabilistic threshold given as a percentage. The formula
can be interpreted as a conditional probability that the feature and the
branch appear together. Branches that tend to appear in test cases that
exhibit a feature can be viewed as &quot;good indicators&quot; of the feature.
</P>

<P><A NAME="target"></A><B>Target program</B> - The program that the user
wants to investigate using RECON. RECON helps locate where features of
the user's target program are located. </P>

<P>
<HR><I>End of Document</I> </P>

</BODY>
</HTML>