Compatibility Administrator Overview

The Compatibility Administrator tool is useful for resolving application compatibility issues during a deployment of Windows XP and the Windows .NET Server family. It is also very helpful after deployment, while supporting applications in the new operating system environment. Specifically, Compatibility Administrator can assist by:

  • Testing applications with compatibility modes
  • Testing applications with individual compatibility fixes
  • Creating custom compatibility modes
  • Creating custom compatibility databases
  • Installing custom compatibility databases on the local computer
  • Searching for installed fixes
  • Querying local compatibility databases

The topics covered in this help file include the following:

Working with Databases

  • Adding a compatibility fix
  • Adding an AppHelp
  • Creating a custom compatibility mode
  • Issues with Application Fixes and 16-bit Programs
  • Install/Uninstall a compatibility database
  • Disabling fixes
  • Enabling fixes

Searching for Fixes

Using the Query Tool

Using the LUA Wizard

NOTE: Some features of the Compatibility Administrator tool are considered to be of use in only limited circumstances. Because of this, those functions are “hidden”. To access all of the advanced functions of Compatibility Administrator, such as special use compatibility fixes, start the program with the following command line:

Ca.exe /x

This switch will launch the Compatibility Administrator program in Expert mode.


Working with Databases

Windows XP provides compatibility information for older applications with known compatibility issues. The Compatibility Administrator tool enables you to create custom compatibility databases for applications that are not on this list of applications with known issues.

Before you can distribute compatibility fix information to other computers in your environment, you must create a custom .SDB compatibility database containing that information. This section will help you to accomplish the following tasks:

  • Adding a compatibility fix
  • Adding an AppHelp
  • Creating a custom compatibility mode
  • Issues with Application Fixes and 16-bit Programs
  • Install/Uninstall a compatibility database
  • Disabling fixes
  • Enabling fixes


Adding a Compatibility Fix

Compatibility Administrator uses the term Fix to describe the combination of compatibility information being added to a custom database for a specific application. This can be a single compatibility fix, or an entire compatibility mode, or any combinations. The limiting factor when adding a Fix to a custom database is that it only applies to a single application.

To add a Fix to a custom database, use these steps:

  1. Highlight the database you are working with under the Working Databases node in the Database pane of Compatibility Administrator.
  2. Click the Fix button on the toolbar. This will open the Create a new Application Fix dialog.
  3. Enter the required information for the name of the application, vendor name, and browse for the path to the executable file for the program. Click Next.
  4. Select a compatibility mode to apply to the application. You can use the Test Run button to try each mode or combination of modes until you determine the modes that solve the issue. When you are ready to move on, click Next.
  5. If you did not find a mode that will solve the compatibility issue, or if you want to fine-tune the compatibility support, select individual compatibility fixes to apply. On this wizard page as well, you can press the Test Run button to try out your selections. If you need to display only the selected compatibility fixes, click the Show Selected button. When you have finished, click Next.
  6. On the Select Matching Information page of the wizard, Compatibility Administrator will display all of the matching information it has detected for the application. It is better to use a limited list of matching information to cut down on file size for the database, yet at the same time you must keep enough matching information so that Windows XP can uniquely identify the application. If you want to add another file to the list of matching information, use the Add File button to browse for the file.
  7. Click Finish to save the custom fix in the database.


Adding an AppHelp

In Compatibility Administrator, an AppHelp is a text message that is displayed when the related application is launched. AppHelps can be blocking, where the message is displayed and the application is blocked from running, or non-blocking where the message is displayed but the program still executes.

You should use a blocking AppHelp message when the related application absolutely cannot run on Windows XP in its current form. This gives you the opportunity to define a specific URL on the Web where the user can download an updated driver or other patch to resolve the issue. If you use AppHelps this way, be sure to define the file matching information to uniquely identify the problematic version of the application, but not to block the corrected version of the program.

Non-blocking AppHelp messages are useful to give the user information regarding their application. This can be a useful method of reminding users about security issues, or changes in the location of resources on the network. This might also be used to inform the user that a new version of the application is available.

