TCAT C/C++, Ver. 3.1 RELEASE NOTES © Copyright 1999-2006 by Software Research, Inc.

These Release Notes describe changes and additions to TCAT C/C++ made in Ver. 3.1 for Windows 98/NT/2000.

Downloadable Versions

You can download either of two versions of TCAT for C/C++: (1) a DEMO version, which does not require a license key; and (2) the FULL version, which requires a license key.

APG Feature Added

The current releases of TCAT C/C++ Ver. 3.1 and TCAT/Java Ver. 3.1 include the All Paths Generator (APG). APG's aim is to give C-C++ and Java programmers instant information about the relative structural complexity of individual functions and modules/objects.

The new APG feature is accessed from buttons on the TCAT C/C++ or TCAT/Java Digraph toolbar. The data generated always relates to the current function or module and gives the following information:

• Total number of segments (edges).
• Total number of nodes (fixed internal states).
• The cyclomatic complexity of the object.
• The total number of 1-trip paths in the program.
• The shortest and longest paths in the program.
• The highest level of iteration in the program.
• The number of basis paths (those with no iteration).
• The number of iterative paths based on the depth of repetition.

In addition, the APG outputs include a complete enumeration of all of the equivalence classes of program flow, up to a repetition count within the looping structure. Studies have shown a high correlation between the APG-generated total path count and the discovery rate of errors for that particular module.

Click here for more information on APG.

DEMO Version Characteristics

The DEMO version does not require a separate license key; it has a key that is valid for a period up to 10 days [it is refreshed regularly]. The DEMO version has these restrictions:

• Only the first 5 modules [functions] in any build are processed.
• Coverage reports apply only to the modules that are processed.
• Digraphs are available only on modules that are processed.
• Calltree diagrams are available only on modules that are processed.

One complete example, Fib.cpp, is included to illustrate product operation.

Runtime Buffering Options

We supply versions of runtmdll_?.dll that are buffered with various buffer lengths. You have to copy the correct file into your copy of runtmdll.dll to get the right buffering effect. The default version is runtmdll_inf.dll.

The supplied versions buffer at the level of 1, 10, 100, 1000, 10,000, 100,000 and infinite buffering. Buffering is accomplished based on the total number of hits made of segments and/or call-pairs.

Selecting the Correct Version of the TCAT C/C++ Runtime

The various versions of runtime that are available are named as follows:

These runtime modules are installed into the $SR/program directory, where $SR is your TCAT C/C++ installation directory.

Restrictions and Limitations

TCAT C/C++ should process virtually any compilable C or C++ program without difficulty. However, there are some restrictions that users should be aware of.

• Call pairs that arise from a function call made within a function call are not instrumented and are not included in the call pair tree. There are other call pair restrictions that are currently being documented and will be posted shortly.
• Operator overriding is not instrumented. Examples are new, delete, ++, +=, etc.
• exit statements are not recognized as callpairs.
• Functions containing goto statements produce incorrect digraphs.
• Recursive functions, when only calling itself, will not render correctly in the call tree diagrams.
• Instrumenting C++ code under the ANSI C model will not work correctly.
• Forcing ANSI C to compile as C++ will not work.

FACTS ABOUT THIS PRODUCT VERSION

COMPLETE COMMAND LINE DEFINITIONS

Here is the consolidated list of instrumenter command line switches available to the TCAT C/C++ instrumenter. The instrumenter command instruments submitted C or C++ language file(s). The switches shown in the following table may be used to vary the processing and reports generated by the instrumenter.

Note that most of the commands are prefixed with -TCAT. This is done because all other switches are passed in their entirety to the underlying C or C++ compiler. The -TCAT prefix indicates that these switches are for TCAT C/C++ processing.

The command is issued as follows:

ic9 [-TCAT-switches] [other-switches] [file]

where,

[file] specifies the file to be instrumented. There must be exactly one file.

[-TCAT-switches] are switches that are sensed by the instrumenter.

-D and -I switches, which are processed by the instrumenter and then passed to the compiler.

[other-switches] switches are passed to the CL command verbatim.

Note that some of the possible switches, which are not preceded with -TCAT, are allowed to be added as often as needed by most C or C++ compilers.

SELECTIVE INSTRUMENTATION OPTION

You use the -TCAT-SI switch to select the objects you want to instrument. The file contains a list of names, left adjusted, one name per line, of compilable objects that should be instrumented in the current execution of the TCAT instrumenter.

Typically you would use the Selective Instrumentation option when you want to focus attention on only a small number of functions. Objects named in the list are instrumented. All other code is processed normally but is NOT instrumented.

NOTE: If the -TCAT-DI switch and the -TCAT-SI are both present, and if a object name appears in both files, then the name is not instrumented. In other words, de-instrumentation takes precedence.

The names found in the Selective Instrumentation file are processed and matched in the current run of the instrumenter in the following order:

• The name of a file (all of the functions in the file are treated as named).

• A C++ classname (all of the methods in the class are treated as named).

• A C++ method (including all the overloaded methods of the same name) or C function.

• A specific C++ method signature or a C function as it appears in the mdf file.

SELECTIVE DE-INSTRUMENTATION OPTION

You use the -TCAT-DI switch to select the objects you do NOT want to instrument. The file contains a list of names, left adjusted, one name per line, of compilable objects that should NOT be instrumented in the current execution of the TCAT instrumenter.

Typically you would use the Selective De-Instrumentation option when you want to avoid instrumentation of selected objects, probably because they have already been thoroughly tested, or possibly because instrumentation of these objects would increase the test coverage data collection overhead.

