mqsimigratecomponents command

Supported platforms

  • Windows
  • Linux and UNIX systems
  • z/OS

Purpose

The mqsimigratecomponents command moves one or more components 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; whether it is the source or the destination.
Note:
  1. For Version 2.1 of the product, Version 2.1.0.8 is the earliest release of the product supported.
  2. For Version 5 of the product, Version 5.0.0.4 is the earliest release of the product supported .
  3. The -t and -s parameters can accept version numbers in the form Version.Release.Modification.Fixpack, for example 5.0.0.4, and can also accept "5" and "2.1" as a shortened form for the previous versions that are 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 one or more components, without making any changes, to ensure that the components are suitable for the required migration.
  • Move one or more components to a different version, in full or part.
  • Undo, that is reverse, a successful move from one version to another, in full or part.
  • Verify that a move has been successful.
Start of changeIf 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.
End of change

Syntax

Parameters

-c
(Optional) Do a pre migration check of specified components to ensure the following:
  • If more than one broker component is specified, the brokers share a database schema
  • In all cases, a migrating broker database schema cannot be shared with a broker that is not being migrated at the same time.
  • 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:
    • Scanning through all the rows is the easiest way
    • Global lock is taken if the broker is Version 2.1

The migration check can be run against a running component, or set of components. This does not impact the components, 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 specified components to ensure the following:
  • 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. Use the -1 parameter before the -2 or -3 parameters.
-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).
-sSource Version
(Optional) The previous version of the component. This value is detected automatically if not specified. See Purpose for the restrictions to the version numbers of the product that are supported.
-tTarget Version
(Optional) The destination version of the component. This value is assumed to be the current version if not specified. 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; at least one must be specified.

Authorization

When running single-step migration, the user ID used to invoke this command must have the ability to:
  • Write to the registry for the product
  • Modify databases associated with the components
  • 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 modify queue definitions
  • -2 requires the ability to write to the registry for the product
  • -3 requires the ability to modify databases associated with the components

Responses

This 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.

Examples

The following example checks for migration of BROKER1 from V2.1 to Version 6.0:

mqsimigratecomponents –c BROKER1
BIP 0001I: Starting migration check for component ‘BROKER1’ to FAD level ‘3’
BIP 0002I: ‘BROKER1’ is version 2.1 (auto-detected)
BIP 0003I: Broker database ‘BKRDB’ and schema ‘WMQIUSER’ are not shared with other components.
BIP 0004I: No invalid rows found in broker database.
BIP 0005I: Migration check passed.
BIP 8071I: Successful command completion.

The following example does automatic migration of BROKER1 from V2.1 to Version 6.0:

mqsimigratecomponents BROKER1
BIP 0001I: Starting migration check for component ‘BROKER1’ to FAD level ‘3’
BIP 0002I: ‘BROKER1’ is version 2.1 (auto-detected)
BIP 0003I: Broker database ‘BKRDB’ and schema ‘WMQIUSER’ are not shared with other components.
BIP 0004I: No invalid rows found in broker database.
BIP 0005I: Migration check passed.
BIP 0020I: Starting registry migration for component ‘BROKER1’.
BIP 0021I: Created top-level ‘CurrentVersion’ key
BIP 0021I: Created ‘DSN’ subkey
BIP 0022I: Created ‘HTTPListener’ subkey
BIP 0023I: Created ‘HTTPListener.HTTPConnector’ subkey
BIP 0024I: Created ‘FADLevel’ value; set to ‘3’
BIP 0025I: Created ‘converters’ value; set to ‘’
BIP 0028I: Moving registry data into ‘CurrentVersion’.
BIP 0029I: Moved value ‘AdminAgentPID’.
[repeat for each value]
BIP 0030I: Completed moving registry data into ‘CurrentVersion’.
BIP 0025I: Finished registry migration for component ‘BROKER1’.
BIP 0011I: Starting database table migration for ‘BKRDB’.’WMQIUSER’.
BIP 0012I: Moving table ’BROKERRESOURCES’ to ’somethingBROKERRESOURCES’.
BIP 0013I: Creating new table ’BROKERRESOURCES’.
BIP 0014I: Copying data from ‘somethingBROKERRESOURCES’ to ’BROKERRESOURCES’.
BIP 0015I: Successfully copied all data (322 rows).
 [repeat for each table]
BIP 0016I: Finished database table migration for ‘BKRDB’.’WMQIUSER’.
BIP 0017I: Starting queue migration for ‘BKRQM’.
BIP 0018I: Creating new queue ‘SYSTEM.BROKER.AGGR.CONTROL’.
BIP 0018I: Creating new queue ‘SYSTEM.BROKER.AGGR.REPLY’.
BIP 0018I: Creating new queue ‘SYSTEM.BROKER.AGGR.REQUEST’.
BIP 0018I: Creating new queue ‘SYSTEM.BROKER.AGGR.TIMEOUT’.
BIP 0018I: Creating new queue ‘SYSTEM.BROKER.AGGR.UNKNOWN’.
BIP 0018I: Creating new queue ‘SYSTEM.BROKER.INTERBROKER.MODEL.QUEUE’.
BIP 0018I: Creating new queue ‘SYSTEM.BROKER.TIMEOUT.QUEUE’.
BIP 0018I: Creating new queue ‘SYSTEM.BROKER.WS.ACK’.
BIP 0018I: Creating new queue ‘SYSTEM.BROKER.WS.INPUT’.
BIP 0018I: Creating new queue ‘SYSTEM.BROKER.WS.REPLY’.
BIP 0026I: Clearing queue ‘SYSTEM.BROKER.ADMIN.QUEUE’.
BIP 0026I: Clearing queue ‘SYSTEM.BROKER.EXECUTIONGROUP.QUEUE’.
BIP 0026I: Clearing queue ‘SYSTEM.BROKER.EXECUTIONGROUP.REPLY’.
BIP 0026I: Clearing queue ‘SYSTEM.BROKER.IPC.QUEUE’.
BIP 0019I: Finished queue migration for ‘BKRQM’.
BIP 0005I: Migration succeeded for component ‘BROKER1’.
BIP 8071I: Successful command completion.

The following example is a repeat of the preceding example, but with the -q flag specified:

mqsimigratecomponents -q BROKER1
BIP 0001I: Starting migration check for component ‘BROKER1’ to FAD level ‘3’
BIP 0002I: ‘BROKER1’ is version 2.1 (auto-detected)
BIP 0005I: Migration check passed.
BIP 0020I: Starting registry migration for component ‘BROKER1’.
BIP 0025I: Finished registry migration for component ‘BROKER1’.
BIP 0011I: Starting database table migration for ‘BKRDB’.’WMQIUSER’.
BIP 0016I: Finished database table migration for ‘BKRDB’.’WMQIUSER’.
BIP 0017I: Starting queue migration for ‘BKRQM’.
BIP 0019I: Finished queue migration for ‘BKRQM’.
BIP 0005I: Migration succeeded for component ‘BROKER1’.
BIP 8071I: Successful command completion.