Preparing the existing ICS system

In preparing your ICS system for an upgrade, you have two options for migrating your ICS database, an in-place database migration and a without in-place database migration. An in-place database migration means re-using the old repository and letting ICS do the upgrade of the repository during the first ICS server startup. A without in-place database migration means upgrading with a brand new and empty repository database.

The upgrade of the InterChange Server system using a without in-place database migration involves the following steps. If using an in-place database migration the changes in the instructions are flagged as "in-place database migration".

  1. Step 1 - Backing up the InterChange Server system
  2. Step 2 - Putting the system in a quiescent state
  3. Step 3 - Uninstalling InterChange Server and Third-Party software
  4. Step 4 - Installing InterChange Server and Third-Party software
  5. Step 5 - Upgrading the Object Request Broker
  6. Step 6 - Upgrading InterChange Server
  7. Step 7 - Start InterChange Server and Third-Party software
  8. Step 8 - Load the Repository
  9. Step 9 - Special upgrade procedures in migrating from Version 4.1.1
  10. Step 10 - Validate the upgrade

Step 1 - Backing up the InterChange Server system

Backing up the InterChange Server system allows you to recover any files that might be overwritten inadvertently during the installation of the new version. Before performing the upgrade procedure, back up both static data and dynamic data (changeable data that you back up on a regular basis, regardless of upgrades). For examples of static and dynamic data, see Table 15.

To back up the system, do the following:

Table 15 summarizes how to back up the different ICS components.

Table 15. Backup methods for InterChange Server data

Type of data Backup method
Static data

Repository
Use the repos_copy utility to save some or all of the customized InterChange Server components. For more information, see the description of how to back up InterChange Server components in the System Administration Guide.

Custom collaboration Java class files (.class), and message files (.msg) Include the collaborations subdirectory of the ProductDir directory in your system backup:
ProductDir\collaborations 

Custom map Java class files (.class)
To include these files in your system backup, make sure the following directory is in your system backup:
ProductDir\DLMs

Custom connectors Include the following directory in your system backup: ProductDir\connectors\connector_name, where "connector_name" is the name of the custom connector.

Customized startup scripts If you have customized any startup scripts, make sure that they are included in your system backup.

ICS configuration file (InterchangeSystem.cfg) Include in your system backup the ICS configuration file, which resides in the ProductDir directory.
Dynamic data

Cross-reference, failed events, and Relationship tables Use the database backup utility for the database. For more information, see the description of how to back up InterChange Server components in the System Administration Guide.

Connector event archive tables Use the database backup utility for the database that contains these tables.

Log files Include the following directory in your system backup:
ProductDir

Step 2 - Putting the system in a quiescent state

Before you upgrade your InterChange Server system to version 4.3, you must make sure that the system is in a quiescent state. This means that all in-progress events should be completed and all in-doubt transactions are resolved before backing up the environment and performing the upgrade procedure.

The following steps describe how to put the InterChange Server system in a quiescent state:

  1. Resubmit failed events or discard the events (this step is optional). You can choose to upgrade failed events to ICS and process it after the system is upgraded.
  2. Stop all adapters from polling the event tables by setting the PollFrequency property to No
  3. Let all events run through the system, including all in-process events. All in-doubt transactions must been resolved.
  4. Stop the collaborations. This task ensures that no events are running through InterChange Server during the upgrade.
  5. Clear the queues by removing any old events from the queues.
    Note:
    Perform step 5 only if you are not processing your failed events and choose to resubmit the events from the application. If you choose to upgrade failed events and you are using MQ transport, DO NOT clear the queues. You should backup the queues and restore them after upgrading. See the MQ docomentation on backing up queues.
  6. Shut down InterChange Server and all its related components.
  7. Shut down your database.
  8. Shut down the ORB (Visibroker) for ICS versions prior to 4.2.2.
  9. Shut down MQSeries.

See the System Administration Guide for more information about how to stop a running system gracefully.

Step 3 - Uninstalling InterChange Server and Third-Party software

The following steps list the proper order of uninstalling third-party software.

  1. Uninstall the ORB (Visibroker) (for versions earlier than 4.2.2)
  2. Uninstall InterChange Server (ICS)
  3. Uninstall JDK
  4. Drop your repository tables . The tables are rebuilt as part of the ICS upgrade.
    Note:
    For in-place database upgrade you do not drop the repository tables since you will re-use the repository in the new installation.

If any InterChange Server components are running as services, uninstall those services before performing the upgrade. Because the new release will reside in a different location, existing service definitions will be incorrect. When the upgrade is complete, see "Advanced configuration options" for instructions on configuring InterChange Server components as services.

