Technical Notes

Upgrading to Host Integrator 6.6 in a Windows Environment
Technical Note 40031
Last Reviewed 11-Sep-2008
Applies To
Verastream Host Integrator version 6.6
Summary

This technical note outlines an upgrade path from Verastream Host Integrator version 5.5 or higher to version 6.6 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.6 in a Windows-based environment.

See Technical Note 10080 for a list of new features in version 6.6; Technical Note 10069 for version 6.5; and Technical Note 10061 for 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.6, 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.6.
• 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.
• Administrative WebStation version 6.6 is not compatible with earlier versions of AADS.

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.6 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 unzip files.

• 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 through 6.5 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.6 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 6.5 or earlier.

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.6 Setup

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

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.6 and restarting the environment. Restore the original configuration you noted in step 1.

Host Application Models

Your deployed 5.5 through 6.5 models will continue to function on a 6.6 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.6, 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 Versions 4.5 through 6.5.

Directory Server Settings

The first time your run the version 6.6 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.6/doc/help/designtool/h_rte.html.

If you install the 6.6 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.6 models and servers because the support libraries you link to are updated by Setup. Be aware that the latest 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 in order to take advantage of any new methods and features.

Beginning in version 6.5, the COM connector file name has changed from appconn.dll to appconncom.dll.

Beginning in version 6.6, the .NET Connector no longer supports .NET 1.1 client applications. For more information, see Technical Note 40037.

Upgrading Web Builder Projects

The first time you open Web Builder 6.6, it automatically updates any existing 5.5 through 6.5 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 earlier versions, but you cannot modify them. You should be aware of the following issues.

Web Builder Upgrade Issues

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.6.

Project Type Changes

Some project types that were in Web Builder version 6.0 or earlier 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.0 or higher supports the creation of projects using Microsoft .NET Framework version 2.0 and Microsoft Visual Studio 2005. Beginning with version 6.6, .NET 1.1 projects are no longer supported. For more information, see Technical Note 40037.

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 with the new release. However, if you re-build a web service generated from the same model, you may need to update your client code to use new web service standards:

• Beginning in version 6.5, Verastream Host Integrator 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.
• Beginning in version 6.6, for WS-I compliance, the web service default return data type is an array. If you need your generated .NET Web Service to return the data type Microsoft Data Set (same as earlier product versions), configure the Return Type in Web Builder (Project Properties).

.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 or higher, the Microsoft Visual Studio 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 or higher 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.6 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 higher. 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 or higher, the visibility options are set appropriately based on the existing element name _SHOW or _HIDE suffixes.) Beginning with version 6.6, options are also available for controlling visibility of recordsets and recordset fields.

For more information on configuring projects, see http://www.attachmate.com/docs/verastream/vhi/6.6/doc/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 or higher, 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 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 Versions 4.5 through 6.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 Host Integrator Server Load Balancing
10060	What is Verastream AADS?
10061	Features Introduced in Verastream Host Integrator 6.0
10069	Features Introduced in Verastream Host Integrator 6.5
10075	Verastream Host Integrator 6.5 and 6.6 Known Issues
10080	New Features in Verastream Host Integrator 6.6
40023	Compatibility Settings in Verastream Host Integrator
40030	Upgrading to Host Integrator 6.6 in a Linux/UNIX Environment
40037	Verastream Host Integrator 6.6 and .NET 1.1 Applications
40999	Verastream Host Integrator Technical Notes