Software Recommendations - 1998 Season 1/DNBCD4.iso/develop/NUMEGA/smartchk/DATA1.CAB/Main_Files/Readme.Txt

Text File | 1997-09-25 | 18.1 KB | 449 lines

NuMega SmartCheck
Version 5.0

Read Me

Contents

* YOU GOTTA KNOW...
* Introducing SmartCheck
* Reporting Problems And Suggestions
* Installation Prerequisites
* Installation
* If You Have BoundsChecker on Your System
* Removing An Installation
* Quick Start to Checking Visual Basic Programs
* Frequently Asked Questions
* Known Anomalies
* Technical Notes



YOU GOTTA KNOW...
==================

==> You must compile your Visual Basic program to Native Code using
Visual Basic 5.0 to take full advantage of SmartCheck. Open your
project in Visual Basic 5.0 and select Properties on the Project menu.
Set these options on the Compile tab:

     * Compile to Native Code
     * No Optimization
     * Create Symbolic Debug Info



Introducing SmartCheck
======================

SmartCheck does more than detect errors -- it explains why the errors
occurred, and how to fix them. Try SmartCheck with VBBugBench in the
Examples directory for a quick tour. SmartCheck helps you solve these
common problems for Visual Basic developers:

* Fatal run-time errors are cryptic and hard to solve. SmartCheck
analyzes fatal errors to give details on what went wrong and possible
solutions.

* You can't always see what happened on the way to an error. SmartCheck
logs your program events like form loads, button clicks, and property
changes as they occur.

* You need to use Windows APIs, but it's not always obvious how to do
it from VB. SmartCheck eliminates trial and error debugging by
validating your Windows API usage.

* VB silently changes variables from one value to another, causing
unexpected problems and performance degradation. SmartCheck detects
data value coercions and lets you see the results.

* Passing bad values to built-in VB functions causes VB runtime errors
that only tell you that something is wrong.  SmartCheck tells you which
argument is incorrect and why.

SmartCheck checks third-party components, and includes NuMega's award-
winning error detection for C/C++ and Delphi components.

Refer to Frequently Asked Questions for more information about how
SmartCheck works with Visual Basic.



Reporting Problems and Suggestions
==================================

NuMega Technical Support can assist you with all your technical
problems, from installation to troubleshooting. To contact Technical
Support:

World Wide Web    www.numega.com   Go to Support
E-Mail            [e-mail]
Fax               603-578-8401
Telephone         888 NUMEGA-S (U.S. and Canada)
                  1-603-578-8401 (International)
Telephone support is available as a Priority Support Service from 8:30
AM to 5:30 PM EST, Monday through Friday. Have your product version and
serial number ready.

Problem reports should include:

- System Configuration (CPU, RAM, OS)
- Detailed problem description (include exact error message text)
- How to reproduce problem
- Options used in compiling and linking
- Your SmartCheck error detection settings



Installation Prerequisites
==========================

* PC-compatible Intel 486 system or above
* Microsoft Windows NT 3.51 or 4.0
* Microsoft Windows 95
* RAM: 32 MB minimum
* Disk: 10 MB for full installation

Microsoft Visual Basic 5.0 must be installed prior to SmartCheck if you
want Setup to install Visual Basic IDE integration. VB 5.0 SP1 and SP2
are supported. Beta versions of VB SP2 are not supported. We recommend
updating to VB 5.0 SP2 for the best SmartCheck performance.



Installation
============

To install SmartCheck, run SETUP.EXE, and the setup wizard will guide
you to completion.


If You Have BoundsChecker on Your System
========================================

You can run SmartCheck and any of the BoundsChecker 5.X versions on the
same machine. SmartCheck is installed in a separate directory.

Important: You can run C/C++ modules instrumented with BoundsChecker
FinalCheck (BoundsChecker 5.0 or above, Visual C++ edition only) under
SmartCheck. However, you must relink with a new version of
bcinterf.lib. This file is in the Support directory on the SmartCheck
CD. Copy it to your BoundsChecker installation directory, and relink
your application.



Removing An Installation
========================

To remove this product, run the Remove SmartCheck program item. Files
that were created after installation will not be removed automatically.



Quick Start to Checking Visual Basic Programs
=============================================

Running SmartCheck from Visual Basic 5:
---------------------------------------
1. Select Start with SmartCheck from the Run menu (or press the
SmartCheck toolbar button). SmartCheck reminds you to set your compile
options for native code. Click Project Properties to set these compile
options:

     * Compile to Native Code
     * No Optimization
     * Create Symbolic Debug Info

2. Click Start with SmartCheck to proceed. SmartCheck automatically
compiles and runs your program. Close SmartCheck to return to the IDE.

3. To change your SmartCheck program settings, select SmartCheck
Settings from the Project menu.

Checking Third Party Controls:
------------------------------
By default, SmartCheck only shows you errors for modules that have
source code and debug information available. To check third party
controls, press Advanced on the Program Settings Error Detection tab.
Check "Report errors even if no source code is available."

Looking Under the Hood of Visual Basic:
---------------------------------------
By default, SmartCheck filters out events that you are not aware of
when you write Visual Basic code. To see the system interactions under
your Visual Basic code, select Settings from the Program menu, press
Advanced on the Error Detection tab, and deselect "Suppress system API
and OLE calls." Run your program. When the program results window is
displayed, use Specific Events on the View menu to show additional
details such as API calls from C, C++ and System code, and OLE method
calls. To see everything SmartCheck tracks, select Show All Events from
the View menu.



Frequently Asked Questions
==========================

Why does SmartCheck only work with compiled (non p-code) executables?
Why can't I check my program while running under the Visual Basic
development environment debugger?
--------------------------------------------------------------------
When you build a Visual Basic 5.0 program in native mode with debug
information, SmartCheck can treat the program much like a Visual C++
program.  The debug information allows SmartCheck to correlate program
addresses with a source file and line number.

When built as a p-code executable, there is no debug information to
work from. You can run Visual Basic 5.0 p-code executables under
SmartCheck, and some features will still work.  However, SmartCheck
will not be able to show you source code for errors and events, and
other SmartCheck features are not fully supported for p-code.

When debugging a program in the Visual Basic IDE, the program is
running in p-code mode.  In addition, there are other critical
differences in the way the code is executed.  The result is that
SmartCheck cannot operate on an executable while it is being debugged
from the Visual Basic IDE.


Sometimes SmartCheck shows the Program Error Detected window more than
once for a line of code that causes a single Visual Basic run-time
error. Why?
-------------------------------------------------------------------
When Visual Basic run-time errors occur, SmartCheck may detect a system
error or invalid use of a VB intrinsic function that precedes the run-
time error.


How do I get more information when SmartCheck doesn't diagnose a
problem?
--------------------------------------------------------------------
By default, SmartCheck doesn't show errors occurring in modules that
don't have debug information. This includes the Visual Basic 5.0 run
time library DLL (MSVBVM50.DLL). Oftentimes, additional information
about a bug in your program can be found by observing the invalid
parameters and API failures that occur in MSVBVM50.DLL.

To see these errors, go to Error Detection settings (Program | Settings
| Error Detection), click Advanced and select "Report errors even if no
source code is available".

If you do this, you'll likely see many OLE interface leaks at the end
of your program. Some of these are from the OLE interfaces that
represent Visual Basic controls. Others are from the OLE system DLLs.


I'm getting Visual Basic Runtime Error 80010108 Automation error. When
I press "Explain" I get no help. Any ideas on what I can do to track
down the automation error?
---------------------------------------------------------------------
VB uses the description of "Automation error" when a property put, get,
or method call fails and it does not recognize the failure status. You
may be able to find the failure status name in the C++ header file
winerror.h. For example, 80010108 is RPC_E_DISCONNECTED. Look for this
reference in the Visual C++ documentation on the Windows APIs and COM
to see which APIs return this error. Set up SmartCheck to collect
system information (see Looking Under the Hood of Visual Basic) and
search for calls to any of the routines that return the error.