Step 4 - Installing InterChange Server and Third-Party software

The following steps list the proper order of installing the components of InterChange Server.

Important:
If you must upgrade any third-party software, be sure to arrange for a System Administrator to back up the software before upgrading.
  1. Install IBM JDK 1.4.2.
  2. Install or upgrade the DBMS and restore the runtime tables if you want to keep the runtime data.

    If you are migrating from an earlier version of InterChange Server, check to see if you must also upgrade your database software. Consult the Software requirements section (see Software requirements ) for the list of supported database software. Compare the version of your existing database software with the version that the 4.3 version of the product supports .

    If you must upgrade your database software, make sure the database administrator (DBA) takes the following steps:

    Consult your database server documentation for instructions on how to perform backups and upgrade database software. For more information on how to migrate the database, proceed to Step 8 - Load the Repository.

  3. Install or upgrade to WebSphere MQ 5.3.02 (CSD07).
    Important:
    The need to perform the steps in this section depends on the version of your current InterChange Server:
    • If you are upgrading from a 4.2.0, 4.2.1 or 4.2.2 version of InterChange Server, you are not required to upgrade WebSphere MQ.
    • If you are upgrading from a 4.1.1 version of InterChange Server, perform the steps in this section to migrate WebSphere MQ to the new version.

    When you upgrade WebSphere MQ, you can take either of the following paths:

    Once you have upgraded the WebSphere MQ software, you need to configure it for use with InterChange Server. For more information, see the description in Configuring WebSphere MQ.

  4. Install InterChange Server in a new directory other than the directory in which the previous version of ICS resides.

Step 5 - Upgrading the Object Request Broker

The WebSphere InterChange Server system no longer uses the VisiBroker Object Request Broker (ORB) to handle communication between ICS and its clients (such as connectors, WebSphere Business Integration tools, SNMP agents, and access clients). Instead, the InterChange Server system now uses the IBM Java ORB. The ICS Installer automatically installs the IBM Java ORB as part of the Java Runtime Environment (JRE).

InterChange Server now uses the IBM Transient Naming Server instead of the VisiBroker Smart Agent to provide its naming service. To upgrade your system to use the new naming server, do one of the following, depending on whether the VisiBroker Smart Agent is installed on the same host machine as the IBM Transient Naming Server and must remain on this same host machine:

Note:
For a general overview of the IBM Java ORB, see the System Administration Guide.

Use of properties to set up the IBM Java ORB has been set in the startup scripts that installation provides. However, if your pre-4.3 version of InterChange Server used the Inprise VisiBroker software and you customized any VisiBroker ORB properties, you might need to make similar changes to the new scripts to accommodate the 4.3 migration to the IBM ORB. For more information on IBM ORB properties and their VisiBroker equivalents, refer to Upgrading ORB properties.

Upgrading ORB properties

Various ORB-related properties were present in the VisiBroker ORB for tuning the ORB. If you have used these properties in any customized scripts or software, you must verify that they are set for the IBM Java ORB appropriately. Table 16 lists some of the VisiBroker ORB properties and their equivalent names in the IBM Java ORB.

If you have any customized scripts from pre-4.3 installations that reference VisiBroker ORB properties, substitute them with their IBM ORB equivalents listed below in Table 16..

Note:
Line breaks have been inserted in some of the property name in Table 16 to enable the names to fit into the table cells. The actual property names do not include spaces or line breaks.

Table 16. IBM ORB properties and their VisiBroker equivalents

IBM ORB properties Equivalent VisiBroker properties Description
org.omg.CORBA.ORBInitialHost vbroker.agent.addr Specifies the IP address or host name of the machine running the IBM Transient Naming Server (tnameserv). The default value for this property is localhost.
org.omg.CORBA.ORBInitialPort vbroker.agent.port Specifies the port on which the IBM Transient Naming Server listens.
com.ibm.CORBA.ListenerPort vbroker.se.iiop_tp.scm.iiop_tp. listener.port The port on which the ORB server will listen for incoming requests. If this property is specified, the ORB will start listening during ORB.init(). By default, this port is dynamically assigned. The VisiBroker property name OAport will continue to be supported.
com.ibm.CORBA.LocalHost vbroker.se.iiop_tp.host This property represents the host name (or IP address) of the machine that the ORB is running on. The local host name is used by the server-side ORB to place the sever's host name into the IOR of a remote object. If this property is not set then the local host is retrieved by calling: InetAddress.getLocalHost() .getHostAddress();.
For 4.3, the VisiBroker property name OAipAddr will continue to be supported.
com.ibm.CORBA.ThreadPool. MaximumSize vbroker.se.iiop_tp.scm.iiop_tp. dispatcher.threadMax Specifies the maximum number of threads that the Server Connection Manager can create. The default value 0 implies that there are no restrictions. For 4.3, the VisiBroker property name OAthreadMax will continue to be supported.
com.ibm.CORBA.ThreadPool. InactivityTimeout vbroker.se.iiop_tp.scm.iiop_tp. dispatcher.threadMaxIdle Specifies the amount of time (in seconds) before an idle thread will be destroyed. The VisiBroker property name of OAthreadMaxIdle will continue to be supported.
com.ibm.CORBA.BufferSize vbroker.orb.streamChunkSize The number of bytes (as a GIOP message) that will be read from a socket on the first attempt. A larger buffer size increases the probability of reading the entire message in one attempt, which may improve performance. The default is 2048.

