mqsimigratecomponents command

Supported platforms

  • Windows
  • Linux and UNIX systems
  • z/OS

Purpose

The mqsimigratecomponents command moves a component from one previously installed version (either Version 2.1 or Version 5 only) of the product to another. This command must be run from whichever version of the installed product is the later, regardless of whether it is the source version or the target version.
Note:
  1. For Version 2.1 of the product, Version 2.1 CSD02 (2.1.0.3) is the earliest release of the product supported. (See Migrating and upgrading for more information.)
  2. For Version 5 of the product, Version 5.0.0.4 is the earliest release of the product supported.

You must have a Version 6.0 installation of the product with the required component code installed, that is, the broker component is installed if it is needed, and so on.

Before starting migration, stop any debugging sessions in the Control Center. It is not possible to migrate message flows that are being debugged.

You can invoke the command with various options 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 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 pre migration check of a specified component to ensure that:
  • The auto-detected version of the broker matches any version specified on the command line
  • There are no 64 bit execution groups, if migrating from Version 6.0 to a previous release
  • The database tables to be copied from a previous release do not contain any rows that violate Version 6.0 index requirements.
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 will migrate 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.0.0.1 
  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

The migration check can be run against a running component. This does not impact the component, except for imposing a slight performance penalty. Note that on UNIX systems, the odbc.ini file needs to be migrated (that is, a new-format odbc.ini file needs to be created with the same set of data sources as the old one) before the check can be run, because the checking command needs to be able to access the broker database.

The check command either succeeds or fails, and prints a message about whether or not the migration should 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 migrating to Version 6.0, 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.
-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 Source Version
(Optional) The previous version of the component.
  • This value is detected automatically if not specified.
  • When performing split migration to Version 6.0, the -s parameter is mandatory after you run the mqsimigratecomponents command with the -1 parameter. This is illustrated in the split migration example.
  • See Purpose for the restrictions to the version numbers of the product that are supported.
-t Target Version
(Optional) The destination version of the component.
  • This value is assumed to be the current version if not specified.
  • When performing split migration from Version 6.0 to a previous version, the -t parameter is mandatory. This is illustrated in the split migration example.
  • See Purpose for the restrictions to the version numbers of the product that are supported.
Component Name
(Required) The name of the component to migrate.

Authorization

When running single-step migration, the user ID used to invoke this command 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
For split migration, the user ID used to invoke this command 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

Start of changeThis command can produce a large number of possible responses, depending on the results of the various operations. Note that this command differs from other commands in the way it produces messages – they are displayed as needed, rather than being produced in a batch at the end of the program. When migrating database tables, z/OS produces more output than distributed systems.End of change

Examples

The following example checks for migration of BROKER1 from Version 2.1 to Version 6.0:

Start of change
mqsimigratecomponents –c BROKER1
BIP8849I: Broker 'BROKER1' (Version 2.1) with Queue Manager 'brkqm1' and Data Source 'brkdb1' specified for migration.
BIP8791I: Duplicate rows check started.
BIP8794I: Table BRMINFO has no duplicated rows.
BIP8794I: Table BRMRTDDEPINFO has no duplicated rows.
BIP8794I: Table BROKERRESOURCES has no duplicated rows.
BIP8794I: Table BRMRTDINFO has no duplicated rows.
BIP8794I: Table BRMWFDINFO has no duplicated rows.
BIP8792I: Duplicate rows check passed.
BIP8791I: Duplicate rows check started.
BIP8800W: No invalid topic syntax was detected in table BSUBSCRIPTIONS.
BIP8800W: No invalid topic syntax was detected in table BPUBLISHERS.
BIP8800W: No invalid topic syntax was detected in table BRETAINEDPUBS.
BIP8797I: Topic syntax check succeded
BIP8680I: Pre-migration check succeeded.
BIP8071I: Successful command completion.
End of change

The following example does automatic migration of BROKER1 from Version 2.1 to Version 6.0:

Start of change
mqsimigratecomponents BROKER1
BIP8849I: Broker 'BROKER1' (Version 2.1) with Queue Manager 'BROKER1' and Data Source 'BROKERDB' specified for migration.
BIP8755I: Copied value 'QueueManagerName' into the new location
BIP8755I: Copied value 'DataSourceName' into the new location
BIP8755I: Copied value 'DataSourceUserId' into the new location
BIP8755I: Copied value 'DataSourcePassword' into the new location
BIP8755I: Copied value 'LilPath' into the new location
BIP8755I: Copied value 'ConfigurationTimeout' into the new location
BIP8755I: Copied value 'ConfigurationDelayTimeout' into the new location
BIP8755I: Copied value 'MigrationNeeded' into the new location
BIP8755I: Copied value 'MQTrustedQueueManager' into the new location
BIP8755I: Copied value 'UserNameServerQueueManagerName' into the new location
BIP8755I: Copied value 'BrokerUUID' into the new location
BIP8755I: Copied value 'AdminAgentPID' into the new location
BIP8763I: Deleted value 'QueueManagerName' from the old location
BIP8763I: Deleted value 'DataSourceName' from the old location
BIP8763I: Deleted value 'DataSourceUserId' from the old location
BIP8763I: Deleted value 'DataSourcePassword' from the old location
BIP8763I: Deleted value 'LilPath' from the old location
BIP8763I: Deleted value 'ConfigurationTimeout' from the old location
BIP8763I: Deleted value 'ConfigurationDelayTimeout' from the old location
BIP8763I: Deleted value 'MigrationNeeded' from the old location
BIP8763I: Deleted value 'MQTrustedQueueManager' from the old location
BIP8763I: Deleted value 'UserNameServerQueueManagerName' from the old location
BIP8763I: Deleted value 'BrokerUUID' from the old location
BIP8763I: Deleted value 'AdminAgentPID' from the old location
BIP8768I: Finished registry migration for component 'BROKER1'.
BIP8654I: Moving filesystem artefacts from '' to 'C:\Documents and Settings\AllUsers\Application Data\IBM\MQSI'
BIP8670I: Database migration started
BIP8663I: Creating temporary new tables
BIP8664I: Migrating from existing tables to temporary new tables
BIP8665I: Dropping existing tables
BIP8666I: Creating new tables
BIP8667I: Copying all rows from temporary new tables to new tables
BIP8668I: Dropping temporary new tables
BIP8669I: Database migration successful
BIP8785I: Starting WebSphere MQ queue migration for component 'BROKER1'.
The setmqaut command completed successfully.
BIP8786I: Created WebSphere MQ queue 'SYSTEM.BROKER.AGGR.REQUEST'
The setmqaut command completed successfully.
BIP8786I: Created WebSphere MQ queue 'SYSTEM.BROKER.AGGR.CONTROL'
The setmqaut command completed successfully.
BIP8786I: Created WebSphere MQ queue 'SYSTEM.BROKER.AGGR.REPLY'
The setmqaut command completed successfully.
BIP8786I: Created WebSphere MQ queue 'SYSTEM.BROKER.AGGR.TIMEOUT'
The setmqaut command completed successfully.
BIP8786I: Created WebSphere MQ queue 'SYSTEM.BROKER.AGGR.UNKNOWN'
The setmqaut command completed successfully.
BIP8786I: Created WebSphere MQ queue 'SYSTEM.BROKER.TIMEOUT.QUEUE'
The setmqaut command completed successfully.
BIP8786I: Created WebSphere MQ queue 'SYSTEM.BROKER.INTERBROKER.MODEL.QUEUE'
The setmqaut command completed successfully.
BIP8786I: Created WebSphere MQ queue 'SYSTEM.BROKER.WS.INPUT'
The setmqaut command completed successfully.
BIP8786I: Created WebSphere MQ queue 'SYSTEM.BROKER.WS.REPLY'
The setmqaut command completed successfully.
BIP8786I: Created WebSphere MQ queue 'SYSTEM.BROKER.WS.ACK'
The setmqaut command completed successfully.
BIP8786I: Created WebSphere MQ queue 'SYSTEM.BROKER.IPC.QUEUE'
BIP8787I: Cleared WebSphere MQ queue 'SYSTEM.BROKER.ADMIN.QUEUE'
BIP8787I: Cleared WebSphere MQ queue 'SYSTEM.BROKER.EXECUTIONGROUP.QUEUE'
BIP8787I: Cleared WebSphere MQ queue 'SYSTEM.BROKER.EXECUTIONGROUP.REPLY'
BIP8787I: Cleared WebSphere MQ queue 'SYSTEM.BROKER.IPC.QUEUE'
BIP8789I: Finished WebSphere MQ queue migration for component 'BROKER1'.
BIP8071I: Successful command completion.
End of change

The following example illustrates a split migration from Version 2.1 to Version 6.0:

mqsimigratecomponents BROKER -1
mqsimigratecomponents BROKER -s 2.1.0.8 -2
mqsimigratecomponents BROKER -s 2.1.0.8 -3

The following example illustrates a split migration from Version 6.0 to Version 2.1:

mqsimigratecomponents BROKER -t 2.1.0.8 -2
mqsimigratecomponents BROKER -t 2.1.0.8 -3
mqsimigratecomponents BROKER -t 2.1.0.8 -1