Total C++ 2/TOTALCTWO.iso/bcheck/readme.txt

Text File | 1997-02-28 | 26KB | 554 lines

BoundsChecker 5.0
Visual C++ Edition

ReadMe File

Contents:

* What's New in BoundsChecker 5.0
* Reporting Problems And Suggestions
* Installation Prerequisites
* Installation
* If You Have A Previous Version Of BoundsChecker On Your System
* Removing An Installation
* Behavior of "BoundsChecker Rebuild All" in Visual C++ 4.x
* Configuration Considerations for Visual C++ 4.x and 5.0
* Known Anomalies
* Technical Notes
* Using BoundsChecker With Visual Test 4.0
* Using BoundsChecker With Symantec 7.0
* Using BoundsChecker With Watcom 10.5



What's New in BoundsChecker 5.0 Visual C++ Edition
--------------------------------------------------

--- New FinalCheck Technology ---
One of the most significant features in BoundsChecker 5.0 is completely new
instrumentation using FinalCheck (TM), the advanced error
detection technology.


--- Improved User Interface ---
BoundsChecker now displays both errors and events in the new Program Results
window. This window is intended to help you focus on the most
pertinent error information and easily change the information
displayed. Also, you can now view program errors and events
dynamically as your program runs.

The Settings dialog has been revised to better define default error
detection settings and provide easier customization.


Reporting Problems and Suggestions
----------------------------------

Technical Support is available by e-mail at [e-mail] or by
calling Technical Support at 603-578-8100. You can also fax us at 603-
578-8401 (attention: Technical Support).

Problem reports should include:

- System Configuration (CPU, RAM, OS, compiler, IDE)
- Detailed problem description (include exact error message text)
- How to reproduce problem
- Whether you are compiling from IDE or command line
- Options used in compiling and linking
- Your error detection mode (Normal, Maximum, or Custom)

Installation Prerequisites
--------------------------

* PC-compatible Intel 486 system or above
* Microsoft Windows NT 3.51 or 4.0
* Microsoft Windows 95
* RAM: 32 MB minimum, 48 MB recommended
* Disk: 12 MB for full installation
* FinalCheck requires Microsoft Visual C++ 4.0 or later
* IDE integration requires Microsoft Visual C++ 4.0 or later (Microsoft
Developer Studio)
* Complete debugger integration (Smart Debugging) requires Microsoft
Visual C++ 4.0 or later (Microsoft Developer Studio)


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

To install BoundsChecker, insert the CD into your CD-ROM drive. Close
any programs that may be running. With Windows 95 or Windows NT 4.0, use
the Add/Remove Programs Control Panel. With Windows NT 3.51, use Program
Manager or File Manager to run setup.exe.

Visual C++ users: BoundsChecker expects that you have already set up the
command-line environment required by Visual C++. Normally this is done
when you install Visual C++. You need these environment strings
(assuming your Visual C++ installation is c:\msvc):

    include=c:\msvc\include;c:\msvc\mfc\include
    init=c:\msvc
    lib=c:\msvc\lib;c:\msvc\mfc\lib
    path=c:\msvc\bin

Because of problems with Visual C++ and long file names, be sure to
install BoundsChecker using short (8.3) names for install directories,
if you plan on using the IDE integration or Smart Debugging.

The BoundsChecker installation directory needs to be in your path if you
plan to compile and link from the DOS command-line.


If You Have A Previous Version Of BoundsChecker On Your System
--------------------------------------------------------------

BoundsChecker32/NT or BoundsChecker for Windows 95: BCHK32NT and/or
BCHK32C must not appear in the path before the BoundsChecker directory.
If they do, BoundsChecker may crash or fail to detect errors because it
is trying to load obsolete libraries from the earlier product.



Removing An Installation
------------------------

To remove this product, run the Remove BoundsChecker program item.

"Remove" performs these steps:

- Deletes BoundsChecker files from the BoundsChecker installation
directory and sub-directories.
- Deletes Visual C++ and Visual Test support files.
- Removes BoundsChecker registry entries.
- Removes BoundsChecker-specific Visual C++ and Visual Test registry
entries.
- Deletes the BoundsChecker 5 program folder and items.

NOTES:
- Files that were created after installation (such as Help system GID files)
will not be removed automatically.


Behavior of "BoundsChecker Rebuild All" in Visual C++ 4.x
---------------------------------------------------------

If you use BoundsChecker 5.0 Visual C++ Edition with the Microsoft Visual
C++ 4.x Developer Studio, you may find that the Tools menu item "BoundsChecker
Rebuild All" (and its associated shortcut on the BoundsChecker toolbar) does
not always behave as you expect. Specifically, if you are working with an
existing project, and your current project configuration (e.g., "Win32 Debug")
has been recently built such that all of its OBJ files are up to date in
relation to their source files, "BoundsChecker Rebuild All" will not be able
to force the files to rebuild for FinalCheck.

This happens because BoundsChecker's FinalCheck builds are accomplished by
running NMAKE on the makefile generated by Developer Studio.  "Rebuild All"
works by calling NMAKE with the "/A" command-line switch, which is supposed
to force the project to rebuild, regardless of the relative dates of the files.
However, most Developer Studio makefiles use the compiler switch "/Gm," which
means "minimal rebuild."  The minimal rebuild switch causes the compiler to do
its own dependency checking, independently of NMAKE.  The result is that NMAKE
calls CL for each source file, but CL compares the source file and its dependent
header files to the OBJ file, sees that the OBJ is newer and decides not to
recompile that file, printing out the message "No significant changes found,
skipping."  In other words, the compiler switch overrides the NMAKE switch.

There are several ways to work around this problem:

--- Create a new project configuration for BoundsChecker FinalCheck builds,
which will make a separate set of OBJ files.  This is the recommended method,
and is described both in the online help and in the manual.

--- Before you select "Rebuild All," delete the OBJ files for the project.
The easiest way to do this from within Developer Studio is to go to the Files
tab of the Project window, right-click on the project name, and select
"Delete intermediate files" from the menu.

--- Disable the "minimal rebuild" option.  In the Project | Settings dialog,
go to the C++ tab and remove the check next to the "Minimal rebuild" option.

Please note that this behavior does not occur with Visual C++ 5.0, because
BoundsChecker uses a different method of integration in that version of
Developer Studio.


Configuration Considerations for Visual C++ 4.x and 5.0
-------------------------------------------------------

If you will be installing both versions 4.x and 5.0 of Visual C++, there are
some configuration details that you should consider, as they will affect not
only BoundsChecker's ability to build programs properly under VC++ 4.x,
but your ability in general to build any project correctly from the command
line.

Both versions of the VC++ are capable of adding several items to your
environment, in particular to the PATH, LIB, and INCLUDE variables.  A common
scenario will be a system on which VC++ 4.x is already installed, to which
VC++ 5.0 is then added.  If during both installations you allow the setup
procedure to "Register Environment Variables," you will end up with:

INCLUDE=c:\msdev\include;c:\msdev\mfc\include
LIB=c:\msdev\lib;c:\msdev\mfc\lib
PATH=c:\msdev\bin

After installing VC++ 5.0, your environment will look something like this:

INCLUDE=c:\DevStudio\vc\include;c:\DevStudio\vc\mfc\include;c:\msdev\include;c:\msdev\mfc\include
LIB= c:\DevStudio\vc\lib;c:\DevStudio\vc\mfc\lib;c:\msdev\lib;c:\msdev\mfc\lib
PATH=c:\DevStudio\vc\bin;c:\DevStudio\SharedIDE\bin;c:\msdev\bin

As you can see, the VC++ 5.0 directories will override the VC++ 4.x
directories.  The consequence of this is that any command-line build, either
with NMAKE or CL, will be performed with VC++ 5.0, whether you want that
or not.  This will cause problems also for any BoundsChecker FinalCheck build
done in the VC++ 4.x Developer Studio, for the same reason.

Therefore, we recommend that if you will be using both VC++ versions on the
same machine, you should not allow the setup program to add anything to your
environment  Microsoft provides a very reasonable alternative in the form
of a batch file called VCVARS32.BAT that will set up all the necessary
environment variables for a command line build in the current DOS session.
This file is usually contained in the \MSDEV\BIN directory (for VC++ 4.x)
or in the \DEVSTUDIO\VC\BIN directory (for VC++ 5.0).  Simply run the
appropriate version of this batch file in a new DOS session to initialize
the environment for the version of the compiler with which you will be
working.

If you want to use Developer Studio, you should then start it from that DOS
session using the command "start msdev."  Developer Studio will inherit the
setting you just established.



Known Anomalies
---------------

--- BoundsChecker inadvertently reports an access violation error in the
Program Error Detected window if the application writes to its resource data.
This error report typically occurs once for each page of virtual memory
containing written resource data.