In pre-4.3 versions of InterChange Server, the VisiBroker ORB provided the osfind tool to identify all ORB objects registered with InterChange Server. The IBM Java ORB provides a tool called CosNameServer_Dump for this purpose. This tool is located in the ProductDir\bin directory. For more information, see the System Administration Guide.

Step 6 - Upgrading InterChange Server

Refer to Upgrading server scripts and Completing component upgrades for additional upgrade information.

Notes:

  1. During an upgrade, you must install the new version to a different location.

  2. When the Installer asks you to name the ICS instance, make sure this name of the ICS instance is the same as your pre-4.3 version to ensure the portability of failed events.

  3. To obtain your original InterChange Server configuration information, you can take one of the following actions when the Installer brings up the InterChange Server Configuration wizard:

Step 7 - Start InterChange Server and Third-Party software

  1. Reboot the InterChange Server machine.
  2. Start the IBM ORB's Persistent Naming Server by running the batch file PersistentNameServer.bat located in the ProductDir\bin directory.
  3. Start IBM MQSeries.

    Make sure that Queue Manager and the Listener are both up and running.

  4. Start the database, if you are running it locally.
  5. If upgrading from 4.1.1 copy the .class, .java and message files backed up previously for DLMs and collaborations to appropriate directories. For DLMs, copy files to ProductDir\DLMs\classes and ProductDir\DLMs\messages. For collaborations, copy files to ProductDir\collaborations\classes and ProductDir\collaborations\messages.
  6. For in-place database migration: You must point the ICS to the database where the original repository resides. You can do this either by reusing the old InterchangeSystem.cfg file or setting the database parameters through the ICS configuration wizard.
  7. Start InterChange Server.

    For instructions on how to start InterChange Server, refer to "Setting up InterChange Server".

    Note:
    The server name must be the same as the previous version to ensure the portability of failed events.

    You can check the InterchangeSystem.log file in the ProductDir directory to confirm a successful startup.

    Note:
    If InterChange Server fails to start up after you upgrade the InterChange Server system, review this upgrade procedure to be sure you followed all the instructions. If the cause of the failure is still unknown, consult IBM technical support for assistance before attempting adjustments or restoring from backup.

Step 8 - Load the Repository

Note:
This step is not necessary if doing an in-place database upgrade.

Load the repository file from the previous version using the repos_copy command. For example, enter the following if the ICS name is WICS with a username/password of admin/null and a repository file name of repos_backup.jar ( use repos_backup.in if upgrading from 4.1.1)

repos_copy -sWICS_NAME -irepos_backup.jar -uadmin - pnull

See Upgrading the repository for more information on repository.

Step 9 - Special upgrade procedures in migrating from Version 4.1.1

If you are upgrading from ICS 4.1.1 do the following steps to upgrade old DLMs and collaborations for tools.

  1. Reboot the server you just installed.
  2. In System Manager, connect to the server.
  3. Create a temporary ICL (Integration Component Library) and import all components from the server.
  4. Compile all the maps and collaborations templates.
  5. Create a project and include all components from the ICL previous created.
  6. Delete the repository on the server.
  7. Deploy the project onto the server.

For more information on ICL see Importing to an ICL.

These steps are not necessary for version 4.2.x servers.

Step 10 - Validate the upgrade

To validate the success of the upgrade, you must ensure that the repository schema was created and that all objects were loaded successfully. To do this validate the following:

Upgrading server scripts

If you have created custom files in your pre-existing InterChange Server system, you need to assess the following files to determine whether they require upgrading:

Upgrading server startup scripts

All startup scripts have been changed to accommodate the move from the VisiBroker ORB to the IBM Java ORB and support for the IBM JRE. These changes include:

If you have customized any pre-4.3 startup scripts, you must make similar changes to the new 4.3 scripts. You might need to make the following customizations to these startup scripts:

Upgrading the tool-configuration file

One of the tasks of the tool-configuration file, cwtools.cfg, is to provide custom .jar files to be included at compile time. If you have created custom .jar files, you must add these custom files to the codeGeneration section, in the classpath variable. The cwtools.cfg file is located in the following directory:

ProductDir/bin

Verifying the environment variables

All system environment variables are new set in a single CWSharedEnv file. All startup scripts read this file as part of their invocation procedure. It is in this file that ICS-system-wide properties (such as those for the IBM Java ORB) are set. As part of your upgrade process, make sure that the following system-wide properties are correctly set:

For more information on the CWSharedEnv file, see the System Administration Guide.

Assessing custom components

If you have any completely custom components that use repository tables (such as scripts, database tables, or stored procedures), you must assess each component to determine whether it must be upgraded. For example, if a stored procedure uses a repository table that has changed in the new release, you must modify this stored procedure to work with the new structure of the repository table.

Note:
You should need to alter neither event tables nor triggers in any way if the schema has not changed.

Upgrading the repository

The InterChange Server repository is a database that holds metadata about InterChange Server components. The ICS Installer does not automatically upgrade the contents of your ICS repository. However, when you started ICS in the previous step, ICS upgrades the schema in your pre-4.3 repository with any 4.3 changes. At this point of the upgrade process, you must decide which objects to load in the repository:

You can use the InterChange Server Component Management view in System Manager to browse the components loaded into the server.

Loading pre-existing repository objects

If you are upgrading from a 4.1.1 version of InterChange Server and had to upgrade your database software, your DBA should have installed the new database server and handled any changes needed for the ICS databases, including the ICS repository. As part of the ICS installation process, you specified the names of these ICS databases in the ICS Configuration wizard. When you started the new version of ICS, the server upgraded the schema in the repository database. To initialize this new repository, you must load pre-existing repository objects.

To prepare for loading the repository, take the following steps:

  1. Copy your existing Java class (.class) files for maps and collaborations into the new directory structure:

    where ProductDir is the product directory for the new 4.3 release. This step ensures that the .class files for your existing maps and collaborations reside in the new 4.3 directory structure.

  2. Ensure that all of the databases your ICS system uses for relationships and database connections are running. Also ensure that ICS is running.
  3. Load the pre-existing repository objects with the following steps:
    1. Edit the repository file to fix several incompatibilities. For more information, refer to Preparing the repository file below.
    2. Clear the repository of any repository objects.
    3. Load the pre-existing objects.

    Each of these steps for handling pre-existing repository objects are described in the sections that follow.

Preparing the repository file

Check your existing repos_copy backup file (called a repository file) to ensure that all values are relevant to the new repository. Create a backup copy of your existing repository file and edit the original repository file to fix the following information:

Note:
If you do not want to load all of the repository objects in your file of pre-existing repository objects, you can remove the unwanted objects from the repository file that you import into the 4.3 repository.

Clearing out the new repository

Before you import the pre-existing repository objects, you must delete any duplicate objects that might already exist in the 4.3 repository. This step is necessary because the repos_copy utility does not recognize the -ar or -arp options (which handle duplicate objects) when it imports an older format into the repository. If ICS finds any duplicate objects in the repository file, it rolls back the entire import operation.

To delete these repository objects, use the -d option of the repos_copy utility. For example, the following repos_copy command deletes the contents of the repository:

repos_copy -sNewICSinstance -uadmin -pnull -d 

In the preceding repos_copy command:

Importing the repository file

To load the contents of the repository files into the repository, use the repos_copy utility. As described in Step 1 - Backing up the InterChange Server system, you should have exported your pre-existing repository objects with the -o option of the repos_copy utility to create one or more repository files. You now import these repository objects into the new repository with the -i option of repos_copy.

Note:
The import operation loads all repository objects defined in the repository file except any project definitions. Project definitions are no longer stored in the repository. They are now defined through Integration Component Libraries (ICLs) and user projects. For more information, see Importing existing user projects.

For example, suppose you have the Repository411.txt repository file. The following repos_copy command loads all repository objects within this file:

 repos_copy -iRepository411.txt -sserverName -uuserName -ppassword -r*

In the preceding repos_copy command:

Once the pre-existing repository objects are in the new repository, you must still perform additional steps to complete the upgrade of collaboration templates and maps. For more information, see Completing collaboration template and map upgrades.

Copyright IBM Corp. 1997, 2004