To add an AppHelp to a custom database, use the following steps:

  1. In Compatibility Administrator, highlight the database to which you want to add the AppHelp.
  2. Select New – AppHelp Message from the Database menu. This will open the Create a Custom AppHelp Message Wizard.
  3. On the first page of the wizard, supply the name of the application and the vendor name. Click Browse to identify the path and executable target for the AppHelp. Click Next.
  4. On the Matching Information page of the wizard you must define the file matching information that Windows XP will use to uniquely identify the application. The wizard will already have selected some matching information, and by default will include the program being. You can use this information or select as many other files as you feel necessary to uniquely identify the application. The Auto-generate button will use proximity to find files that are located near the application being fixed. When you invoke Auto-generate, only files in the directory in which the application resides or its sub-directories will be used. When you are satisfied with your selections, click Next.
  5. On the Enter Message Type page, you must determine which type of AppHelp you are applying. Select the (default) first option to apply an AppHelp that will simply display a message when the application is launched. The second option will prevent the application from being run at all. Click Next.
  6. The Enter Message Information page enables you to provide both the message text for the AppHelp and a URL for a Web site that can provide more details about the problem and even file updates to resolve the issue. The message text can either be plain text or in HTML.

The Test Run button can be used to test the application and the AppHelp message. Click Finished when you are satisfied with the AppHelp.


Creating a Custom Compatibility Mode

The compatibility modes provided with Windows XP contain groups of compatibility fixes that have been found to resolve common compatibility issues. As you apply compatibility fixes to your applications, you may discover certain groupings of fixes that are useful. The Compatibility Administrator tool can assemble these fixes into a custom compatibility mode that can then be reused in other databases.

To create a custom compatibility mode, please use the following steps:

  1. Highlight the custom database to which you want to add a custom compatibility mode and select Create New – Compatibility Mode from the Database menu. Alternatively, you can highlight the database and click the Mode button on the toolbar.
  2. Enter a name for the new compatibility mode.
  3. Select the compatibility fixes to include in this mode. You can select multiple fixes by pressing and holding the Ctrl key while clicking the fixes. Click the right arrow button (>) to add the selected fixes to the mode.
  4. Click OK to save the selections to the custom database as a new compatibility mode.

Another useful way to add multiple compatibility fixes is to copy the settings from an existing compatibility mode and then customize any additional compatibility fixes that need to be added or removed. Use the Copy Mode button to select the existing compatibility mode to use as the template for your new mode.


Copying Fixes between Databases

Version 3 of the Compatibility Administrator tool presents the ability to cut, copy, and paste compatibility fixes between different custom databases. This technique can be used with fixes, modes, and AppHelp messages.

To copy a component from one custom database to another, both databases must appear in the left pane of the Compatibility Administrator tool. To copy a fix from one custom database to another use the following steps:

  1. Open the custom database containing the fix you want to copy.
  2. Right click the fix to be copied and select Copy from the context menu.
  3. Right click the destination database and select Paste from the context menu.

Compatibility fixes for an application may depend upon compatibility modes or other compatibility fixes elsewhere in the custom database. When you copy a compatibility fix that depends on other fixes or modes, Compatibility Administrator will also copy those other elements transparently.

Compatibility information must be stored by unique name in order to be tracked correctly by the operating system. When you copy a compatibility fix from one database to another database the name must be altered to preserve uniqueness. Compatibility Administrator will perform this rename transparently. If you want to view the information that has been altered, select Events from the View menu to open the Events pane. The Events pane will display each individual operation that was performed on the compatibility fixes in the copy operation.


Issues with Application Fixes and 16

Issues with Application Fixes and 16-bit Programs

The application compatibility technologies in Windows XP were designed to work with all 32-bit applications. Unfortunately, there are issues which prevent the deployment of these technologies for 16-bit applications. Normally this would be relatively unimportant due to the overwhelming prevalence of 32-bit applications for Windows.

However, there is one particular instance where 16-bit programs are very common, and that is for setup programs in applications that must install on multiple hardware platforms. This was a common occurrence in Windows NT where the application must support not only the Intel x86 platform, but also the PowerPC, MIPS, and Alpha platforms as well. In these applications, the setup program would be written as a 16-bit “stub” program whose only job was to detect the hardware platform and launch the appropriate native installation program.

Because these 16-bit setup programs were so common for Windows NT applications, the application compatibility technologies in Windows XP have been designed to propagate from the 16-bit stub program to any 32-bit program that it launches. Because of this propagation, compatibility fixes and modes can be successfully applied to 16-bit stub programs and carry through to support the 32-bit applications launched by them.


Installing

Installing & Uninstalling Databases

Custom databases must be installed before they will have any effect in Windows XP.To install a custom database in Compatibility Administrator, use the following steps:

  1. Using Compatibility Administrator, highlight the custom database you want to install in the left pane.
  2. Select Install from the File menu. Alternatively, you can right click the custom database and select Install from the context menu.

NOTE: If you install a new database containing entries for an application that has already had compatibility fixes applied, the previous entries for the application may not be applied.

Once a database is installed it will be checked for compatibility information every time the related application is launched. The relationship between the database file and the application (or applications) is stored in the Registry. Windows XP checks the Registry for the presence of compatibility fix information and if found will retrieve the fix information from the custom database file.

When a custom database file is no longer necessary, either because the applications are no longer in use or because the vendor has provided a patch that resolves the compatibility issues, the custom database can be removed using Compatibility Administrator. To remove a custom database, use these steps:

  1. Using Compatibility Administrator, highlight the custom database you want to remove in the left pane.
  2. Select Uninstall from the File menu. Alternatively, you can right click the custom database and select Uninstall from the context menu.

See the help topic on Deploying Custom Databases for an explanation of how to install and uninstall custom databases on remote computers.


Disabling Compatibility Fixes

Custom compatibility databases can conceivably become quite complex as you add fixes for the multiple applications found within your environment. Over time you may encounter situations where it is necessary to temporarily disable a particular fix within your database. One such scenario is when you want to test the effectiveness of a software update for an application. If the software vendor releases a patch for the issues your compatibility fix addresses, you would want to test the effectiveness of the patch by temporarily disabling the compatibility fix, and then testing the application.

The ability to disable compatibility fixes within a database saves you the time and effort of removing the fix and then adding it again later when it is needed. A disabled fix will not be used by Windows XP, but will remain in the database until it is removed permanently or is re-enabled.

To disable a fix within a database, use the following steps:

  1. Expand the custom database to show the fixes in the left pane of the Compatibility Administrator.
  2. Highlight the fix you wish to disable. The contents of the fix will be displayed in the right pane.
  3. Click the application name in the right pane to highlight it.
  4. Select Disable Entry from the Database menu to disable the fix. Alternatively, you can right click the application name in the right pane and select Disable Entry from the context menu.

This technique can also be used to disable a fix in the system database if you find a reason to do so.

NOTE: When disabling an entry it will remain disabled even if you do not save the database file.


Enabling Disabled Compatibility Fixes

It can be useful to disable a fix within a custom database for troubleshooting or testing purposes. Once the testing is completed, you can enable the disabled fixes by using the following steps:

  1. Expand the custom database to show the fixes in the left pane of the Compatibility Administrator.
  2. Highlight the fix you wish to enable. The contents of the fix will be displayed in the right pane.
  3. Click the application name in the right pane to highlight it.
  4. Select Enable Entry from the Database menu to enable the fix. Alternatively, you can right click the application name in the right pane and select Enable Entry from the context menu.


Searching for Fixes

Te Search function in the Compatibility Administrator tool can be used to locate the executable files in a particular location that have compatibility fixes, modes, or AppHelp messages applied to them. This can be very useful when trying to identify the applications present that use compatibility fixes, or the fixes being applied to a given program.

