Technical Notes

Upgrading to Host Integrator 6.5 in a Windows Environment
Technical Note 40031
Last Reviewed 23-Feb-2007
Applies To
Verastream Host Integrator version 6.5
Summary

This technical note outlines an upgrade path from Verastream Host Integrator version 5.5 or 6.0 to version 6.5 that enables existing installations to retain as many existing settings and models as possible. Details are provided to upgrade the AADS (Authentication, Administration, and Directory Services), Administrative WebStation, server configuration files, host application models, and Web Builder projects to be compatible with Host Integrator version 6.5 in a Windows-based environment.

See Technical Note 10069 for a list of new features in version 6.5. See Technical Note 10061 for a list of features introduced in version 6.0. See Technical Note 40030 if you have Host Integrator servers for Linux/UNIX platforms.

Although the Setup program is able to detect and save your current configuration and migrate its settings to version 6.5, you should review your configuration thoroughly after upgrading to be sure that the migration was successful.

This technical note addresses these upgrade issues:

Upgrading AADS, Administrative WebStation, and Session Server

Under Windows, the Setup program detects the presence of AADS, Host Integrator Session Server, and Administrative WebStation and offers to backup the configuration information.

To upgrade Host Integrator AADS and Servers under Windows, follow the steps below. See Technical Note 40030 for instructions to upgrade Linux/UNIX components.

Note the following:

• If you are upgrading multiple systems in your installation environment, it is recommended that you backup and uninstall the earlier version (repeat steps 1 through 9 below) on all systems before upgrading all systems to version 6.5.
• It is possible to have different versions of AADS in the same environment, but they will not interact with or be aware of each other.

Preserving Your Existing Settings

1. In the Administrative WebStation:

• Make a note of your current security settings, and then turn off all security.
• Make a note of your Host Integrator domain server settings.

2. Log in to Windows with Administrative privileges and close all running applications.
3. Start the version 6.5 Setup program:

• For Downloaded Product: When you run the downloaded Verastream Host Integrator Windows Server or Development Kit, you are prompted for a Location to Save Files. This is a temporary directory for unpacking the installation files, by default on the local C: drive.

• From the CD-ROM: Click Start > Run, then type or browse to the path to the installation program (for example, D:\Setup.exe), and then click OK.

4. The Setup program checks your system for the presence of any 5.5 or 6.0 components and lists these in the Legacy Component Migration dialog box. Click Next.
5. Select the components whose settings files will be backed up and migrated to version 6.5 and then click Next.
6. Select a backup directory location to save the settings files that will be migrated and then click Next.
7. Save the settings files for the components you selected and then click Exit.
8. If you have been running .NET applications created by VHI Web Builder, see Unlock .NET Files Prior to Uninstalling (later in this note).

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

Note: If you are upgrading multiple systems in your installation environment, it is strongly recommended repeat the above steps 1 through 9 on all systems before proceeding. (Otherwise, you must separately upgrade all AADSs to version 6.5, then upgrade all Administrative WebStations, and then upgrade all Session Servers.)

Restoring Saved Settings Files in your 6.5 Setup

10. Install Verastream Host Integrator version 6.5. You must install to the same directory location that was used by version 5.5 or 6.0.

11. Some server, domain, and security parameters may revert to their default settings after upgrading, so be sure to check your server and domain configurations carefully after installing version 6.5 and restarting the environment. Restore the original configuration you noted in step 1.

Host Application Models

Your deployed 5.5 or 6.0 models will continue to function on a 6.5 Session Server. They are automatically migrated to the <VHI>/deploy directory. No manual upgrade is required.

To upgrade a model created with an earlier version, open and save the model in the Design Tool. Note: Once you convert a model file to version 6.5, it can no longer be loaded on an earlier version 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. For more information see Compatibility Settings for Models Created in Version 4.5, 5.0, or 5.5.

Directory Server Settings

The first time your run the version 6.5 Administrative WebStation and Session Monitor, you will need to assign the AADS, or possibly remove and re-add the AADS.

As of version 5.5, the Session Monitor creates a default security certificate when connecting. This certificate may still be present after uninstalling the previous version of Host Integrator and reinstalling the new version. After the upgrade, the Session Monitor will attempt to use a certificate that is now out of date. When attempting to connect, you'll see messages such as "SSL connection failed. Certificates don't match."

To correct this problem, select Remove Directory Server from the Configure menu. You can ignore additional error messages while doing this operation. Next, select Add Directory Server to add it again with an appropriate security certificate.

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. See the list of error numbers at http://www.attachmate.com/docs/verastream/vhi/6.5/help/designtool/h_rte.html.

If you install the 6.5 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.5 models and servers because the support libraries you link to are updated by Setup. Be aware that the 6.5 API may contain new methods, so upgrading your client code may be 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.5 in order to take advantage of any new methods and features.

The COM connector file name has changed from appconn.dll to appconncom.dll.

Upgrading Web Builder Projects

The first time you open Web Builder 6.5, it automatically updates any 5.5 or 6.0 projects so that you can run the applications or use the web services and JavaBeans. Generally, you can deploy, undeploy, or delete existing web projects created in version 5.5 or 6.0, but they will be updated to version 6.5 when you attempt to modify them. You should be aware of the following issues.

Web Builder Upgrade Issues

Project Type Changes

Some project types are no longer available for creating new projects. For .NET and Java web applications, you no longer need to choose between procedure-based or screen-based (rejuvenation) project types. The web application project types for Java and .NET incorporate the functionality of screen-based or procedure-based project types.

.NET 1.1 Projects

Verastream Host Integrator version 6.5 supports the creation of projects using Microsoft .NET Framework version 2.0 and Microsoft Visual Studio 2005. (VHI version 6.0 supports .NET 1.1 or 2.0; VHI version 5.5 supports .NET 1.1.)

To benefit from Web Builder version 6.5 enhancements (as described in Technical Note 10069), your .NET 1.1 projects need to be re-built as separate new .NET 2.0 projects in Web Builder.

Existing .NET 1.1 projects can continue to run. However, in order to re-build your existing projects using .NET 1.1 in Web Builder 6.5, you must do the following.

• Prior to upgrading VHI to version 6.5, create user-defined project types in Web Builder that are copies of the base .NET 1.1 project types.

• If you have both .NET 1.1 and 2.0 installed, the VHI 6.5 installation will detect .NET 2.0 and configure Web Builder to use it by default. After upgrading, you can modify Web Builder properties so it will build with .NET 1.1.

Unlock .NET Files Prior to Uninstalling

If you have run an existing .NET web application, certain Host Integrator files (such as appconncom.dll and xerces-c_1_4.dll) remain loaded by IIS and locked. Prior to uninstalling your existing version of Host Integrator, reboot the system, or terminate the aspnet_wb process in Windows Task Manager.

Web Services Compatibility

An existing generated web service, and its clients, will continue to run correctly under the Verastream Host Integrator 6.5 release. However, if a 5.5 web service is replaced with a 6.5 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.5 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.5, 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 or 6.0 connector used with a 6.5 server). To allow your project to re-compile, delete the invalid reference and add the COM reference to appconncom.dll (now named Attachmate Verastream Host Integrator 6.5 in the list of COM libraries).

Upgrading ASP Projects

ASP web applications that were created in VHI Web Builder version 5.5 do not run correctly after upgrading to VHI version 6.0 or later. Also, you may encounter an error when attempting to rebuild an existing ASP procedure-based Web application.

To remedy this, use Web Builder to undeploy and rebuild the existing ASP Web application. Undeploy the application before you rebuild it. You may also need to restart IIS prior to rebuilding.

Controlling Element Visibility in Rejuvenation Projects

In versions 5.0 through 6.0, you could use _SHOW or _HIDE appended to the names of model entities, attributes, or procedures to control the display of these elements in web applications generated by Web Builder.

Beginning with version 6.5, instead of using these naming conventions, element visibility is controlled by selecting options in Web Builder's Project Properties dialog box . (When the project is initially converted to version 6.5, the visibility options are set appropriately based on the existing element name _SHOW or _HIDE suffixes.) For more information on configuring projects, see http://www.attachmate.com/docs/verastream/vhi/6.5/help/webbuilder/wb_howto_configure_apps.html.

Java Package, Object, and Method Name Compatibility

Beginning in version 6.0, Java package, object, and method names are generated differently by Web Builder. These changes may cause a problem if you run the new 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.

Java Project Icons Dimmed

After upgrading to Host Integrator version 6.5, deployed Java project icons may appear dimmed (greyed out). To remedy this, in Web Builder, right-click on each project and select Deploy.

Build Fails When Renaming or Deleting Procedures

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

• Delete the web application project, then rebuild it.
• Or, for web application projects that you customized, delete the source files that reference the old procedure names, and then rebuild the project.

Upgrading to a Different Folder

If you install Host Integrator into a different folder from the original earlier installation, Web Builder projects may not be upgraded to version 6.5.

Upgrading Event Handlers From Version 5.5

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.

Beginning in version 6.0, such models are 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. Then, rebuild the event handler.
2. Save the model in the Design Tool.
3. Redeploy the model to the server.

Note: Although this can be done before or after upgrade, it's best to resolve the missing Java class before upgrading a production server.

Compatibility Settings for Models Created in Version 4.5, 5.0, or 5.5

When you open a model created in an earlier version of the Design Tool, you'll see a message noting that "This model was created with a prior version of the Verastream Host Integrator." The compatibility settings described in Technical Note 40023 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 to make any necessary modifications. You can also re-enable a compatibility setting at any time. To view compatibility settings, select Settings > View Settings; then open the Compatibility category.

Related Technical Notes

0200	Using the Attachmate Download Library (FAQ)
10030	Supported Platforms and Systems Requirements for Verastream Host Integrator
10049	Configuring Verastream AADS Failover in Windows
10052	Configuring Verastream Server Load Balancing
10060	What is Verastream AADS?
10061	Features Introduced in Verastream Host Integrator 6.0
10069	New Features in Verastream Host Integrator 6.5
10075	Verastream Host Integrator 6.5 Known Issues
40023	Compatibility Settings in Verastream Host Integrator
40030	Upgrading to Host Integrator 6.5 in a Linux/UNIX Environment
40999	Verastream Host Integrator Technical Notes