Technical Notes

Upgrading Host Integrator 5.0 to 5.5 in a Windows-Based Environment
Technical Note 40021
Last Reviewed 04-Mar-2004
Applies To
Verastream Host Integrator version 5.0 through 5.5
Summary

This technical note outlines an upgrade path from Verastream Host Integrator 5.0 to 5.5 that enables users to maintain as many of their existing settings and models as possible. Details are provided to upgrade the AADS, Administrative WebStation, server configuration files, and host application models to be compatible with Host Integrator version 5.5 in a Windows-based environment.

Upgrade Path: Host Integrator 5.0 to 5.5

If you are upgrading to Verastream Host Integrator 5.5 from version 5.0, you must upgrade your Verastream components in this order:

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

Before you begin your upgrade, review the details in these sections:

Upgrading AADS, Administrative WebStations, and Session Servers

Under Windows, the Host Integrator version 5.5 Server Setup program detects the presence of 5.0 AADS, Administrative WebStations, and Host Integrator session servers. Setup can back up and upgrade the configurations to version 5.5.

AADS

You must upgrade each AADS to version 5.5 before you install a Host Integrator 5.5 Administrative WebStation or session server. Note: If AADS is on the same PC as an Administrative WebStation or a session server, you can select both or all of them when you run Setup.

Note: It is possible to have a version 5.0 and a version 5.5 AADS in the same environment, but they will not interact or be aware of each other.

Administrative WebStations

Because the Administrative WebStation is not compatible with an AADS of a different version, you should keep at least one 5.0 version of the Administrative WebStation if you plan to keep a 5.0 AADS.

Upgrade each Administrative WebStation after you upgrade AADS. Note: If the WebStation is on the same PC as an AADS or a session server, you can select both or all of them when you run Setup.

Host Integrator Session Servers

Upgrade your Host Integrator session servers to version 5.5 after you upgrade each AADS and Administrative WebStation. Note: If a server is on the same PC as an AADS or an Administrative WebStation, you can select both or all of them when you run Setup.

Steps to Upgrade AADS, Administrative WebStations, and Session Servers

To back up and upgrade each of these components from version 5.0 to 5.5, follow these steps:

1. Log in to Windows with Administrative privileges and close all running applications. Turn off all security before upgrading a Host Integrator session server.
2. Insert the Host Integrator 5.5 product CD into your CD-ROM drive.

3. To start the Setup program, click Run on the Start menu, type or browse to the path to the installation program on the Host Integrator product CD (for example, D:\Setup.exe), and then click OK.

4. Select the components whose settings files you want to back up and migrate to version 5.5. Click Next.
5. Select a backup directory to save the settings files that will be migrated. Click Next.
6. Save the settings files for the components you selected and then click Exit.
7. Use Add/Remove Programs from the Control Panel to uninstall Verastream Host Integrator version 5.0.
8. Install Verastream Host Integrator version 5.5 from the product CD.

9. Be sure to check your server and domain configurations carefully after installing version 5.5 and restarting the environment because some server, domain, and security parameters may revert to their default settings after upgrading.

After the AADS, Administrative WebStations, and session servers are upgraded, you can upgrade your host application models, WebBuilder projects, and client applications.

Upgrading Host Application Models

Your deployed 5.0 models will continue to function on a 5.5 session server. No manual upgrade is required. When you open a 5.0 model in the 5.5 Design Tool, it is saved as a 5.5 model. However, once you convert a model file to version 5.5, it can no longer be loaded on a 5.0 server.

Consider the following issues when upgrading host application models:

Upgrading Models in Folders with a Different Name

In Host Integrator version 5.5, models must be located in a folder with the same name as the model itself. If you have a .model file located in a folder that does not have the same name, you will see the message "<model> is not a valid model name. Please check the name and model path for accuracy." In order to open the model, you must move it to a folder that has the same name as the model.

When you open an existing model, new event handler folders are added to the model folder even if you do not save the model. These folders have no impact on the model itself, and their presence does not indicate that the model has been upgraded to 5.5.

Settings (.dtool) Files Used at Model Creation Only

Verastream Host Integrator 5.5 uses settings files only as a basis for creating new models. Version 5.5 includes a default settings file for all supported terminal types, and you can build your own settings files to quickly create multiple models that share settings. Settings files (with the extension .dtool) are optional.

In earlier versions of Host Integrator, a .dtool file was used with every model. When you upgrade a model to version 5.5, the existing settings file is incorporated into the model file. Any changes you make as you modify the model in version 5.5 will not be reflected in the 5.0-based .dtool file.

Adding a Model to Administrative WebStation Model Configuration

The models you deployed in earlier versions of Host Integrator will display as expected on the Model Configuration page. However, if you need to add a model, the Add Model button previously displayed on this page is no longer available. To add a model to the Model Configuration list, follow the procedure for using commands to deploy a model package. See the product Help files for details.

Compatibility Settings for Host Integrator 5.0

When you open a 5.0 model in the 5.5 Design Tool, you'll see this message, "This model was created with a prior version of the WRQ Verastream Host Integrator."

Use the compatibility settings described in Technical Note 40023 to choose whether to keep a model's original (5.0 or earlier) behavior or to change the behavior to version 5.5 standards. Each default compatibility setting (set to Yes) retains the original behavior.

Upgrading Web Builder Projects

The first time you open Web Builder 5.5, it automatically updates any 5.0 projects so that you can run the applications or use the web services and JavaBeans. Although you can deploy, move, or delete 5.0 web projects, you cannot modify these projects in Web Builder 5.5.

Be aware of these issues before you begin the upgrade procedure.

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

Package Names. In Web Builder 5.0, the package name generated was limited by a user-defined prefix appended to the project name. In Web Builder 5.5, you can enter an entirely new name for the package.

Object and Method Names. If you rebuild a 5.0 web project in Web Builder 5.5, the newly generated JavaBeans use different object and method names. For example:

5.0 Name	5.5 Name
ProjectName.Main()	ProjectName.Session()
recordSet.getRecordSize()	recordSet.size()
recordSet.getRecord(i)	recordSet.get(i)

Upgrading Client Applications

You may choose to install the new AppConn connector files on machines running client applications, but they will continue to work as usual if you choose not to do so.

Install the 5.5 AppConn connector on each machine 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 5.5 models and servers because the linked support libraries will be updated by Setup. Be aware that the 5.5 API contains 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 5.5 to take advantage of the new methods and features.

After the Upgrade

Although the Setup program is able to detect and save your current configuration and upgrade its settings to version 5.5, review and test your configuration thoroughly after upgrading to be sure that the upgrade was successful.

Related Technical Notes

10028	Features Introduced in Verastream Host Integrator 5.5
40022	Upgrading to Host Integrator 5.5 in a Linux/UNIX Environment
40023	Compatibility Settings in Verastream Host Integrator
40031	Upgrading to Host Integrator 6.5 in a Windows Environment
40999	Verastream Host Integrator Technical Notes