To search for the fixes being applied to a given executable, use these steps:

  1. Click the Search button to open the Search dialog. Alternatively, select Search for Fixes from the Search menu.
  2. Use the Browse button to identify the path to search for affected executables.
  3. Select the compatibility options to search for. The available options are Entries with Compatibility Fixes, Entries with Compatibility Modes, and Entries with AppHelp. Selecting both Compatibility Fixes and Compatibility Modes check box tells Compatibility Administrator to look for entries that have either Compatibility Fixes or Compatibility Modes
  4. Click the Find Now button to begin the search operation. The results will be displayed in the bottom pane of the Search dialog.
  5. Double clicking on a search result will take you the appropriate entry in the contents pane. You can also execute the result found by right clicking on the result and selecting “Run Program”


Finding User Applied Modes

Windows XP provides compatibility modes through the user interface (UI) in the form of the Compatibility Wizard and the Compatibility tab of an executable’s Properties sheets. Any compatibility settings made through either of these methods will be stored on a per-user basis and thus will affect only the user that made the settings.

NOTE: Due to the order of precedence in applying compatibility fixes the fixes designated by a user through the GUI (such as by using the Application Compatibility Wizard) will be applied before any fixes contained within a custom database. This may cause the fixes in a custom database to be ignored for that user.

The Compatibility Administrator tool will display all of the per-user compatibility settings stored on the local computer. This will aid in identifying compatibility modes for a locally installed application so that these settings can be used to create a new custom database for distribution to other users.


Using the Query Tool

As custom compatibility databases become more and more complex, the ability to effectively locate individual compatibility fixes takes on greater meaning. The Query function within the Compatibility Administrator offers sophisticated search capabilities designed to help you locate fixes within all of the installed databases on the local computer.

You can open the Query Compatibility Databases dialog by clicking the Query button on the toolbar. Alternatively, you can select Query Database from the Search menu. The Query Compatibility Databases dialog has three tabs:

  • Program Properties
  • Fix Properties
  • Advanced.


Program Properties Tab

This tab is used to locate entries in compatibility databases on the local computer. This can include searching through the system databases, custom databases, installed databases, or all databases.

The main function of the Query Compatibility Databases dialog is to provide a simple interface to create SQL queries that will search the compatibility databases. Using SQL to directly query the databases can give you greater flexibility to perform complex searches.

To use the Program Properties tab to query for an entry in a custom database, use these steps:

  1. Select Custom Databases from the Look in drop-down list box to restrict the query to the custom databases on the local computer.
  2. In Search for the Program Name(s), type the name of the entry you are searching for. This should be the same as the name displayed under the Applications node of the custom database in the left pane of Compatibility Administrator.
  3. Click the Find Now button to execute the search. The results are displayed in the lower pane of the Query dialog.

As an alternative to querying for the application name, you can use the Search for the File text box to enter the file name associated with the application. This should be the actual executable name that was designated when the compatibility fix was added to the database.

The checkboxes on the Program Properties tab will add AND clauses to the SQL query that is generated. Leaving the three boxes unchecked will perform the equivalent of an OR query using the three options, that is to say the query will return any entry with the application (or file) name where there is a compatibility mode OR a compatibility fix OR an Application Help present.

To find an entry that contains a compatibility mode, check the checkbox for Compatibility Modes in addition to the other query information, but leave the other checkboxes empty. If you check the checkbox for Compatibility Modes and the checkbox for Compatibility Fixes, and the entry you want contain a mode, but no compatibility fixes, the Query tool will not return any results.


Fix Properties Tab

This tab is provided to enable you to query compatibility databases for any entries using particular compatibility modes or fixes. To query the compatibility databases on the local computer for all “fixed” programs using a particular compatibility mode, use these steps:

  1. Select the database to query from the Look in drop-down list box.
  2. Type the name of the compatibility mode you want to query for in the Search for programs fixed using text box.
  3. Click the Search in Compatibility Modes checkbox.
  4. Click the Find Now button to execute the query. The results will be displayed in the lower pane of the dialog.

