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".
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:
repos_copy -sWICS -oRepository430.txt -uadmin -pnull
For 4.1.1 the repos_copy utility creates a backup of the respository objects in a *.txt or *.in file.
For 4.2.2 and later versions the repos_copy utility creates a backup of the respository objects in a *.jar file.
ProductDir\mqseries\crossworlds_mq.tst
IBM recommends taking a system backup of the entire InterChange Server product directory.
Table 15 summarizes how to back up the different ICS
components.
Table 15. Backup methods for InterChange Server data
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:
See the System Administration Guide for more information about how to stop a running system gracefully.
The following steps list the proper order of uninstalling third-party software.
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.
The following steps list the proper order of installing the components of InterChange Server.
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.
When you upgrade WebSphere MQ, you can take either of the following paths:
When you install WebSphere 5.3, make sure you choose the Custom install and the option to include Java Messaging. If you choose Typical, the required Java messaging files are not installed. For detailed instructions, see Installing WebSphere MQ.
For detailed instructions, see Upgrading WebSphere MQ.
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.
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:
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.
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..
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.
Refer to Upgrading server scripts and Completing component upgrades for additional upgrade information.
Notes:
Make sure that Queue Manager and the Listener are both up and running.
For instructions on how to start InterChange Server, refer to "Setting up InterChange Server".
You can check the InterchangeSystem.log file in the ProductDir directory to confirm a successful startup.
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.
If you are upgrading from ICS 4.1.1 do the following steps to upgrade old DLMs and collaborations for tools.
For more information on ICL see Importing to an ICL.
These steps are not necessary for version 4.2.x servers.
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:
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:
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:
For example, if you have any customized data handlers, add their .jar files in the CLASSPATH variable.
Once you have completed the upgrade process and its testing, you can remove the -design option from the server startup so that InterChange Server starts in production mode.
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
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.
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.
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:
For any particular ICS component you chose to install (that is not separately installed), Installer automatically copies the appropriate input files into the ProductDir\repository directory. These input files contain the repository objects for the new components you have installed as part of your 4.3 release.
If you backed up your ICS repository with repos_copy, you have one or more repository files that contain the repository objects for components from your pre-existing ICS release.
You can use the InterChange Server Component Management view in System Manager to browse the components loaded into the server.
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:
ProductDir\DLMs\classes\NativeMaps
ProductDir\collaborations\classes\UserCollaborations
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.
Each of these steps for handling pre-existing repository objects are described in the sections that follow.
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:
When you import relationships, you must verify that the following attributes for each relationship are valid within the repository file:
If these attributes identify a database that cannot be found during the repos_copy import to the ICS repository, InterChange Server rolls back the entire import operation. However, if you delete the above attributes for each relationship, InterChange Server uses the repository as the default relationship database.
Database connection pools in the 4.1.1 format cannot be imported into the new repository. Therefore, you must delete any connection pools from the repository file. After the ICS instance is upgraded, you must recreate these connection pools within System Manager.
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:
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.
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.