Upgrading from Host Integrator 5.5 to 6.0

Note: This information applies to upgrades from two prior releases and is included for users migrating directly from version 5.5 to 6.5. You should also review the migration information specific to version 6.5.

If you are upgrading to Verastream Host Integrator 6.0 from 5.5, please read this section fully to understand how to upgrade your settings and files to version 6.0. See What's New in Version 6.0 for a list of new features. See Linux/UNIX upgrade notes if you have Host Integrator servers for these platforms.

Although the Setup program is able to detect and save your current configuration and migrate its settings to version 6.0, you should review your configuration thoroughly after upgrading to be sure that the migration was successful. Use the information in this section to plan your upgrade to Verastream Host Integrator version 6.0.

Upgrading from 5.0

These instructions also apply if you are upgrading from Host Integrator version 5.0 to version 6.0. See the following topics for additional details related to this upgrade path:

What's New in Version 5.5

Upgrading from Version 5.0 to version 6.0

Upgrade Sequence

Upgrade your components in this order:

  1. Authentication, Administration, and Directory Services (AADS)
  2. Administrative WebStation
  3. Host Integrator Session Servers
  4. Host application models
  5. Client applications

Review these upgrade issues:

Component Migration

This section briefly describes each component and explains how to migrate its settings to Host Integrator version 5.5.


AADSs

You must upgrade your AADSs to version 6.0 before you install Host Integrator 6.0 Administrative WebStations or servers. The Host Integrator 5.5 Setup program can detect the presence of a 5.5 AADS and back up and upgrade its configuration to AADS 6.0. More Information...

Administrative WebStations

Upgrade your Administrative WebStations after you upgrade AADS. Because the Administrative WebStation is not compatible with an AADS of a different version, you should keep at least one 5.5 version of the Administrative WebStation if you plan to keep a 5.5 AADS. The Host Integrator 6.0 Setup program can detect the presence of version 5.5 Administrative WebStations and back up and upgrade its configuration to version 6.0. More Information...

Host Integrator Session Servers

Upgrade your Host Integrator Session Servers to version 6.0 after you upgrade your AADSs and Administrative WebStations. The Host Integrator 6.0 Setup program can detect the presence of 5.5 servers and back up and upgrade their configurations to version 6.0. More Information...

Host Application Models

Your deployed 5.5 models will continue to function on a 6.0 Session Server. No manual upgrade is required.

To upgrade a model, open and save a 5.5 model in the Design Tool. Once you convert a model file to version 6.0, it can no longer be loaded on a 5.5 server. Save the model only after you have verified that it behaves as you expect. For example, in certain cases it may be necessary to delete a pattern and re-add it. You should also verify that other aspects of the model, such as operations, recordsets, and procedures, behave correctly before you save the model.

Changes in Host Integrator that could affect your model upgrade are disabled in a series of compatibility settings. More information...

Client Applications

It is recommended that you install the new AppConn connector files on machines running client applications. You may be able to continue to use the old connector; however, if you see an "Undefined error message," this indicates that a connector upgrade is required. The error message may also include an error number that can provide further information. Open the error messages topic and look for the listed error number.

If you install the 6.0 AppConn connector on machines running client applications, allow the Setup program to complete the installation and create registry entries (if necessary). Your current client applications will work seamlessly with 6.0 models and servers because the support libraries you link to will be updated by Setup. Be aware that the 6.0 API may contain new methods, so upgrading your client code is to your advantage.

Note: If you have statically linked to any of the AppConn connector files in your applications, you must re-link to the connector files after upgrading to version 6.0 in order to take advantage of any new methods and features.

Upgrading AADS, Administrative WebStations, and Host Integrator Servers

Under Windows, the Setup program will detect the presence of AADS, Host Integrator Session Servers, and Administrative WebStations and offer to backup the configuration information. To upgrade Host Integrator AADS and Servers from version 5.5 to 6.0 under Windows, follow the steps below. The instructions for upgrading Linux/UNIX components include additional steps for this release.

Notes:

To upgrade AADS and Host Integrator Session Servers on a Windows system:

  1. Log in to Windows with Administrative privileges and close all running applications.

  2. Insert the Host Integrator product CD into your CD-ROM drive or locate your e-delivery folder.
  3. If you are uninstalling from another machine on the network and using the CD, you must map a drive to the Host Integrator product CD.

  4. To start the Setup program, click Run on the Start menu, type or browse to the path to the installation program (for example, D:\Setup.exe), and then click OK.
  5. The Setup program evaluates your system for the presence of any 5.5 components and lists these in the Legacy Component Migration dialog box. Click Next.

  6. Select the components whose settings files will be backed up and migrated to version 6.0 and then click Next.

  7. Select a backup directory where the settings files to be migrated will be saved and then click Next.

  8. Save the settings files for the components you selected and then click Exit.

  9. Use Add/Remove Programs from the Control Panel to uninstall Verastream Host Integrator version 5.5.

  10. Install Verastream Host Integrator version 6.0.
  11. For each group of 5.5 settings that you selected to upgrade, the Host Integrator 6.0 Setup program will detect the presence of the backed up files and ask if you want to restore the settings for your 6.0 installation. Follow the prompts.

    Any model you open and save in the Design Tool will be automatically upgraded to 6.0. Deployed models from earlier versions will also continue to function after the Host Integrator server is upgraded to 6.0.

Web Builder Projects

The first time you open Web Builder 6.0, it automatically updates any 5.5 projects so that you can run the applications or use the web services and JavaBeans. You can deploy, undeploy, or delete 5.5 web projects without any upgrade, but they will be updated to version 6.0 when you attempt to modify them.

Web Builder Upgrade Issues

Java Package, Object, and Method Name Compatibility

Java package, object, and method names are generated differently in the Web Builder 6.0 release. These changes may cause a problem if you run the new 6.0 projects with an old client. You may need to generate the new Java project, then alter the client code to use these new object, method, and package names.

.NET 1.1 Projects

Verastream Host Integrator now supports projects using a .NET 1.1 or 2.0 Framework and Visual Studio version 2003 or 2005. If you built projects using .NET 1.1 and you want to move to .NET 2.0, you should rebuild the project. If you have more than one version of .NET on your machine, .NET 2.0 will be the default for any new projects. You can continue to use .NET 1.1 by changing this setting in the Web Builder Microsoft Tools settings.

Web Services Compatibility

An existing generated web service, and its clients, will continue to run correctly under the Verastream Host Integrator 6.0 release. However, if the 5.5 web service is replaced with a 6.0 web service generated from the same model, you may need to update your client code to use new web service standards. Verastream Host Integrator 6.0 uses a new version of Apache Axis, which includes new web service standards and implementations. Review the WSDL for any changes or updates that may affect the client applications.


.NET Error Message "Type Library not registered"

If you have an existing .NET project (such as C# web service) used with a prior version of Verastream AppConn for COM (appconn.dll), after upgrading to version 6.0, the Microsoft Visual Studio .NET development environment may show the appconnlib reference is invalid and/or the type library is not registered (even though no runtime incompatibility occurs with the 5.5 connector used with a 6.0 server). To allow your project to re-compile, delete the invalid reference and re-add the COM reference to appconn.dll (now named Attachmate Verastream Host Integrator 6.5 in the list of COM libraries).

Build Fails When Renaming or Deleting Procedures

When rebuilding a .NET or Java procedure-based web application, you may get an error if you have renamed or deleted procedures in the model. To correct this, you can either:

Upgrading to a Different Folder

If you upgrade Host Integrator into a different folder from the original installation, 5.5 Web Builder projects may not be upgraded to version 6.0.

New Settings and Requirements

Upgrading Event Handlers

Event handlers were introduced in version 5.5. Previously, models referencing non-existent Java classes as event handlers were allowed to load and run until the reference to the missing class was found. In this release, these models are now considered invalid. They can be opened in the Design Tool, but they cannot be deployed until the problem is addressed.

If you find a model with this problem, you can correct it by doing the following before or after your upgrade:

  1. Use the Design Tool to either remove the reference to the missing Java class, or define the missing class in one of the model's event handler library jars and then rebuild the event handler.
  2. Save the model in the in the Design Tool.
  3. Redeploy the model to the server.

Although this can be done before or after upgrade, it's best to do this before upgrading a production server if possible.

Compatibility Settings for Host Integrator 4.5, 5.0, and 5.5

When you open a model created in an earlier version of the Design Tool, you'll see the following message noting that "This model was created with a prior version of the Verastream Host Integrator." The compatibility settings described below are enabled to allow your models to maintain the same behavior as they had in an earlier version of Host Integrator.

Review the compatibility settings and consider disabling these settings in order to take full advantage of current product functionality. In most cases, you will not see any changes in the behavior of your model. If you do note a change, use the guidelines included in the settings descriptions below to make any necessary modifications. You can also re-enable a compatibility setting at any time. To view compatibility settings, select View Settings from the Settings menu, then open the Compatibility category.