![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
Control > Maintenance > Upgrade To New Release (Apex/Summit)After installation, upgrade your subsystems using the Upgrade to New Release dialog. (Note that if you are performing a patch install, it is not necessary to run apex_upgrade. Installing a patch to an existing release is covered in the Installation Guide.) The Upgrade to New Release dialog performs the following actions:
- Updates switches.
- Updates imports.
- Deletes and recreates .Rational/Compilation and .Rational/Imports_Control (unless the -no_cleaning option is set).
- Remodels all specified views (skips views for which you do not have write permission).
The functionality of apex_upgrade command is described below, followed by a description of the Upgrade to New Release dialog.
General Information
There are four basic actions that can be done with apex_upgrade:
- Create a model map
- Do the upgrade (using the model map)
- Revert (to pre-upgrade state)
- Commit (remove files needed to Revert)
These actions correspond to the following four options:
-create_model_map <map>
-use_model_map <map>
-revert
-commitThe actions are described below:
Action #1: Create a model map
In the previous versions of apex_upgrade, the set of new models to use was provided by the user on the command line. Models that not specified on the command line were taken from environment variables (eg $APEX_ADA95_MODEL).
This version of apex_upgrade computes the set of new models by translating the version number (eg 3.2.0) in old models to the new version number (eg 4.0.0). A one-to-one mapping of old to new models is created, and stored in a file specified by the user using the "-create_model_map <map>" option. After its creation, you should inspect the newly created <map> file. Each line of this file is of the form "old_model: new_model". If any new_model is set to UNKNOWN, that means apex_upgrade was unable to determine a replacement view. You must either edit this file and replace all instances of UNKNOWN with valid models, or rerun apex_upgrade with the -create_model_map <map> option omitting views based on the old_models that were mapped to UNKNOWN.
You may also edit the <map> file to override any new_model values.
Views that have already been upgraded will have the new models listed in the old_model column of the <map> file. The corresponding new_model will be set to "ALREADY_IS_NEW_MODEL", and can be left as-is.
Action #2: Do the upgrade (using the model map)
You can specify the set of views to be upgraded explicitly, or via subsystem names or configuration files. Specifying a subsystem will upgrade the Policy/Switches file for that subsystem, and all views in the subsystem. Specifying a configuration file will upgrade all views in the configuration.
Views can be removed from the list to be upgraded via the -skip* options. You have the option of running apex_upgrade in two passes. The reason for breaking apex_upgrade into two passes is that some product installations have unix file permissions such that different people must perform pass 1 on different sets of views. If this is not a concern for your installation, you can perform both passes during a single invocation of apex_upgrade. Use the -pass option to specify which pass(es) to perform.
Pass 1 performs the following operations:
- updates Policy/Switches
- updates Imports
- cleans views
- remodels views based on new models
Pass 2 performs the following operations:
- remodels views (if run separately from pass 1)
- compiles views
The reason for breaking apex_upgrade into two passes is that some product installations have unix file permissions such that different people must perform pass 1 on different sets of views. If this is not a concern for your installation, you can perform both passes during a single invocation of apex_upgrade. Use the -pass option to specify which pass(es) to perform.
Action #3: Revert (to pre-upgrade state)
Backing out upgrade
This version of apex_upgrade allows you to partially back out an upgrade. Backups of following information is saved before apex_upgrade alters it.
- The Policy/Switches file.
Policy/Switches.pre_$APEX_PROD_VERSION.upgrade
- The Imports/*.cfg files.
Imports/*.cfg.pre_$APEX_PROD_VERSION.upgrade
- The view's current model.
Running apex_upgrade with the -restore option will restore these files, and remodel views.
Note, however, that once views are cleaned (during pass 1) compilation information cannot be retrieved.
Action #4: Commit (remove files needed to Revert)
Although it will not harm anything to leave the backup files in place, the -commit option will remove them should you wish to do so.
Upgrading very old views
apex_upgrade is designed to upgrade views based on models from Apex beyond a specific version (see -upgrade_very_old_views of usage section at bottom of output for exact Apex version). If you attempt to upgrade views based on older models, apex_upgrade will print an error, and give you the option of re-running with the -upgrade_very_old_views option. It is expected that there will be problems if you use this switch to upgrade old views. But it is provided for advanced Apex users who can finish upgrading views by hand after apex_upgrade has done what it can.
Remodeling views with non-Rational keys
If a C/C++ view has the BUILD_KEY switch set to a value other than $APEX_BASE/c++/keys/* the view is said to have a non-Rational key. The BUILD_KEY will not be updated, and the view will not be remodeled unless the -replace_other_keys switch is specified.
Similarly, if any other view has the COMPILER_KEY switch to a value other than $APEX_BASE/ada/key.ss/*.{rel,wrk} the view is said to have a non-Rational key. The COMPILER_KEY will not be updated, and the view will not be remodeled unless the
-replace_other_keys switch is specified.
Dialog DescriptionThe following is a top-to-bottom description of the Upgrade To New Release dialog.
- Views, Subsystems, and Configurations to upgraded:
This list identifies the views and subsystems that will be upgraded. You must specify at least one item to upgrade.
Add items to the list by typing them in next to the Add: button, and then pressing the Add: button. Wild cards will be expanded as items are added to list.
If you specify a subsystem, the subsystem will appear in the list, but all views within that subsystem will be upgraded.
Note: Mutually imported views must be upgraded together.
- Action:
You must select one of the four actions: Create Model Map, Do Upgrade, Revert, or Commit.
The "Create Model Map" action must be performed before you can perform the action "Do Upgrade".
- Model Map:
This section specifies the full path to the Model Map file. This file is created during the "Create Model Map" action, and is used during the other three actions.
- Options:
The toggle buttons in the options section control the behavior of all four actions.
- Skip these views:
Selecting Ada 83 will skip Ada 83 views
Selecting Ada 95 will skip Ada 95 views
Selecting C++ will skip C++ views
Selecting RCI will skip RCI views
- Skip Views with Name(s):
You can enter the full path names of views in this field. Alternatively, you can enter the name of a file containing a list of views: one view per line.
- Verbose:
Prints extra information about the upgrade to the message window.
- Attempt to upgrade views based on very old models:
No testing has been done to verify that this command will correctly upgrade views based on pre-3.0.0 Apex. If you attempt to upgrade such views, the default behavior is to warn you that apex_upgrade is skipping those views. If you want to force apex_upgrade to try to upgrade the views anyway, select this toggle.
- Effort Only:
List the views that would be upgraded, and show the commands that would be executed.
- First Pass:
This section of the dialog is only active if the Do Upgrade action is selected. Performing First pass upgrades requires group write access to each view.
- Update Import Information
Updates the direct and mutual imports for each view. This toggle should remain selected unless you have specific reasons why you do not want imports updated.
- Clean Each View
Remove compilation artifacts for each view. Does not remove linked executables.
- Remodel Each View
Remodels all views that have the default (i.e. Rational supplied) Compiler Key or Build Key.
Update the following switches:
- All:
Update all switches in Policy/Switches
All switches except Compiler Keys and Build Keys set to non-Rational values:
Update all switches in Policy/Switches except COMPILER_KEY and BUILD_KEY. Use this switch if you have set these switches to special values and do not want them updated.
- Second Pass:
Command Line Interface: apex_upgrade.
Rational Software Corporation http://www.rational.com support@rational.com techpubs@rational.com Copyright © 1993-2001, Rational Software Corporation. All rights reserved. |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |