Starting the upgrade process

After the system is in a quiescent state and backed up, you can safely start the upgrade procedure.

Note:
It is not required to uninstall the older version of InterChange Server before installing version 4.3, but it is perfectly acceptable to do so at this stage. Refer to Uninstalling InterChange Server for details. If you choose not to uninstall at this time, it is advisable to remove the older version after you have finished the upgrade because the associated files are large. You should use a different directory for the 4.3 installation even if you choose to uninstall at this stage.
Upgrading the system involves the following tasks:

Importing the database

If you upgraded your database arrange for the DBA to import the saved database information, including schema information and stored procedures. Consult your database server documentation for instructions.

Installing the new version of InterChange Server

After you have backed up your pre-4.3 installation, you are ready to install the new version of InterChange Server. To install the new version of InterChange Server, see Installing InterChange Server, XML data handler, e-Mail adapter, and other supporting products for instructions.

Notes:

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

  2. When the Installer asks you to name the ICS instance, make sure this name of the ICS instance is the same as your previous version to ensure the portability of failed events. This step is unnecessary if your are performing in-place migration of the database.

  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:

Configuring the Object Request Broker

If you are upgrading from a 4.2.2 version of InterChange Server, you do not need to configure the Object Request Broker. Proceed to the instructions inUpgrading server scripts.

As of the 4.2.2 release of InterChange Server, the VisiBroker ORB has been replaced by the IBM Java ORB. As described in Upgrading hardware and supporting software, the ICS Installer automatically installs the IBM Java ORB and the IBM Transient Naming Server as part of the ICS installation process. However, you must ensure that the IBM Java ORB is configured properly by performing the following tasks:

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 32 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.2.2 installations that reference VisiBroker ORB properties, substitute them with their IBM ORB equivalents listed below in Table 32.

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

Table 32. 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. For 4.3 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. For 4.3, 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 can improve performance. The default is 2048.

Identifying registered ICS ORB components

In pre-4.2.2 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.

Upgrading high-availability (HA) features

As of the 4.2.2 release of InterChange Server, the IBM Java ORB replaced the VisiBroker ORB. With this change, the Transient Naming Server replaced the VisiBroker Smart Agent, which was previously used for HA. For more information about configuring the IBM ORB for the HA environment, see Installing and Configuring the Object Request Broker (ORB).

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

As of the 4.2.2 release of InterChange Server, all startup scripts were changed to accommodate the move from the VisiBroker ORB to the IBM Java ORB and support for the IBM JRE.

If you have customized any server startup scripts and you are upgrading to 4.3 from a release other than 4.2.2, you must make similar changes to the new scripts. You might need to make the following customizations to these startup scripts:

Note:
The Integrated Test Environment is now accessed by a simple startup command. Set ICS to test mode by adding the -test option to the startup line in the server startup script. More details can be found in the Implementation Guide for WebSphere InterChange Server.

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 on the Windows machine running your Tools:

ProductDir\bin

Verifying the environment variables

All system environment variables are set in a single CWSharedEnv.sh 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.sh 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 will need to alter neither event tables nor triggers in any way if the schema has not changed.

Starting the new upgraded version

After the installation completes, you can start the new version of InterChange Server using your existing version of the repository, provided that all of the required supporting software is running. If you have upgraded with in-place upgrade of the database you must point ICS to the original repository. To start up ICS, follow these steps:

  1. It is advisable, but not strictly necessary to reboot the machine.
  2. If you are installing with in-place upgrade of the database, you reuse the previous server configuration file, InterchangeSystem.cfg. If you are not upgrading the database in-place, use the new configuration file generated by the installer. If you are using the previous configuration file, copy the old configuration file to ProductDir directory of the new installation. If you are using the new configuration file, use the Server Configuration wizard to change the settings appropriately. Please make sure that the server name is the same as the previous server installation if you want to upgrade failed event from the old ICS.
  3. Ensure that all required supporting software is running. Supporting software includes the following:

    For instructions on how to verify that supporting software is running, refer to Starting supporting software and Starting the IBM ORB Transient Naming Server.

  4. Start InterChange Server.

    For instructions on how to start InterChange Server, refer to Starting InterChange Server and Starting System Manager.

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.

Upgrading the repository

The InterChange Server repository is a database that holds metadata about InterChange Server components. You can perform the upgrade with in-place database upgrade or without. The 4.3 ICS Installer does not automatically upgrade the contents of your ICS repository. However, if in-place upgrade is used then 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:

Important:
If you are upgrading without in-place upgrade of the database, load the new 4.3 repository with the pre-existing repository objects. For more information, see Loading pre-existing repository objects.

You can use the InterChange Server Component Management view in System Manager on a connected Windows machine to browse the components loaded into the server.

Loading pre-existing repository objects

The steps described in this section are required only if you are upgrading InterChange Server without in-place upgrade of the database.

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 databases that 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.
    2. Clear the repository of any repository objects.
    3. Load the pre-existing objects.

    Each of these steps to loading the repository is described in the sections that follow.

Preparing the repository file

The steps in this section are required only if you are upgrading from version 4.1.1.

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 -ppasswd -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 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:
In the 4.1.1 version of the InterChange Server the project definitions were stored in the repository. In the 4.3 version of InterChange Server, project definitions are no longer stored in the repository. They are now defined through Integration Component Libraries (ICLs) and user projects. The import operation loads all repository objects defined in the repository file except any project definitions. For more information, see the System Installation Guide for Windows.

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:

After 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