Troubleshooting JCapper Installs

General Overview

Initially, I was hoping to avoid having to write this document. I wrote JCapper using Microsoft Visual Basic 6.0 for use on Windows XP operating systems. I thought that Micosoft Windows XP would be backwards compatible with previous versions of Windows. For the most part, this is true. But as some have discovered, this is not always the case. There are simply too many different versions of Windows out there and each has its own versions of separate dependent components. Not all of them are compatible with each other. This effectively means that creating a single version of JCapper that runs right out of the box on any and all Windows platforms no matter how each has been configured, and no matter what OCX and DLL file versions have been installed is an impossibility.

This doesn't mean that if you get an error message during the install process that JCapper won't run on your machine. What it does mean is this: If you do get an error message during a JCapper Install it will take a little extra effort to get JCapper up and running. That's all. In almost all cases it's simply a matter of identifying the missing component or dependency file that is causing the problem.

What follows below are some of the more common problems that users have reported during JCapper installs along with the solution that solved the problem.

The JCapper Diagnostic Tool

The JCapper Diagnostic Tool was designed to provide vital information about various components installed on your machine. The Diagnostic Tool is part of the Demo Version download package and can be run by finding the file named JCapper_DiagTools.exe in your Build Folder and then double clicking it. A screenshot of this process as viewed from Windows Explorer is shown below.

Screenshot above: The user is about to start the JCapper Diagnostics Tool

Screenshot above: The JCapper Diagnostics Tool at startup

The Start Diagnostics Button

When clicked, the Start Diagnostics button causes a series of system tests to take place. This process, from start to finish, only takes a few seconds. A screenshot of the JCapper Diagnostics Tool after all system tests have been run (and passed) appears below:

Screenshot above: The JCapper Diagnostics Tool after all tests have been run (and passed)

Tests performed during this process are listed below:

1. The Windows Version is Read

2. The Windows System Folder is Read

3. The MDAC Version is Read

4. The MDAC Data Provider is Read

5. The JCapper Database is Read using the MDAC Provider

6. The Windows Scripting Host is Tested

7. The Commom Dialog Control is Tested

8. The RichTextBox is Tested

9. The DataGrid Control is Tested

After all tests have been performed, the results of each test are displayed in the TextBox. A JCapper Install where all nine system tests have been passed indicates a successful install. Failure of one or more system tests indicates a failed (or partially failed) install. What follows below are the causes of failure for each test along with the best solution for correcting the problem.

Windows Version Test

This test is performed primarily for informational purposes. JCapper is designed to be compatible with Windows 98 and later. I have even seen it run on Windows 95 operating systems that have been configured correctly.

Windows System Folder Test

This test is performed to alert the user of the location of the Windows System folder. In the event of OCX and DLL conflicts, this is the folder where existing copies of unregistered DLLs and OCX files may likely be found. It is from this folder where OCX and DLL regiistration will, in most cases, be attempted.

ADO Version Test

This test is performed to identify the current MDAC version installed and running on your machine. M.D.A.C. stands for Microsoft Data Access Components. JCapper is MDAC 2.7 Compatible. If a compatible MDAC version has not been installed on your machine, this means that a compatible database driver could not be found. Until this situation is corrected, JCapper will be unable to read its database. You can download and install MDAC 2.71 from Microsoft at the following url:

http://www.microsoft.com/downloads/details.aspx?FamilyID=9ad000f2-cae7-493d-b0f3-ae36c570ade8&DisplayLang=en

MDAC Provider Test

This test is performed to detect a compatible database driver. MDAC Versions 2.6 and later do not include the Jet 4.0 Database Driver required by JCapper and many other programs worlwide. To compensate for this deficiency, Microsoft maintains links where free downloads of the Microsoft Jet 4.0 Database Driver may be obtained. Those users with MDAC 2.6 or 2.7 who don't yet have the Microsoft Jet 4.0 Database Driver installed may download and install the Microsoft Jet 4.0 Database Driver separately from the following url: http://support.microsoft.com/default.aspx?scid=kb;en-us;239114

JCapper Database Read Test

This test is performed to see if an ADO connection can be opened to the JCapper Database. When this test is successful, this means that data can be read from and written to the database. When this test fails, this means that data can not be read from the database.

Cause of problem: Failure of this test is a very strong indicator of one of two things:

1. No Compatible MDAC Version Exists on the machine (ADO Version Test)

or 2. No Compatible Database Driver Exists on this machine (MDAC Provider Test)

In all cases, this situation must be corrected before JCapper will run on this machine. Solution: download and install a compatible MDAC version along with the Microsoft Jet 4.0 Database Driver.

File Scripting Object Test

This test is performed to determine the status of the File Scripting Object (FSO.) When this test is successful, the Windows File Scripting Object is able to read the drive, folder, and file structure on this machine. When this test fails, the Windows File Scripting Object (FSO) is unable to read the drive, folder, or file structure on this machine. The cause of this problem, most common in older versions of Win98, is an unregistered DLL file name: SCRRUN.DLL. Solution: Verify that the file named SCRRUN.DLL is present on the Windows System Folder and use Regsvr32 to register the file.

