+

Search Tips   |   Advanced Search

(dist)(iseries)

WASPreUpgrade command

The WASPreUpgrade command for WebSphere Application Server v8.5 saves the configuration of a previously installed version of WAS into a migration-specific backup directory.


Location

The command file is located in and must be run from the v8.5 app_server_root/bin directory.

(iseries) Authority

To run this command script, the user profile must have *ALLOBJ authority.


Syntax

WASPreUpgrade.sh backupDirectory                   currentWebSphereDirectory
                 [-traceString trace_spec [-traceFile file_name ]]
                 [-machineChange true | false]
                 [-oldProfile profile_name]
                 [-workspaceRoot profile1=user_workspace_folder_name_1;profile2=user_workspace_folder_name_2]
                 [-username < user name >]
                 [-password < password >]
                 [-javaoption < -Xms...m > -javaoption < -Xmx...m > ]
                 [-requireEmbeddedDBMigration true | false]
                 [-keepDmgrEnabled true | false]

WASPreUpgrade.bat backupDirectory                    currentWebSphereDirectory
                  [-traceString trace_spec [-traceFile file_name ]]
                  [-machineChange true | false]
                  [-oldProfile profile_name]
                  [-workspaceRoot profile1=user_workspace_folder_name_1;profile2=user_workspace_folder_name_2]
                  [-username < user name >]
                  [-password < password >]
                  [-javaoption < -Xms...m > -javaoption < -Xmx...m > ]
                  [-requireEmbeddedDBMigration true | false]
                  [-keepDmgrEnabled true | false]
(iseries) 
WASPreUpgrade backupDirectory                currentWebSphereDirectory
              [-traceString trace_spec [-traceFile file_name ]]
              [-workspaceRoot profile1=user_workspace_folder_name_1;profile2=user_workspace_folder_name_2]
              [-username < user name >]
              [-password < password >]
              [-javaoption < -Xms...m > -javaoption < -Xmx...m > ]
              [-requireEmbeddedDBMigration true | false]
              [-keepDmgrEnabled true | false]


Parameters

The command has the following parameters:

backupDirectory

This is a required parameter and must be the first parameter specified. The value backupDirectory specifies the name of the directory where the command script stores the saved configuration.

The WAS_INSTALL and USER_INSTALL root directories are invalid directories for the location of the WAS backup directory.gotcha

This is also the directory from which the WASPostUpgrade command reads the configuration.

If the directory does not exist, the WASPreUpgrade command script creates it.

currentWebSphereDirectory

This is a required parameter and must be the second parameter specified. This can be any edition of WAS v6.1 for which migration is supported.

(dist) The value currentWebSphereDirectory specifies the name of the installation root directory for the current WAS v6.1 installation.

(iseries) The value currentWebSphereDirectory specifies the name of the instance or profile root directory for the current WebSphere Application Server instance Version 6.1 profile to migrate.

  • In Version 6.1, the profile root may be a unique value chosen during profile creation but the following directories are the defaults:

    • For Version 6.1 Express or base: /QIBM/UserData/WebSphere/AppServer/V61/Base/profiles/profile

    • For Version 6.1 WebSphere Application Server Network Deployment: /QIBM/UserData/WebSphere/AppServer/V61/ND/profiles/profile

-traceString

This is an optional parameter. The value trace_spec specifies the trace information to collect.

To gather all trace information, specify "*=all=enabled" (with quotation marks).

If we do not specify the -traceString or -traceFile parameter, the command creates a trace file by default and places it in the backupDirectory/logs directory.

-traceFile

This is an optional parameter. The value file_name specifies the name of the output file for trace information.

If we do not specify the -traceString or -traceFile parameter, the command creates a trace file by default and places it in the backupDirectory/logs directory.

(dist) -machineChange

This is an optional parameter used for a migration involving cross operating-system and machine boundaries. If specified as true, this parameter provides support for changing physical hardware when migrating by backing up items stored outside the WAS installation or profile folder hierarchy. If specified as false, only files stored under the WAS installation folder or profile folders are copied to the backup directory during migration.

The default is false.

When this value is false, migration assumes that the new and old WebSphere Application Server installations are on the same physical machine with shared access to the file system. Therefore, any files located outside the WebSphere directories are communal and can be shared. Migration does not copy files outside the WAS tree into the backup directory when -machineChange is false. False is the only option when you use the Migration wizard. If we select -machineChange=false, you must run the WASPostUpgrade command on the same physical hardware.