What are the strange sounding API calls like __vbaChkStk?
-------------------------------------------------------------
If you change the default filtering to show all API and OLE calls,
you'll see many APIs and OLE methods that aren't documented.  For
example:

EVENT_SINK_Release
ThunRTMain
EVENT_SINK_AddRef
__vbaCastObjVar
__vbaChkstk
__vbaExceptHandler
__vbaExitProc
__vbaFreeObj
__vbaFreeObjList
__vbaFreeStr
__vbaFreeStrList
__vbaFreeVar
__vbaGosubFree
__vbaLateIdCallLd
__vbaNew2
__vbaObjSetAddref
__vbaObjSet
__vbaObjVar
__vbaStrCopy
__vbaStrMove
__vbaStrCat
rtcErrObj


These APIs and others like them are the inner workings of the Visual
Basic run time library. SmartCheck logs and uses knowledge of some of
these APIs internally.  However, we're don't document or provide
detailed parameter information for these calls.
----------------------------------------------------------------------



Known Anomalies
===============

1. If the source code shown for an event appears to be off by several
lines, you may be running a project that was initially created in VB4.
The solution is to load the affected form files in VB5, make a change
(e.g., add a blank line, then delete it), and then save the project.
The next time VB5 rebuilds the program, the source lines should be
correct.