Windows Scripting Host Test

This test is performed to determine the status of the Windows Scripting Host. The Windows Scripting Host is used in JCapper to control the timing of the start and stop of single events that, collectively, combine to mimic a single process. Examples of this are the events behind the Calculate Races and Build Database buttons of the Main Module. When the Diagnostic Tool indicates success of the Windows Scripting Host Test, logic in JCapper can control the timing of multiple step processes via the Windows Scripting Host. When this test fails, the Windows Scripting Host is not available for control of mustiple step processes. This does not mean that JCapper will not run on this machine. Instead, it means that mutiple step processes such as Calculating Races and Building a Database can not be run as single processes. Instead, the individual tasks that make up these processes must be run separately until the problem has been corrected.

Cause of Problem: Unregistered OCX file named WSHOM.OCX. Solution: Verify that the file named WSHOM.OCX is present on the Windows System Folder and use Regsvr32 to register the file.

Common Dialog Control Test

This test is performed to make sure that the Microsoft Common Dialog Control is available. In JCapper, the Microsoft Common Dialog Control is used to provide the user a dialog box interface for browsing the directory structure when opening files. When this test fails, the Microsoft Common Dialog Control has not been installed on this machine and is not available to JCapper for its needed purpose. Because many of the modules in JCapper use the Microsoft Common Dialog Control, user experience on machines where the Microsoft Common Dialog Control has not been installed will be severely hampered until the problem has been resolved.

Cause of problem: Unregistered OCX file named: COMDLG32.OCX. Solution: Verify that the file named COMDLG32.OCX is present on the Windows System Folder and use Regsvr32 to register the file.

RichTextBox Test

This test is performed to make sure that the Microsoft RichTextBox Control is available. The Microsoft RichTextBox Control is used by JCapper in the Data Window to display results from queries run against the database. When this test succeeds, the Microsoft RichTextBox Control is available to the Data Window for its intended purpose and the Data Window should behave as designed. When this test fails, this means that the Microsoft RichTextBox Control has not been installed on this machine and will not be available to the Data Window. The Data Window will not be useable until this problem has been corrected.

Cause of problem: Unregistered OCX file named: RICHTX32.OCX. Solution: Verify that the file named RICHTX32.OCX is present on the Windows System Folder and use Regsvr32 to register the file.

DataGrid Control Test

This test is performed to make sure that the Microsoft DataGrid Control is available. The Microsoft DataGrid Control is used by JCapper in the Profile Table and System Settings Interfaces to display data from tables in the database. When this test succeeds, the Microsoft DataGrid Control is available to the Profile Table and System Settings Interfaces for its intended purpose and these modules should behave as designed. When this test fails, this means that the Microsoft DataGrid Control has not been installed on this machine and will not be available to the Profile Table and System Settings Interfaces. The Profile Table and System Settings Interfaces will not be useable until this problem has been corrected.

There are three possible causes of this problem. Each should be addressed separately. This is the recommended sequence to correct the problem:

Cause of problem: 1. Unregistered OCX file named: MSDATGRD.OCX. Solution: Verify that the file named MSDATGRD.OCX is present on the Windows System Folder and use Regsvr32 to register the file.

Cause of problem: 2. Unregistered DLL file named: MSVBVM60.DLL. Solution: Verify that the file named MSVBVM60.DLL is present on the Windows System Folder and use Regsvr32 to register the file.

Cause of problem: 3. On machines where a compatible MDAC version has not been installed and/or a Microsoft Jet 4.0 Database Driver has not been installed, the Diagnostics Tool will also indicate failure of the DataGrid Control Test. It will be necessary to first correct download and install a compatible MDAC version and/or a Microsoft Jet 4.0 Database Driver before the DataGrid Control Test will succeed on this machine. Solution: See the sections on the ADO Version and MDAC Provider Tests above.

Using Regsvr32 to Register a File

Dependency files such as OCX files and many DLL files require an entry in the Windows Registry before they become available to the programs that use them. Regsvr32 is a utility that provides the user a quick easy way to register and unregister dependency files. You can run Regsvr32 by clicking the Windows START button followed by clicking RUN and then followed by typing in the command REGSVR32 followed by the full path to the dependency file that you are registering. The RUN textbox off the Windows START button also responds to Drag and Drop. This means that after clicking the Windows START button and clicking RUN and keying REGSVR32 into the open textbox, you can simply drag and drop the dependency file from Windows Explorer rather than typing in the full path to the file. After getting the command line into the textbox, either by typing it out or using drag and drop, simply click OK and Regsvr32 will register the file. Screenshots appear below to illustrate the process of registering a dependency file.

Screenshot above: the user is registering the dependency file c:WINDOWS\system32\wshom.ocx

Using Regsvr32 to Unregister a File

Regsvr32 may also be used to unregister dependency files. The procedure for unregistering a file is exactly the same as registering one with one key difference: the command syntax \u is placed between Regsvr32 and the path to the dependency file. This is illustrated in the screenshot below:

The Exit Button

The JCapper Diagnostics Tool can be closed by clicking the Exit Button.