Use the same procedure when querying for the programs fixed using specific compatibility fixes with the exception that you would check the Search in Compatibility Fixes checkbox and leave the Search in Compatibility Modes checkbox unchecked.

NOTE: The name entered in the Search for programs fixed using text box must match the type of compatibility fix or mode you are querying for. For instance, entering the name of a compatibility fix and check the compatibility mode checkbox will not return any results.


Advanced Tab

The Advanced tab enables you to more directly control the SQL query that is being used to search the databases. This can be a very powerful tool for retrieving complex queries directly from the compatibility databases.

CAUTION: Effective use of the Advanced tab is based upon your familiarity with the Structure Query Language (SQL). Without a fundamental understanding of SQL the functions on this tab will be very confusing.

The SELECT text box will contain the clauses of the SELECT portion of your SQL query. The WHERE text box will contain the clauses used for the WHERE portion of the query. To add a clause to the SELECT text box, double click the desired value in the Select clauses list box and it will be added to the SELECT text box automatically. The same technique will work for the WHERE clauses. Alternatively, you can type the information directly into the text boxes if you prefer.

For example, to construct a query to locate all information regarding an application by the name of MyApp, use these steps:

  1. Select the databases to query from the Look in drop-down list box.
  2. Double click the asterisk (*) in the Select clauses list box. This will instruct the query to return all columns of information for the application.
  3. Double click the APP_NAME clause in the Where clauses list box.
  4. Type MyApp after the equal in the WHERE text box, enclosed in double quotes. The value you assign to the WHERE clause must be enclosed in double quotes for the WHERE clause to be well-formed.
  5. Click the Find Now button to execute the query. The generated SQL statement will be displayed in a message box. Click OK to continue the query. The results will be displayed in the lower pane.

The steps in the example (assuming that the option to query all databases was selected) will generate the following SQL statement:

SELECT * FROM SYSTEM_DB, INSTALLED_DB, CUSTOM_DB WHERE APP_NAME = “MyApp”

The number and content of the columns returned in the results pane will depend entirely upon the SELECT portion of the SQL statement.


Using the LUA Wizard

The limited user access (LUA) feature in Windows XP causes a great many compatibility issues for applications written for Windows 95/98/Me. In Windows 95/98/Me there is no concept of user-based security; every user has full access to the Registry and the Program Files folder. This meant that applications written for these environments never needed any special methods for storing user information in a secure fashion. These applications will typically be denied access to HKEY_LOCAL_MACHINE and to the Program Files folder and may well fail to run because of this.

Windows XP denies limited user accounts access to these areas of the operating system as a means to protect the stability of the system. Many viruses introduced in the Windows environment have exploited the lack of permissions on the Registry and the Program Files folder to propagate themselves. Windows XP improves security by denying access to these areas by default. Compatibility Administrator can help you to fine tune the LUA settings applied to an application enable the program to run correctly while still maintaining full security.

To use the Customize LUA Wizard, use the following steps:

  1. Use Compatibility Administrator to add a fix to a custom database. Select the LUA compatibility fix on the Compatibility Modes pages of the wizard. See the Adding a Fix help topic for more information on adding a compatibility fix.
  2. Highlight the application entry in the left pane.
  3. Right click the executable name in the right pane that contains the LUA compatibility mode and select Customize LUA from the context menu.
  4. The first page of the Customize LUA Wizard enables Compatibility Administrator to track attempted file access by the application. The Overwrite existing data and Modify existing data options are very useful if you have run the wizard before and forgot to exercise some aspect of your application. Click the Run program to collect data radio button and click Next.

NOTE: You must be logged on as a user with Administrator permissions to run the LUA wizard.

  5. The Test Run Application dialog opens and gives you the opportunity to change the path and name of the executable if necessary. The real value of this dialog is to enter any command line arguments that may be required by the program. Click OK when you are ready to run the program. The application will run and Compatibility Administrator will gather data about the files and locations the application attempts to write to as you use the features of the program.

