IBM Integration Bus, Version 9.0.0.8 Operating Systems: AIX, HP-Itanium, Linux, Solaris, Windows, z/OS

See information about the latest product version

mqsimigratecomponents command

Use the mqsimigratecomponents command to migrate a component from one version of the product to another version on the same computer.

Supported platforms

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

Purpose

Migrate components to IBM® Integration Bus Version 9.0 from a previous version:
  • If you are migrating from Version 6.1 you must have installed Version 6.1.0.3 (Fix Pack 3) or later.

    If you are using WebSphere® Application Server with WebSphere Message Broker, or you have publish/subscribe applications that use the SubIdentity option, you must upgrade WebSphere Message Broker Version 6.1 to Fix Pack 4 before you can migrate to IBM Integration Bus Version 9.0.

You can also use the mqsimigratecomponents command to return a broker from IBM Integration Bus Version 9.0 to WebSphere Message Broker Version 8.0 or WebSphere Message Broker Version 7.0 to reverse the effects of forward migration. You cannot use the mqsimigratecomponents command to return a broker from IBM Integration Bus Version 9.0 to WebSphere Message Broker Version 6.1. You can restore a WebSphere Message Broker Version 6.1 environment only from a back-up.

When you restore a broker to Version 8.0 or Version 7.0, changes that you made to the broker's state that are compatible with your target version are kept. However, changes that you made that are not compatible with your target version are not reflected in the restored broker's state, which might cause errors.

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

You must have an installation of the product at both target and source versions, with the required component code installed, to issue this command successfully.

Before you start migration, stop the broker and all active debug sessions in the IBM Integration Toolkit. You cannot migrate message flows that are being debugged.

Specify appropriate options on this command to perform one of the following actions:
  • Check that the component is suitable for the required migration, without changing that component (-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 was successful (-v).

Usage notes

If you specified a data source user ID and password on the mqsicreatebroker command for the broker that you are migrating, the values of these parameters are also migrated and saved in the format that is used by the mqsisetdbparms command. The values are used by the broker to access databases for which you did not set alternative values by using the mqsisetdbparms command. After migration, if you want to change the user IDs or passwords that the broker uses to access databases, you can use only the mqsisetdbparms command.

If you update the user ID and password values, and you migrate the broker back to the previous version, the new values are also migrated back to the original broker.

Syntax

Read syntax diagramSkip visual syntax diagram
                          .-| Move |---.                      
>>-mqsimigratecomponents--+-| Check |--+----ComponentName------->
                          +-| Undo |---+                      
                          '-| Verify |-'                      

>--+-----+-----------------------------------------------------><
   '- -q-'   

Check

|-- -c --+--------------------+--+--------------------+---------|
         '- -s--SourceVersion-'  '- -t--TargetVersion-'   

Move

   .-------------.                           
   V             |                           
|----+---------+-+--+--------------------+---------------------->
     +- -1-----+    '- -s--SourceVersion-'   
     +- -2-----+                             
     |     (1) |                             
     '- -3-----'                             

>--+--------------------+---------------------------------------|
   '- -t--TargetVersion-'   

Undo

        .-------------.                       
        V             |                       
|-- -u----+- -1-----+-+-- -s--SourceVersion--------------------->
          +- -2-----+                         
          |     (1) |                         
          '- -3-----'                         

>-- -t--TargetVersion-------------------------------------------|

Verify

|-- -v--+--------------------+----------------------------------|
        '- -t--TargetVersion-'   
Notes:
  1. Valid only for forward migration to Version 9.0.

Parameters

-c
(Optional) Check a specified component before migration to ensure that the following are true:
  • The auto-detected version of the broker matches any version that is specified on the command line.
  • Any database tables that are accessed in a previous release do not contain any rows that are incorrectly indexed.

You can check a running component. The check does not affect the component, apart from a slight degradation of performance.

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.

The -c and -v parameters are mutually exclusive. Additionally, if you specify either of these parameters, you cannot specify any other parameter when you run this command.

-v
(Optional) Check a specified component after migration to ensure that the following are true:
  • The registry is in the correct format for the new version.
  • The correct queues exist for the new version.

The -c and -v parameters are mutually exclusive. Additionally, if you specify either of these parameters, you cannot specify any other parameter when you run this command.

-q

(Optional) Print fewer status messages during the operation.

-1
(Optional) Do only registry and file system work.
  • When you migrate to Version 9.0, use the -1 parameter before the -2 or -3 parameters.
  • When you migrate backwards from Version 9.0 to a previous version, use the -2 parameter before the -1 parameter.
-2

(Optional) Do only WebSphere MQ work.

-3
(Optional) Do only database work.

This option is valid only for forward migration to Version 9.0.

-u
(Optional) Undo a failed migration step; you must also specify at least one of -1, -2, or -3. Use this option only when the migration failed, and also failed to auto-recover (for example, if a failure occurs during split migration).

-3 is valid only for forward migration to Version 9.0.

-s SourceVersion
(Optional) The previous version of the component.
  • If not specified, this value is detected automatically.
  • When you perform split migration to Version 9.0, 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 9.0 to a previous version, the -t parameter is mandatory.
  • 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

For information about platform-specific authorizations, see the following topics: If you have enabled broker administration security, you must also set up the authority detailed in Tasks and authorizations for administration security.

The mqsimigratecomponents command updates your registry, file system, and WebSphere MQ definitions.

If the user ID used to run this command does not have the authority to perform all these steps, you can run the command 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 by using the -1, -2, and -3 parameters.

If you run single-step migration, your user ID must be able to complete the following actions:
  • Write to the registry and the file system for the product
  • Modify queue definitions
  • Read from the database that is associated with the broker, if you are migrating from Version 6.1

If you run split migration, your user ID must always be able to read from the registry for the product.

If you are doing a backward split migration of the registry, the integrity check that verifies the levels of both WebSphere MQ and the database requires your user ID to have the following rights:
  • WebSphere MQ authority to open the SYSTEM.BROKER.* queues.
The following specific authorization for each step is required for the migration to succeed:
  • -1 requires the ability to write to the registry and the file system for the product, SELECT from the broker database tables if you are migrating from Version 6.1, and open the SYSTEM.BROKER.* queues
  • -2 requires the ability to modify queue definitions
  • -3 requires the ability to read from databases that are associated with the broker, if you are migrating from Version 6.1

Responses

This command can produce many 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 when they are generated, rather than being reported in a batch at the end of the program.

When you migrate database tables from Version 6.1, z/OS produces more output than distributed systems. Use the -q parameter to reduce the number of messages displayed.

Examples

The following example shows a split migration from Version 8.0 to Version 9.0:

mqsimigratecomponents BROKER1 -1
mqsimigratecomponents BROKER1 -2
mqsimigratecomponents BROKER1 -3

The following example shows a migration from Version 9.0 back to Version 8.0:

mqsimigratecomponents MYBROKER -t 8.0.0.2
Related tasks:
Migrating
an26150_.htm | Last updated Friday, 21 July 2017