If we intend to run the WASPostUpgrade command on a different machine or file system, you should run the WASPreUpgrade command with -machineChange=true. If we select -machineChange=true, migration creates an additional subdirectory (/migrated/) in the migration backup directory containing any files referenced by the WAS configuration that reside outside the product or profile directories. When you run the WASPostUpgrade command, these files are returned to their original paths on the new machine.

Performance considerations:

If we migrate with Service Integration Bus (SIB) busses configured with file-system file-store repositories, you might require additional space in our migration heap and migration backup directory. Each bus has three file-store values—a log, a tempspace, and a repository. These three files vary in size, but they can be as much as 100-500 MB each. When migration is running, it backs up any file stores that are in the WAS tree during the pre-upgrade process. There needs to be sufficient space on the file system to permit this. If file stores exist at the destination location already during the post-upgrade process, migration backs up the file stores in memory to support rollback.

If we run the WASPreUpgrade command with -machineChange=true, resulting in a backup directory containing shared file-store objects, you might find that the post-upgrade process suffers from out-of-memory exceptions because the default maximum heap is too small to contain the file-store backups in support of rollback. To resolve this issue, perform one of the following three tasks:

  • If the file stores at the system location are valid, delete the copies from the backup directory before running the WASPostUpgrade command.

    By deleting the entire /migrated/ subdirectory from the migration backup directory before running the WASPostUpgrade command, you essentially convert your pre-upgrade backup from -machineChange=true to -machineChange=false.

  • If the copies of the file stores in the backup directory are valid, delete the versions at the destination location.

    This changes the rollback support so that the destination files do not exist and will not occupy space in memory during the migration.

  • If we require rollback support and we need both the files in the backup directory as well as the files on the file system, increase your maximum heap size for the post-upgrade process to some value great enough to support all of the SIB files that conflict.

(dist) -oldProfile

This is an optional parameter used for migrating a specific instance or profile from a previous version of WAS.

-workspaceRoot

This is an optional parameter. The value user_workspace_folder_name_x specifies the location of the console customized "My tasks" settings for one or more profiles.

-username

This is an optional parameter. The value user name specifies the administrative user name of the current WebSphere Application Server installation.

This is a required parameter if the following conditions are true:

  • We are migrating a deployment manager.

  • Administrative or global security is enabled in the source installation.

  • The WebSphere Application Server installation you are migrating from is Version 8.0 or above.

-password

This is an optional parameter. The value password specifies the administrative password of the current WebSphere Application Server installation.

This is a required parameter if the following conditions are true:

  • We are migrating a deployment manager.

  • Administrative or global security is enabled in the source installation.

  • The WebSphere Application Server installation you are migrating from is Version 8.0 or above.

-javaoption

This is an optional parameter. Specify memory sizes for the Java heap used by the WASPreUpgrade command.

The value "-Xms...m" is the parameter specified to indicate the starting heap size. Replace the "..." with the size in Megabytes that you intended to use. For example, if the starting heap size is to be 128 MB, specify the parameter as: -javaoption -Xms128m

The value "-Xmx...m" is the parameter specified to indicate the maximum heap size. Replace the "..." with the size in Megabytes that you intend to use. For example, if the maximum heap size is to be 1024 MB, specify the parameter as: -javaoption -Xmx1024m

-requireEmbeddedDBMigration

This is an optional parameter for migrating embedded databases.

If the value is specified as true, any exception that occurs when you migrate the embedded databases causes the WASPreUpgrade command to fail. If the value is specified as false, any exception that occurs when you migrate the embedded databases is logged in the trace file, and the WASPreUpgrade command continues.

The default value is true.

-keepDmgrEnabled

This is an optional parameter used for migrating a Version 8.0 dmgr profile.

When WASPreUpgrade runs, Version 8.0 dmgr profiles are stopped. By default, the deployment manager remains stopped. If the value is specified to true, WASPreUpgrade starts the deployment manager before the command finishes running.

The default value is false.


Logging

The WASPreUpgrade tool displays status to the screen while it runs. The tool also saves a more extensive set of logging information in the WASPreUpgrade.time_stamp.log file written to the backupDirectory directory, where backupDirectory is the value specified for the backupDirectory parameter. We can view the WASPreUpgrade.time_stamp.log file with a text editor.


Migrated resources

WASPreUpgrade saves all of the resources, but it does not migrate entities in our classes directory.

Migration saves the following files in the backupDirectory directory.

  • WASPostUpgrade command