NOTE: The full path and name of the executable must be listed in this dialog so that the information can be assigned to the AppPath and AppDrive variables.

  6. On the Edit the File List page you will see a list of files and/or folders that need to be redirected in order to properly support the application. In the first column the files to be redirected are listed with their paths. In the second column you can enter a file or path name to redirect them to. Be careful to always append a backslash (\) at the end of any path to indicate a folder instead of a file. The path to the application files will be represented by the %APPPATH% variable, and the drive where the application resides will be represented by the variable %APPDRIVE%. The Redirect To options will be either Per User or All Users depending on whether the information is stored on a per-user basis or shared among all users.
  7. On the next page, edit the information for both the new per-user and all-users redirection. These options will create new environmental variable settings for %APPDATA% and %COMMON_APPDATA% and will be used by the compatibility mode to redirect information to appropriate folders.
  8. Once all information has been entered, click the Finish button to complete the wizard.

Compatibility Administrator uses variables to represent the drive letter and path where the application is installed, “tokenizing” the path. The option in the Edit the File List page to Show Un-Tokenized Entries will use the full drive letter and file path in the list display instead of the variables.


Deploying Compatibility Fixes

Custom databases contain the various compatibility fixes, modes, and AppHelps for applications. These database files can be deployed to other Windows XP computers in a variety of methods such as logon scripts, Group Policy, or simple file copy operations. Once the file exists on the target computer the custom database file must be installed (registered) before the operating system will identify the fixes present when launching the affected applications.

This is done by using the SDBINST.EXE command from a command prompt, followed by the full path and name of the custom .sdb file. For example:

Sdbinst c:\Windows\AppPatch\myapp.sdb

Once the database file is registered on a computer the compatibility information will be used anytime the application is launched. The full syntax of the SDBINST.EXE command is:

Usage: sdbinst [-?][-q][-u][-n] foo.sdb | {GUID} | “name”

-? Displays the Help screen for SDBINST.EXE

-q Runs the command in Quiet mode, no messages are displayed

-u Uninstall the specified custom database

-g {GUID} Specify the custom database by globally unique identifier (GUID) (uninstall only)

-n “name” Specify the custom database by filename (uninstall only)

The SDBINST.EXE command could be written into a logon script to automatically install the custom database from a share network location when the users logon to their computers. This could even be accomplished as part of a custom job to be pushed out to the desktops.


Glossary

AppHelp

An AppHelp is a message displayed when an affected application is launched. AppHelp messages are defined too be either blocking or non-blocking. Normally, AppHelp messages will define information that a user should know about the application they are attempting to launch, and provide the URL to a Web page that contains more information about the issue.

Blocking AppHelp

A blocking AppHelp will prevent the affected application from launching. This type of AppHelp is appropriate to use when launching the application will have serious adverse effects on the operating system stability or other applications.

Compatibility Database

A compatibility database is a file containing compatibility fixes, modes, and AppHelps for one or more applications. There are several system databases or compatibility databases that are provided with Windows XP that contain compatibility information for hundreds of applications. You can use the Compatibility Administrator tool to create custom databases to contain user-defined compatibility information for applications not found in the system databases.

Compatibility Fix

A compatibility fix, sometimes called a shim, is a small piece of code that intercepts API calls from applications and transforms them so that Windows XP is able to provide the same support the program received from an earlier version of Windows. This can be anything from disabling a new feature of Windows XP to emulating a particular behavior of an older version of the Win32 API set.

Compatibility Mode

A compatibility mode is a collection of compatibility fixes that work together to provide support for an application. Typically, compatibility modes are groups of compatibility fixes that are commonly used to resolve issues for applications and have been grouped together to enable easy reuse of the same fixes.

Custom Database

A custom database is a user-created compatibility database. The custom database may contain compatibility fixes, modes, and/or AppHelp messages as required by the supported applications.

Non-Blocking AppHelp

A non-blocking AppHelp will not prevent the application from launching normally. Instead, this type of AppHelp is designed to provide important information about product updates that may improve performance of the application, or a notice to the user about functionality within the program that may be limited while running on Windows XP.