2. There is a known bug in Visual Basic 5.0 that can cause an invalid
page fault on closing the IDE due to the way Visual Basic 5.0 destroys
command bars during shut down. If you experience this problem, refer to
Microsoft Knowledge Base Article ID Q167213, for workarounds
(http://www.microsoft.com/kb/articles/q167/2/13.htm). This problem is
corrected in Visual Basic 5.0 SP2.

3. Under certain narrow conditions, programs that uses OLE automation
under Windows 95 will fault when run under SmartCheck. The underlying
problem is that OLE32.DLL expects a thread's "last error" value to be
preserved across a system call (for example, LocalFree). However, the
Win32 documentation explicitly warns against this practice.

Because Windows 95 is inconsistent in its use of the last error
mechanism, SmartCheck sets the last error code to zero by default
before letting an API call proceed. This results in more accurate API
failure diagnosis. SmartCheck's default behavior rarely has problems,
except in cases like mentioned above. The workaround is to go to the
"Program | Settings" dialog, select the "Error Detection" tab, then
click on the "Advanced" button. Deselect the "Reset GetLastError before
each API call" option.

4. If the project group contains an OCX and test program to contain the
OCX, SmartCheck may not compile the projects in the right order so that
the test activates. If this occurs, start SmartCheck as standalone
program, instead of starting SmartCheck from the Visual Basic IDE.

5. Internet Explorer 4 and Outlook Express (part of the IE 4 package)
do not run under SmartCheck. If you need this functionality, please
contact Technical Support and ask to be a beta tester for SmartCheck
service pack.

6. Microsoft Script Debugger causes SmartCheck analysis of Visual Basic
run-time errors to fail. The SmartCheck Program Transcript window
contains the message "Outer event not found". A similar problem may
occur with any multithreaded program where the other threads keep
running (and generating events) during SmartCheck analysis.

7. Abnormal termination of a program compiled with VB 5.0 may cause
instability in SmartCheck and Windows 95. If this occurs, upgrade to
Visual Basic Service Pack 2 (http://www.microsoft.com/vbasic). Until
you upgrade, avoid terminating your program with SmartCheck's End
command. This problem does not occur under Windows NT.

8. If you run a Visual Basic program that contains a form, but no user
code, SmartCheck displays a warning that the executable is compiled in
pcode, even if you have chosen native code in your compile options. You
can ignore the warning, or add a dummy subroutine to your project.

9. When you use File-Send... to send your program results by e-mail,
the recipient must save the results to a file with the extension .sce
in order to view them in SmartCheck.

10. When displaying parameters of type Date, the event pane correctly
decode and shows them (e.g., "1-1-97"). However, the underlying data
type of a Date is a double.  The details pane displays all Date
parameters as double values.

11. If a VB intrinsic function takes an unlimited number of comma
delimited parameters, SmartCheck will only log/show the parameters that
are required. For example: write #1, var1, var2, var3, "abc", var4 -
Only the first argument (the file number --> #1) is required, and so
it's the only one SmartCheck can log.

12. If you remove the start project from the Visual Basic IDE, then
start SmartCheck, the add-in manager is disabled and you can't start
your program again.




Technical Notes
===============

1. SmartCheck detects resource leaks and memory problems in C and C++
components, but these types of problems do not occur in Visual Basic
code. SmartCheck does monitor memory allocation leaks from an OCX or
DLL which is explicitly calling one of the memory allocation APIs.
This also includes GDI resources (brushes, pens, bitmaps) which you or
your OCXs may be using. This version of SmartCheck detects object leaks
in C and C++ components, but does not detect them Visual Basic code.

2. SmartCheck does not track the VB global object or VB debug object.
Some Visual Basic commands such as Load, Unload and Debug.Print are
actually methods of these objects, and are not tracked by this version
of SmartCheck.

3. SmartCheck supports all of the built-in Visual Basic controls, and
all of the controls that come with the Visual Basic 5.0 Enterprise
edition. SmartCheck also has visibility into third-party OCXs that use
IDispatch::Invoke to communicate with Visual Basic. SmartCheck does not
log events fired by controls that use the "dual interface" mechanism.
In addition, SmartCheck doesn't show the interactions from OLE objects
that aren't "controls".  These are objects that you can't drop onto a
form (e.g., "Excel.Worksheet").

4. To turn off reporting of OnError statements, suppress this function
in MSVBVM50.DLL. Open your program in SmartCheck, and select Settings
from the Program menu. Go to the Error Suppression tab, select the
suppression library for your program, and click Add API Function.
Select MSVBVM50.DLL from the Select API dialog, and select OnError from
the list of functions.

5. If you use Data Access Objects, you can make your program run faster
under SmartCheck by enabling the DAO350 Suppression Library. Open your
program in SmartCheck, and select Settings from the Program menu. On
the Error Suppression tab, select the DAO350.DLL suppression library.

6. To turn off checking of Data Access Objects, you must add DAO350.DLL
to your component list, and then deselect it. Open your program in
SmartCheck, and select Settings from the Program menu. Go to the Files
to Check tab, click Add, and enter the full path of DAO350.DLL. You can
use Windows Explorer to find the file, if you do not know where it is
installed on your system. Press Open to add the file, then deselect
DAO350.DLL to disable checking.

7. Programs instrumented with NuMega FailSafe contain error handlers,
so SmartCheck will not notify you when run-time errors occur. To
analyze errors trapped by FailSafe, load your program under SmartCheck,
choose Settings from the Program Menu, and enable Perform Analysis of
Handled Visual Basic Runtime Errors on the Reporting tab. After you run
your program, display Handled Errors (Specific Events on the View
menu).

8. SmartCheck uses a 16k event buffer to determine the cause of a
runtime error. If the source code line that SmartCheck needs to know
about is too far away to be in the buffer, SmartCheck will not analyze
the error.

9. Startup performance and alternate DEFAULT.DAT files
------------------------------------------------------
If your program takes an unusually long time to start under SmartCheck,
you may want to use one of the alternate DEFAULT.DAT files shipped with
SmartCheck. First, backup your existing copy of DEFAULT.DAT by renaming
DEFAULT.DAT (in the SmartCheck 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: By default, SmartCheck installs DEFAULT.MSC



-----------------------------------------------------------------
Copyright 1997 NuMega Technologies, Inc.
Sept. 1997

readmevb.txt