WebSphere Message Brokers
File: an26150_
Writer: Bill Oppenheimer

Reference topic

This build: July 31, 2007 21:33:58

mqsimigratecomponents command

The mqsimigratecomponents command migrates a component from a previously installed version of the product to another to prepare it for participation in the broker domain of the target version.

Supported platforms

  • Windows®.
  • Linux® and UNIX® systems.
  • z/OS®. Run this command by customizing and submitting BIPMGCMP.

Purpose

Migrate components to WebSphere® Message Broker Version 6.1 from Version 6.0 or from Version 5.0.

Start of changeYou can also use this command to return a component from a later version to an earlier one to reverse the effects of forward migration, with one exception. You cannot return a Configuration Manager from Version 6.1 to Version 5.0.End of change

You must run this command from whichever version of the installed product is the later, regardless of whether it is the source version or the target version.

For Version 5.0 of the product, Version 5.0.0.4 (Fix Pack 4) is the earliest release of the product that is supported.

You must have an installation of the product at the required version, with the required component code installed, to issue this command successfully.

Before you start migration, stop any active debug sessions in the Message Broker Toolkit. You cannot migrate message flows that are being debugged.

Specify appropriate options on this command to perform one of the following actions:
  • Check on a component, without making any changes, to ensure that the component is suitable for the required migration (-c).
  • Move a component to a different version, in full or part (-s and -t).
  • Undo a failed migration step (-u).
  • Verify that a move has been successful (-v).

The mqsimigratecomponents command updates your registry and file system, WebSphere MQ definitions, and database definitions. If the user who is issuing the command does not have the authority to perform all of these steps, the command can be run one part at a time. Different users can run the part for which they are authorized in order to achieve the overall result. This approach is referred to as split migration, and is performed using the -1, -2, and -3 parameters.

If you are using the mqsimigratecomponents command with a Sybase database, you must modify the database by performing the following actions:
  1. Log on to ISQL using a system administrator account.
  2. Issue the following series of commands:
    1> use master
    2> go
    1> sp_dboption "BROKER1","ddl in tran",TRUE
    2> go
    Database option 'ddl in tran' turned ON for database 'BROKER1'.
    Run the CHECKPOINT command in the database that was changed.
    (return status = 0)
    1> use BROKER1
    2> go
    1> checkpoint
    2> go
    where BROKER1 is the name of the Sybase broker database.

Syntax

Parameters

-c
(Optional) Do a check of a specified component before you migrate it, to ensure that:
  • The auto-detected version of the broker matches any version specified on the command line.
  • 64-bit execution groups are not supported if you are migrating from Version 6.1 to Version 5.0.
  • The database tables to be copied from a previous release do not contain any rows that violate Version 6.1 index requirements.

The migration check can be run against a running component. The check does not impact the component, except for imposing a slight performance penalty. On Linux and UNIX systems, you must migrate the ODBC configuration file (the file in which you have defined the data sources, for example .odbc.ini) before you run the check, because the checking command must be able to access the broker database.

The check command either succeeds or fails, and prints a message about whether the migration will succeed, but no modifications are made during the process.

-v
(Optional) Do a post-migration check of a specified component to ensure that:
  • The correct database tables and queues exist for the specified version.
  • The registry is in the correct format for the specified version.
-q
(Optional) Print fewer status messages during the operation.
-1
(Optional) Do only registry and file system work.
  • When you migrate to Version 6.1, use the -1 parameter before the -2 or -3 parameters.
  • When migrating backwards to a previous version, use the -2 or -3 parameters before the -1 parameter.
-2
(Optional) Do only WebSphere MQ work.
-3
(Optional) Do only database work.

If a broker that you are migrating shares a database schema with another broker, warning message BIP8678 is issued and the check fails. In this case, all the brokers that share a database schema must be migrated together.

  1. Stop all the brokers that are sharing the database schema.
  2. Migrate the first broker. This action migrates the database tables for all brokers, as well as the file system and registry, and WebSphere MQ definitions for that broker only; for example:
    mqsimigratecomponents FIRSTBROKER -t 6.1.0.0
  3. Migrate the file system and registry, and WebSphere MQ parts of each of the other brokers; the database part has already been migrated. Use the -1 and -2 parameters to do this, either in one step or two steps:
    • In one step:
      mqsimigratecomponents BROKERB -1 -2
    • In two steps:
      mqsimigratecomponents BROKERB -1
      mqsimigratecomponents BROKERB -2
-u
(Optional) Undo a failed migration step; you must also specify at least one of -1, -2, or -3. You should only use this option when migration has failed, and also failed to auto-recover (a failure during split migration being one example).
-s SourceVersion
(Optional) The previous version of the component.
  • If not specified, this value is detected automatically.
  • When you perform split migration to Version 6.1, the -s parameter is mandatory after you run the mqsimigratecomponents command with the -1 parameter, as shown in the split migration example.
  • See Purpose for the restrictions to the version numbers of the product that are supported.
-t TargetVersion
(Optional) The destination version of the component.
  • If not specified, this value is assumed to be the current version.
  • When you perform split migration from Version 6.1 to a previous version, the -t parameter is mandatory, as shown in the split migration example.
  • See Purpose for the restrictions to the version numbers of the product that are supported.
ComponentName
(Required) The name of the component to migrate.

Authorization

If you run single-step migration, your user ID must have the ability to:
  • Write to the registry and the file system for the product
  • Modify databases associated with the component
  • Modify queue definitions
If you run split migration, your user ID must always have the ability to read from the registry for the product, and also have specific authorization for each step to succeed:
  • -1 requires the ability to write to the registry and the file system for the product
  • -2 requires the ability to modify queue definitions
  • -3 requires the ability to modify databases associated with the component

Responses

This command can produce a large number of possible responses, depending on the results of the various operations. This command differs from other commands in the way it produces messages: they are displayed as generated, rather than being reported in a batch at the end of the program. When you migrate database tables, z/OS produces more output than distributed systems. Use the -q parameter to reduce the number of messages displayed.

Examples

The following example illustrates a split migration from Version 5.0 to Version 6.1:

mqsimigratecomponents BROKER -1
mqsimigratecomponents BROKER -s 5.0.0.5 -2
mqsimigratecomponents BROKER -s 5.0.0.5 -3

The following example illustrates a migration from Version 6.1 back to Version 6.0:

mqsimigratecomponents BROKER -t 6.0.0.4
Related reference
Migration and upgrade
Notices | Trademarks | Downloads | Library | Support | Feedback

Copyright IBM Corporation 1999, 2007Copyright IBM Corporation 1999, 2007. All Rights Reserved.
This build: July 31, 2007 21:33:58

an26150_ This topic's URL is: