If you are upgrading to Verastream Host Integrator 6.0 from 5.0, please read this section fully to understand how to upgrade your settings and files to version 6.0. You do not have to install version 5.5 in order to upgrade to version 6.0, but you should review the upgrade notes and change topics for both releases before upgrading. To upgrade a UNIX/Linux platform from 5.0, see the technical support site.
What's New in Version 6.0.
Linux/UNIX upgrade notes
Upgrading from Host Integrator 5.5 to 6.0
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.
Review the sequence for upgrading from
5.5. The sequence is the same for those upgrading from 5.0.
Review these upgrade issues:
Other model-related changes that affect upgrade include the role of settings files and requirements for model name and folder name matching.
Web Builder modifications that apply to a 5.0 upgrade only are listed below.
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 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.
In Web Builder 5.0, the package name generated was limited by a user-defined prefix added to the project name. In Web Builder 6.0, 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 6.0, the newly generated JavaBeans use different object and method names. For example:
|5.0 Name||6.0 Name|
An existing generated web service, and its clients, will continue to run correctly under the Verastream Host Integrator 5.5 release. However, if the 5.0 web service is replaced with a 5.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 5.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
5.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.0 connector used with a 5.5 server).
To allow your project to re-compile, delete the invalid reference and re-add
the COM reference to appconn.dll (now named WRQ Verastream Host Integrator 5.5
in the list of COM libraries).
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:
If you upgrade Host Integrator into a different folder from the original installation, 5.0 Web Builder projects may not be upgraded to version 5.5.
Version 5.5 now uses settings files only as a basis for creating new models. Using settings files (with the extension .dtool) is optional. Verastream Host Integrator now 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. All .dtool settings files are saved in the <VHI>\settings folder.
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 .dtool file settings will be 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.
In Version 5.5 of Host Integrator, 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 will be 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.
When you open a 5.0 model in 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.
After reviewing the information below, it is recommended that you disable these settings in order to take full advantage of Version 5.5 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.
Error entity compatibility
Multi-column recordset compatibility
Pattern width compatibility
Protected attribute compatibility
Recordset update compatibility
Read recordset compatibility
Relative to pattern compatibility
WaitForUpdate 3270 compatibility
See 5.0 recordset termination for additional compatibility information.
Previous to version 5.5, Host Integrator did not recognize entities when performing a command list portion of an operation. An error entity was not recognized until an operation was complete, and a WaitForCursorAtAttr command was not satisfied if the attribute was defined on an entity other than the starting entity for the operation.
This change applies to any model with either of the following:
To upgrade your model, click View Settings on the Settings menu. Open the Compatibility category, and change the setting for Verastream 5.0 Error Entity Compatibility to No.
Click the Destinations button from the Operation tab for each entity to determine if an error entity is defined. One possible side effect of changing this setting is that if an error entity is reached before the operation is complete, an error will now be reported.
To support this new behavior, re-recognition of the origin entity of an operation is ignored unless that entity is defined as a destination of the operation (primary, alternate, error, or intermediate). In other words, the origin is handled as an intermediate destination for which there is no action defined. Also, any destination or error entity found in the middle of an operation command list may behave differently after changing this setting.
Review each operation in the Operation tab for each entity to check for the presence of a WaitForCursorAtAttr command. Click the Edit button to display information about the commands that make up each operation. If a condition "wait for cursor at attribute" produced a timeout because the attribute is not on the starting entity for the operation, this timeout may no longer occur when you upgrade.
This setting controls the way that record and field locations in multi-column recordsets are calculated.
In versions 5.0 and earlier, the width of the first recordset field was used to determine the positions of all other records and fields after the first field, regardless of whether or not the other recordset field widths were the same as the first field. The location of records and fields within records, in multi-column recordsets, used only the column width of the first field defined in the record to determine subsequent field and record locations.
In version 5.5, the determination of record and field positions uses the field width of each field as recorded in the model file to determine field and record locations.
Click the Validate option on the Debug menu. If you have multi-column recordsets that are affected by this condition, you'll see this message:
Warning: Multi-column recordset has columns of varying widths
You can still deploy models that have this warning.
Changing the Verastream 5.0 Multi-column Recordset Compatibility setting from Yes to No will produce different results when you run a recordset test, but the warning message above will be displayed in either case. You can eliminate this message (if appropriate) by modifying the recordset's width and column settings.
Previous to 5.5, a single line of pattern text greater than the width of a
rectangular pattern matched if the wrapped text is present in the defined pattern
region. The pre-5.5 behavior only applies to rectangular patterns that have
Search for pattern in expanded region checked on the Pattern tab and a single
line of search text defined with a width greater than the width of the pattern
The rectangular region to search contains the following text (ignoring trailing spaces):
My dog and I went
for a hike. He ran
and ran all over.
The pattern below is recognized as a match.
for a hike. He ranand
Note: This match is recognized even though the Design Tool does not display the matched text correctly.
When Pattern Width Compatibility is set to Yes, this behavior is maintained. To upgrade your model, click View Settings on the Settings menu. Open the Compatibility category, and change the setting for Verastream 5.0 Pattern Width Compatibility to No.
Navigate through your model and confirm that all entities are recognized correctly.
Any pattern that is not recognized will cause entity recognition to fail. For
patterns not used in entity signatures, inspect each applicable rectangular
pattern. Change the pattern so that wrapping is not assumed to be acceptable
as part of the pattern match.
The Design Tool in version 5.0 of Host Integrator permitted marking a field or attribute as writable even when the corresponding field on the host application is read only. The Host Integrator ignored errors caused by attempting to write data to a recordset field or entity attribute which contains any protected (read-only) character cells.
The new behavior in version 5.5 of Host Integrator reports an error if a model attempts to write data to a recordset field or entity attribute that contains any protected (read-only) character cells.
To upgrade your model, click View Settings on the Settings menu. Open the Compatibility category, and change the setting for Verastream 5.0 Protected Attribute Compatibility to No.
Change the setting and check for errors reported when your model attempts to write data to a recordset field or entity attribute that is not writable. You can then evaluate your model to determine if you want to have this error reported and therefore need no additional modifications, or if you need to change the model itself.
Versions of the Host Integrator prior to version 5.5 did not execute the "before update" or "after update" operations. In version 5.5, these operations will be executed if they exist. Your model may behave differently after you change the compatibility setting for recordset update if all of the following conditions are true:
To upgrade your model, click View Settings on the Settings menu. Open the Compatibility
category, and change the setting for Verastream 5.0 Procedure Recordset Update
Compatibility to No.
In version 5.0, Host Integrator does not execute the "before update" or "after update" operations in this circumstance, even if it is present. If one of these options is enabled, changing the compatibility mode setting will now perform the operation.
Versions of the Host Integrator prior to version 5.5 used a recordset caching mechanism to retain recordset data that was no longer visible, and would return records in the cache if scrolling could not make a record visible. This could occur if the recordset had not defined a "page up" command even though the client application expected to be able to access records randomly. This opened the possibility that a client application could read "stale" data (information from a cache rather than from the host application itself).
This change applies to any model and client application with all of the following characteristics:
To upgrade your model, click View Settings on the Settings menu. Open the Compatibility category, and change the setting for Verastream 5.0 Read Recordset Compatibility to No.
With Host Integrator 5.0, this sequence will return data for that record from the recordset cache rather than reporting an error. If you change the compatibility setting to No, you may see the error "No PageUp operation has been defined." Define a PageUp operation to correct the problem.
To review recordset scrolling commands, click the Recordset tab for each entity. Click the Operations button on the Recordset tab to display the operations defined to control the recordset.
This setting controls the way the position of a pattern with an Any Column attribute is calculated. In versions 5.0 and earlier, the location of patterns was calculated incorrectly if the pattern column was defined as Any column and the pattern width was not the same as the terminal screen width. Correcting this calculation in version 5.5 has caused the positions of objects (such as attributes and recordsets) located relative to such patterns to change as well.
Review the attributes for each entity to determine if the Start position is calculated as Relative to Pattern with the Col specified as Any Column. With the compatibility setting applied (set to Yes), the position of the Any column pattern will miscalculate the pattern position if the pattern width is not equal to the screen width.
If you change Verastream 5.0 Relative to Pattern Compatibility to No, the position of Any column patterns will be calculated so that results are correct for pattern searches in a region that is not as wide as the terminal screen. If you change this setting, confirm that positions for attributes and recordsets are calculated as you expect.
This version includes a modification to the command WaitForUpdate and to the equivalent Host Update option in the WaitForMultipleEvents command. In order to ensure that existing models continue to function as they did in earlier versions, this compatibility setting is included. When you load an existing model into the Design Tool, the setting Verastream 4.5 WaitForUpdate Compatibility will be set to Yes.
When set to Yes, this setting ensures that the model will continue to use the original behavior of these commands. You may choose to keep this compatibility setting to retain the current behavior. However, any models you create will have this option set to No.
If you wish to upgrade your model, do the following:
This setting applies to models for IBM 3270 sessions that meet both of the following conditions:
When you load an existing model into the Design Tool, the setting Verastream 5.5 Wait for Update 3270 Compatibility will be set to Yes.
Keeping this setting enabled ensures that the model will continue to use the original behavior. However, any models you create after applying this patch will have this option set to No and use the new behavior.
If you wish to upgrade your model, do the following:
In prior versions, the record termination setting Read up to pattern did not work as documented; all records were returned regardless of the termination pattern. In version 5.5, this setting, now named Read until pattern, indicates that no records are returned after the specified pattern is found.
If you have models that use this setting, the number of records returned under
the earlier version may differ from those returned in the 5.5 model. There is
no compatibility setting for this behavior.
The models you have deployed in earlier versions of Host Integrator will be displayed 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. (In particular, read the note on not including descriptor files in your model package if you don't want to lose model or session pool configuration information in the Administrative WebStation.)
If you recorded a 5250 model with Host Emulator and used Scroll Up/Scroll Down keys, these keys will no longer operate as they did in versions previous to 5.5. To address this problem, open the master model and resave it.