--- Due to a known problem in Windows95, it is possible to crash the
operating system when halting a program from the BoundsChecker Program
Error Detected window. Windows NT handles this situation properly,
however, Windows95 does not. The problem occurs when an application
calls ExitProcess (which BoundsChecker does to halt the application) and
one of the DLLs used by the application brings up a message box during
its DLL_PROCESS_DETACH processing sequence. To prevent this error
condition, avoid making any calls to MessageBox during your
DLL_PROCESS_DETACH processing.

--- Due to SmartHeap memory manager usage, it is possible, however
unlikely, that BoundsChecker will report false overruns of dynamically
allocated memory. In order to use BoundsChecker with the memory manager
provided with SmartHeap/HeapAgent, you must add the following lines to
the DEFAULT.DAT file, located in the BoundsChecker DATA directory (these
are the functions that overload malloc, calloc, realloc and free):
              _MEM_malloc           ID  011
              _MEM_calloc           ID  015
              _MEM_free             ID  019
              _MEM_realloc          ID  022

Once you have edited DEFAULT.DAT, BoundsChecker will keep track of the
heap correctly; both HeapAgent and BoundsChecker will be able to report
errors to you.

--- BoundsChecker reports leakage when processing DLL_PROCESS_DETACH.
Since the order in which modules are unloaded cannot be controlled,
erroneous leakage reports can result when a DLL unloads after
BoundsChecker. This can occur when the following conditions are met:
- user DLL allocates memory in DLL_PROCESS_ATTACH
- user DLL frees the allocated memory in DLL_PROCESS_DETACH
- BoundsChecker unloads before the user DLL

--- If NMCL cannot create the debug directory (because it already
exists) and causes nmake to fail, add the /N switch as the first
argument (before the existing /f switch) to the NMCL command in the
registry. The following keys are affected (Visual C++ 4.x):
HKEY_CURRENT_USER/Software/Microsoft/Developer/BoundsChecker
  Argument5 = '/N /f "$(WkspDir)\$(WkspName).mak" /t "%e" /c "%c" /B -4'
HKEY_CURRENT_USER/Software/Microsoft/Developer/BoundsChecker
  Argument6 = '/N /f "$(WkspDir)\$(WkspName).mak" /t "%e" /c "%c" /R -4'
(This problem is known to affect 4DOS/NT users.)

--- Visual C++ IDE command line settings will override BoundsChecker
specific command line settings. If your project requires command line
settings, make sure they are set correctly in both Visual C++ and
BoundsChecker.

--- BoundsChecker does not automatically update all dependencies if your
.MAK file contains a different source path than the actual location of
your files. To correct this, make sure to update all dependencies before
running BoundsChecker Build or Rebuild All. (Visual C++ Edition Only)

--- BoundsChecker will use your IDE Options settings for include file
and library directories. If you change these settings, you must close
the IDE and reopen it to force BoundsChecker to pick up the changes.

--- Running an instrumented program under the Visual C++ debugger may
cause the message 'Target out of date' to appear. This is normal Visual
C++ behavior. Visual C++ considers a target to be out of date if the
project has never been built with CL from the IDE (for example, if you
normally build with CL from the DOS command line). The message also
occurs after changing any of the project settings, and starting the
debugger before rebuilding with CL from the IDE. The message is
harmless, and you do not have to rebuild your project with BoundsChecker
before debugging.

--- If you re-install Visual C++, the registry options used for
BoundsChecker IDE integration are lost. To restore them, run
BoundsChecker Setup, select Custom installation, and check only Visual
C++ support.

--- Program settings are keyed to an EXE name. If you are building a DLL
in the Visual C++ IDE, set the project "Executable for Debug Sessions"
to the fully qualified EXE name before setting BoundsChecker Error
Detection Settings. The EXE and the DLL will share the same settings.

--- In some instances, BoundsChecker may compile a file that you do not
think is in your project. Due to the way Visual C++ writes its
automatically generated MAK files, there is a rare instance in which
running NMAKE on the project MAK file compiles different files than
selecting the Build command from the IDE. The problem occurs when the
project contains a .cpp file (example test.cpp) and there is a junk file
in the same directory named test.c. The IDE build will build test.cpp,
but BoundsChecker will build test.c. A similar problem happens if a
project contains test.cxx, and there are junk files named test.cpp or
test.c. The solution is to remove or delete the junk file. This occurs
because BoundsChecker uses NMAKE to build, while the IDE uses its own
internal make procedure.

--- Under Windows 95, you must specify command.com as your COMSPEC if
you perform BoundsChecker Build or Rebuild All under the Visual C++ IDE.
Using 4DOS version 5.0f will result in a compilation error because 4DOS
does not pass all command line arguments to the BoundsChecker build
procedure.

--- In some rare instances, BoundsChecker may falsely report an
incorrect number of arguments for sprintf functions for optimized code.
Use Suppress to prevent a false report on later runs.

--- If you perform a BoundsChecker Rebuild All on your project in the
Microsoft Visual C++ IDE after having done a normal build, and the
project is configured to build a browser database, BSCMAKE will fail.
This is because VC++ fails to release the BSC file open after building
the project, and the BoundsChecker build is thus unable to access the
file.  The workaround is to quit the IDE and restart it.

--- BoundsChecker may incorrectly report several memory and resource
leaks from dynamically loaded Delphi 2.X DLLs, because these memory and
resource allocations are implicitly freed. If you do not wish to be
informed of these leaks, the recommended work around is to run
BoundsChecker in Custom error detection mode, and make sure to disable
the 'Report errors even if no source code is available' setting. This
issue will be addressed in a future release.

--- Certain OLE interface methods, as implemented in some existing
applications, will return the error code E_NOTIMPL ("not implemented"),
although the OLE documentation indicates that this is not an acceptable
return code for these methods.  This is the list of methods for which
this sometimes occurs:

    IOleInPlaceObject::ContextSensitiveHelp
    IOleInPlaceObject::ReactivateAndUndo
    IOleObject::GetMoniker
    IViewObject2::Freeze

Note that BoundsChecker will notify you of this error even if you are
running in Quick or Normal mode, or have unchecked the 'Check for OLE
"not implemented" return code errors' option in Custom mode.  This is
because we base our OLE error checking on documented OLE behavior.

--- OLE errors reported in OLE system DLLs:  In certain circumstances
BoundsChecker can report errors on OLE interface method calls that are
made inside system OLE DLLs such as OLE32.DLL and OLEAUT32.DLL.  These
errors are only reported in normal and maximum mode and are always OLE
return failure errors.  The reason these errors are reported is because
an interface, that was created and hooked by BoundsChecker, was passed
to an API function and that API is using it.  Since the interface was
created in the user's program, we still monitor it for error detection
even if it is inside a system DLL.




Technical Notes
---------------

--- Preventing Leaks in DLL Startup Code: BoundsChecker will detect
leaks from the initialization code of a DLL that you cannot correct. To
prevent these reports, name your DLL entry point DllMain. BoundsChecker
recognizes DllMain, and knows not to check the startup code.

--- Debugging an NT service: Using the Registry Editor, go to
HKEY_LOCAL_MACHINE\SOFTWARE\MICROSOFT\WINDOWS NT\CurrentVersion\. Create
a new key called "Image File Execution Options". Under this key, create
a subkey with the name of your service. For example, MYSERV.EXE. To this
subkey, add a REG_SZ value called Debugger. For the Debugger value,
enter the path to the BoundsChecker program (e.g.,
C:\BChecker\BC.EXE). Exit the Registry Editor. Start up the Control
Panel, and double-click on the 'Services' icon. Highlight your service
to be checked. Click the 'Startup...' button. In the dialog box that
appears, select the 'Allow Service to Interact with Desktop' button.
Click OK. If you don't do these steps, BoundsChecker will run, but will
be invisible. At the main Control Panel | Services dialog, start your
service. BoundsChecker should appear, with the service already opened.
At this point, you can set any desired options and then run the service
via BoundsChecker. If your service starts automatically during NT's
bootup, use the Control Panel to set the 'Interact with desktop'
attribute, and then restart the machine. BoundsChecker should start
automatically when the service is started. (IMPORTANT NOTE: This only
works with Windows NT 3.51, or later versions!)

--- Automatically invoking BoundsChecker when a program is executed
(Windows NT only): You would use this if the program is invoked by some
other process, and you want to run BoundsChecker on this program. NOTE:
This works only on Windows NT, and will not work on Windows 95. As
always, be careful whenever you edit the registry. Using REGEDT32:

1 Select the key
  HKEY_LOCAL_MACHINE\Software\Microsoft\Windows NT\CurrentVersion

2 Under the selected key, add the following KEY, if it does not exist:
  Image File Execution Options

3 Under "Image File Execution Options" add this KEY:
  FOO.EXE
  (where FOO.EXE is the name of the program you want to test.)

4 Under the "FOO.EXE" key add a new VALUE:
  Value name: Debugger
  Data type:  REG_SZ
  String:     c:\Bchecker\bc.exe
  (Where the string value is the full pathname for BoundsChecker on your
machine.)

--- Startup performance and alternate DEFAULT.DAT files: If your program
takes an unusually long time to start under BoundsChecker, you may want
to use one of the alternate DEFAULT.DAT files shipped with
BoundsChecker. First, backup your existing copy of DEFAULT.DAT by
renaming DEFAULT.DAT (in the BoundsChecker DATA directory) to
DEFAULT.BAK. Then, copy one of the alternate DEFAULT.xxx files to
DEFAULT.DAT:
Microsoft C/C++ (includes Symantec)   DEFAULT.MSC
Borland C/C++ (include Watcom)        DEFAULT.BOR
Borland Object Pascal (Delphi 2.X)     DEFAULT.DPH
All of the above                      DEFAULT.ALL
NOTE: This is done automatically for you by the Setup program, based on
your compiler choice.

IMPORTANT: If you need to change or add support for additional compilers
after installing BoundsChecker, make sure to run Setup to install the
appropriate DEFAULT.DAT file (or copy the appropriate file/files as
described above).


--- First chance exceptions when using Smart Debugging: When using Smart
Debugging, you may notice additional first chance exception messages in
the debugger output tab. These messages are generated by the Visual C++
debugger whenever an exception occurs and are harmless if there is an
exception handler in the application to handle it. If there is no
exception handler, it becomes a fatal second chance exception and the
application terminates. BoundsChecker calls IsBadReadPtr() frequently
during its normal operation. If a bad pointer is passed to this
function, it will cause this message in the debugger's output tab. Since
the function handles the exception, it is a non-fatal notification that
can be safely ignored. When using Smart Debugging, NuMega recommends
that you use the Exceptions dialog from the Developer Studio Debug menu
to set the Access Violation exception to "Stop if not handled" (this is
the default setting).

--- Heap exceptions when running under a debugger in Windows NT 3.51:
When an application is debugged, the Windows NT memory management APIs
throw exceptions when bad parameters are detected. BoundsChecker uses
some of these APIs to perform parameter validation, which can cause
these exceptions to be thrown. At the request of many beta testers, we
now disable the Windows NT debug heap during Smart Debugging. If you
wish to re-enable the debug heap when using Smart Debugging, change the
following registry value to 0.

    HKEY_CURRENT_USER
        \Software
            \Microsoft
                \Developer
                    \BoundsChecker
                        \DisableHeapException




Using BoundsChecker With Visual Test 4.0
----------------------------------------

When using the BoundsChecker with Visual Test, make sure that your
scripts wait for BoundsChecker to completely finish so all text is
properly sent to your BoundsCheckerNotification handler.  If the script
ends before BoundsChecker is finished, some error notifications might
not get through.  This is especially true with memory and resource leaks
since the application being tested must completely end before they can
be reported.

Here are two methods to make sure your script does not end prematurely:

1 In the test script, following the commands to close the application
being tested, add a long enough sleep statement to allow BoundsChecker
to get all the information over to the notification handler (You may
need to use a value greater than the 60 used here).
...
WSysMenu ( 0 )
WMenuSelect ( "&Close" )
Sleep ( 60 )
End
...

2 If the script is run interactively, a Pause statement will display a
message box and wait until the OK button is pressed before the script
will continue.


Using BoundsChecker With Symantec 7.0
-------------------------------------

The Symantec C\C++ compiler uses the Microsoft CodeView debug format, so
no special steps need to be taken during compile and link except to
include debug information. This can be accomplished by compiling and
linking with the following switches:

Compile: -g
Link: /CO

As with any debugger, BoundsChecker works best if optimizations are
disabled, which can be done by compiling with the -od compiler switch.

The Symantec C\C++ compiler also uses the MFC class library. This is the
same MFC as is shipped with the Microsoft Visual C++ compiler.
BoundsChecker works the same with both the Microsoft and the Symantec
compilers.


Using BoundsChecker With Watcom 10.5
------------------------------------

The Watcom 10.5 compiler is capable of producing CodeView compatible
debug information and thus is compatible with BoundsChecker.
BoundsChecker will not run correctly with versions of Watcom prior to
10.5. To prepare your Watcom program for use with BoundsChecker:

1 Compile with the following switches:
-hc - Set output debug format - CodeView.
-d3 - Full symbolic debugging with unreferenced type names.
-od - disable optimizations
-3s or -4s or -5s - add stack calling conventions

2 Link
Include the line:  DEBUG CODEVIEW

3 CVPACK the executable
After building the .EXE file, run CVPACK, found in the Watcom BINNT
directory, on the .EXE.


-----------------------------------------------------------------
Copyright 1997 NuMega Technologies, Inc.
03/03/97