Rational XDE* v2003 Model Repair Tool, v. 1.0
Release and Installation Notes
Licensed Materials – Property of IBM
© Copyright IBM Corp. 2003[1]
This document describes the Model Repair Tool (MRT), its purpose, installation and use.
The MRT Tool
Upgrading Rational XDE models to Rational XDE 2003 will not work if a model has missing subunit files. This condition is normally indicatedbya dialog box stating “Upgrade failed: Model upgrade failed because subunits were missing or unusable.”
In order to work with this condition, a Model Repair Tool (MRT) has been created to help diagnose potential problems, as well as fix the specific problem of missing subunit files (for details, see the “Purpose” section).
If the MRT identifies missing subunit files, the tool will ask you to assemble all the missing units from other sources (such as configuration management branches or locations) into the workspace in which you are upgrading the models. However, some of these units may have been deleted, can no longer be found, or are no longer wanted. In this case, the MRT will allow you to remove references to these storage units from the model so that it can be upgraded using Rational XDE 2003.
The MRT is a Microsoft† Visual Basic[2] 6 application that you can install on any Microsoft† Windows XP† or Windows 2000† (SP3) platform along with a Rational XDE 2003 installation. You do not need Visual Studio 6 installed for the MRT to function properly (for details, see the “Installation” section).
Some caveats:
· The MRT will only make minor repairs in otherwise sound models. Models with serious problems should be sent to Rational Technical Support (see Contacting Rational Technical Support). The MRT will indicate whether the problem can be fixed automatically or not.
· The MRT detects only certain types of problems having to do with subunits and imported models, as well as Rational XDE for Microsoft Visual Studio .NET† profile upgrade problems. This version of the MRT does not diagnose cases where the model does not load at all.
· The MRT works with Rational XDE v2003, and will write models in a format that cannot be opened by earlier versions of Rational XDE, since the models are not backward compatible.
· The MRT allows you to see a detailed log of the analysis performed on the models you select. Note that these logs are intended for consumption by Rational IBM technical staff, and may seem obscure.
NOTE: Customers should be aware that this tool reports on model names, subunit names, and fully qualified cross-model reference names. This may constitute proprietary or classified information. Please take appropriate care when submitting logs to Rational Technical Support (see Contacting Rational Technical Support).
Purpose
You can use the MRT to diagnose the causes of some of the following problems:
· Inability to upgrade a model. For example, some storage units may not be present in your file system.
· Inability to fully load a model. For example, some storage units may fail to load, or parts of the model’s content seem lost.
· Inability to resolve references to other models.
· Unnecessary conflicts during Visual Studio .NET code synchronization. These can be fixed automatically by the MRT.
The specific technical problems that are examined include:
· Storage unit files that cannot be found where Rational XDE expects them.
· Storage unit files with no content (i.e. that are empty).
· Storage unitsknown by a differentGUID (Globally Unique ID) from the GUID in the storage unit file.
· Storage units that fail to load for unknown reasons.
· Various problems detected by Rational XDE.
· Multiple Uniform References (Location Registry Components) being used to reference the same model.
· Storage unit files that have been modified with Microsoft Notepad† and saved in a format other than ANSI.
· Storage unit files that have been truncated.
· Storage unit files that have references to non-existent elements within the same storage unit.
· Incomplete profile upgrades in Rational XDE for Visual Studio .NET models. This can be fixed automatically.
The MRT logs other useful information in addition to the items listed above. For example, the MRT identifies storage unit files that are not currently part of a model. Such storage unit files are created during normal usage of Rational XDE and their presence does not indicate a problem.
Installation
The MRT and its installer have been tested on Windows 2000 (SP3) and Windows XP.
You do not need to install Rational XDE before you install the MRT; however, the MRT will not run without it. Further, you do not need to have Visual Studio 6 installed to run the MRT.
To install:
Unzip Model Repair Installer.zip and run setup.exe.
To uninstall, use the standard Microsoft Windows “Add or Remove Programs” Control Panel.
NOTE: Please press the button with the computer-and-box icon.
The installation begins and a small status bar appears until the MRT is completely installed.
A dialog box appears letting you know that the MRT was installed successfully.
Use
Please install Rational XDE v2003 before using the MRT.
You may start the MRT by pressing the Start button and selecting Programs > Rational XDE Model Repair Tool > Model Repair Tool.
- Press the Select Model button.
The Select a Model to Repair dialog box opens.
- Select the .mdx file you want to diagnose, and press Open.
The model is analyzed. Large models may take a few minutes to diagnose.
If you are informed that a problem exists that the MRT can fix, you may want to modify the backup folder that will be used to save a copy of your existing model before repairs are made.
In particular, if your model has many nested storage units, you may encounter problems with the file path length limit being exceeded by your innermost storage unit files. The standard “temp” folder has a long path name.
To change the backup folder to a shorter path, e.g. to “C:\Temp”, press the Select Backup Folder button and select an alternative folder. A numbered folder will be created within this folder for any actual backups made.
Types of Problems Reported
After the diagnosis is complete, one of the following dialog boxes appears:
· Successful Analysis – No Known Problems
· Missing Storage Unit Problems Found
· Profile Problems Found
· Notepad Problem Found
· Serious Problems Found
· Analysis Problems – Model Load Fails
Successful Analysis – No Known Problems
This dialog box indicates that the MRT did not find any of the known model, subunit, or reference problems in the model. You may wish to see the detailed results of the analysis; in that case, pressing the Yes button will open Notepad with the results.
You should be able to upgrade your model to Rational XDE v2003 without problems.
Missing Storage Unit Problems Found
This dialog box indicates that the MRT found problems that it is able to fix. You may wish to see the detailed results of the analysis; in that case, pressing the Yes button will open Notepad with the results.
Dismiss the dialog box and follow the directions provided by the task pane (the tree view on the right hand side of the main display). Keep in mind that you should try to repair the model by locating the missing storage units and placing them with correct filenames in the correct folders, rather than deleting references to them in the model. The MRT is, however, able to destroy all references to missing storage unit files if you press the Destroy Missing Subunits button.
Use the left hand tree view in the main display to see where in the model hierarchy the missing storage units are. Click the check box marked Show Good Storage Units (or maybe just Good if the display has been resized) if you want to see more context. To get the exact path and filename where Rational XDE expects a storage unit file, see the list of missing storage unit files in the task list on the right hand side of the main display.
A backup will be made of your model before it is repaired.
The MRT will warn you once before you accidentally delete all traces of the missing storage units in the model. It is important that you press the Analyze Model button again after repositioning any missing storage unit files that you were able to locate, and verify that they are no longer listed as missing subunits. Otherwise, references to them will be deleted from the model when you press the Destroy Missing Subunits button.
Profile Problems Found
This dialog box indicates that the tool found problems that it is able to fix. You may wish to see the detailed results of the analysis; in that case, pressing the Yes button will open Notepad with the results.
Follow the directions provided by the task pane (the tree view on the right hand side of the main display), and then press Fix Profiles.
A backup will be made of your model before it is repaired.
Notepad Problem Found
This dialog box indicates that the MRT found problems that that you may be able to fix. You may wish to see the detailed results of the analysis; in that case, pressing the Yes button will open Notepad with the results.
Follow the directions provided by the task pane (the tree view on the right hand side of the main display). To repair the potential Notepad encoding problem, open the indicated file in Notepad, select Save As, and save the file after setting the Encoding to ANSI.
NOTE: This repair procedure will only work if all characters in the file are 7-bit ASCII. If this is not the case, you must locate an uncorrupted version of the file or contact customer support (see Contacting Rational Technical Support).
Serious Problems Found
This dialog box indicates that the MRT found problems in the model that it cannot fix. You may wish to see the detailed results of the analysis; in that case, pressing the Yes button will open Notepad with the results.
Please contact customer support (see Contacting Rational Technical Support).
NOTE: It is possible to have the MRT fix other problems with the model at this point, but it is inadvisable, since doing so could cause data loss:
The MRT task display may look like this (see the right hand tree view):
If the MRT indicates that there are missing storage unit files, you should start looking for them while you request assistance on the issues in red boldface from Rational Technical Support (see Contacting Rational Technical Support).
Note that intact versions of empty files (the red boldface <empty file> error in the screenshot above) could be retrievable from your configuration management system. If the storage unit files cannot be retrieved, the MRT can be used to remove references to them by first deleting/destroying the empty file from the file system and re-analyzing the model.
This is an extreme measure and should only be done after careful consideration; the action results in data loss.
Analysis Problems – Model Load Fails
If the MRT cannot load a model, it will examine the file system for potentially related subunits; however, the analysis will be less exhaustive.
If no known problems are identified, the above dialog box appears. You may need to contact customer support (see Contacting Rational Technical Support).
Performing Indicated Tasks
Individual issues are described in the sections Types of Problems Reported and Problems Identified by the Model Repair Tool. This section describes the general workflow for using the tool.
To use the MRT, select a model, look at the resulting dialog box and task list, and perform (cautiously) the tasks indicated. The tasks are listed on the right hand side of the tool’s main display, in order of importance, starting with the most serious issue.
If you need more space to see long path names, you may resize the main window, or drag the divider between the left and right panes.
If you would like to see all storage units in the model, e.g. to get better context information, click the check box marked Show Good Storage Units (or maybe just Good if the display has been resized).
If the MRT indicates that there are missing storage units, and you have been unable to locate intact copies of the storage unit files, then you will need to give the tool write access to all the storage units that need to be modified in order to eradicate all references to those storage units from the model. The MRT lists files that need to be checked out or otherwise write enabled in the task list:
In the above example, you must check out the file called “UseCaseModel.pkx” in the Sample Model folder. If you don’t check out the file before pressing the Destroy Missing Subunits button, the following dialog box appears:
All model-related paths in the MRT are displayed relative to the folder in which the model (.mdx) file is located.
Once the MRT successfully destroys all traces of a missing storage unit, the MRT will re-analyze the model, and display the following dialog box:
NOTE: The MRT may indicate that there are unused model-related files (such as storage unit files for deleted model elements) that do not seem to be used by the analyzed model, or any model in the same folder or subfolders. You may want to remove unused model-related files from your file system to avoid confusion. However, such files may not actually be obsolete. They may temporarily be ignored by Rational XDE due to errors in other storage units that are preventing the files from being referenced properly. They could also be used by a model that the MRT did not detect, so use caution.