All objects seen by the instrumenter and NOT named in the list are instrumented.

NOTE: If the -TCAT-DI switch and the -TCAT-SI are both present, and if a object name appears in both files, then the name is not instrumented. In other words, de-instrumentation takes precedence.

The names found in the Selective De-Instrumentation file are processed and matched in the current run of the instrumenter in the following order:

• The name of a file (all of the functions in the file are treated as named).

• A C++ classname (all of the methods in the class are treated as named).

• A C++ method (including all the overloaded methods of the same name) or C function.

• A specific C++ method signature or a C function as it appears in the mdf file.

SETTING COMPILER OPTIONS FOR THE INSTRUMENTER

The TCAT instrumenter invokes the native compiler after completing its processing steps. To instrument a program correctly the compiler options need to be set correctly.

The compiler options vary with your application and they can be copied directly from Visual C++ settings. To find the compiler options you need select Settings for the project. Then select the appropriate Project Settings. Select C/C++. The options that are needed can be found in the field Project Options.

Two example compiler options settings are listed below.

Example 1

/nologo /MDd /W3 /Gm /GX /Zi /Od /DWIN32 /D_DEBUG /D_WINDOWS /D_AFXDLL /D_MBCS /Fo".\Debug/" /Fd".\Debug/" /FD /c

Scribble Release Version compiler options

/nologo /MD /W3 /GX /O2 /DWIN32 /DNDEBUG /D_WINDOWS /D_AFXDLL /D_MBCS /Fo".\Release/" /Fd".\Release/" /FD /c

The compiler options can also be read from a file using the @OPTIONS <filename> switch described elsewhere in this Release Note.

Example 2

@SRop.txt /Fo".\Debug/" /Fd".\Debug/" /FD /c

This will also read options from a file named "SRop.txt" in the directory when the files are instrumented (e.g. the source dir of scribble.)

The file "SRop.txt" contains:

/nologo /MDd /W3 /Gm /GX /Zi /Od /DWIN32 /D_DEBUG /D_WINDOWS /D_AFXDLL /D_MBCS

PRAGMAS, /M FLAGS PRESERVED

The TCAT C/C++ instrumenter has been changed to preserve any #pragma directives found during the preprocessing and instrumentation step. Such directives will be sent on to the compiler.

In addition, because Visual C++ Studio uses /M flags to define additional macros which will affect decisions taken regarding library linkage, we have modified TCAT C/C++ to be able to pass all /M flags through without modification. (Examples of /M flags include /ML, /MT, /MD, /MLd, /MTd and /MDd).

PROCESSING OF BACKSLASHES

This version of TCAT C/C++ fixes problems that used to occur when backslashes (\'s) were encountered. In some cases these characters were incorrectly processed and instrumentation errors could result.

/ SWITCHES PROCESSED

This version of TCAT C/C++ adds the capability to process compiler flags starting with /. In earlier versions instrumentation options had to start with -. This is done because Microsoft compilers commonly accept either form.

KNOWN LIMITATIONS AND RESTRICTIONS

Certain constraints apply to this version of TCAT C/C++ for Windows.

• The namespace keyword in C++ is not supported.
• We have disabled the -tcat-E (report error log) flag in the new ic9 build. If the test setup you have uses -tcat-E, it will now be simply ignored and will still do the instrumentation properly.
• Call Pair Instrumentation The ic9 instrumenter can instrument multiple function calls in one statement, for example:

  
  	if ( obj_a . mf1 ( )  && obj_a . mf2 ( )  )	
  	i = obj_a . mf1 ( )  + obj_a . mf2 ( ) ;
          j = f () * obj_a . mf1 ( ) ;
     ==>
  	if ( ExpHit(1, 4, (CprHit(1, 1), obj_a . mf1 ( ) ) && (CprHit(1, 2), obj_a . mf2 ( ) ) ) )
  	i = (CprHit(1, 3), obj_a . mf1 ( ) ) + (CprHit(1, 4), obj_a . mf2 ( ) );
  	i = (CprHit(1, 5), f ( ) ) * (CprHit(1, 4), obj_a . mf1 ( ) );
  

  However, the ic9 instrumenter can only instrument one single function call if the calls are nested or chained, as illustrated in this example passage:

  
  	f(f1(),f2());
          f(i, f2());
  	f3(obj_a.mf2());
  	obj_a.mf1().mf2();
  	obj_b.mf3()->mf4();
     ==>
  	(CprHit(1, 19), f ( f1 (), f2 ( ) )  ) ; 
  	(CprHit(1, 20), f ( i, f2 ( ) ) ) ; 
  	(CprHit(1, 21), f3 ( obj_a.mf2 ( ) ) ) ; 
  	(CprHit(1, 22), obj_a . mf1 ( ) . mf2 ( ) ) ; 
  	(CprHit(1, 23), obj_b . mf3 ( ) -> mf4 ( ) );
  

  Note: In the above obj_a, obj_b are objects, mf?() are methods, and f?() are functions.
• A function contains return statements in a infinite loop only can be instrumented, but will cause a compiler error (C2202 Not all control paths return a value), and will fail to create an object file. An example is shown below.

  int f(int a)
  	{
      		while (1) {
  		if (cond1) {
      	    		....
      	    		return a;
          	}
  		else if (cond2)
  	    		return b
  		else {
            		....
          	} 
      		}
  	}

  This problem is specific to Microsoft Visual C++ only.
  If you cannot prevent this type of control structure, add another return statement at the bottom to make the VC compiler happy. However, it may cause compile warning ( for unreachable statement ) with some other compilers.
• Any "inline" functions encountered are accepted but are not instrumented.