Upgrading from Host Integrator 5.0

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.

Upgrade Sequence

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 Projects

Web Builder modifications that apply to a 5.0 upgrade only are listed below.

Web Builder Upgrade Issues

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

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
ProjectName.Main() ProjectName.Session()
recordSet.getRecordSize() recordSet.size()
recordSet.getRecord(i) recordSet.get(i)

Web Services Compatibility

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

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.0 Web Builder projects may not be upgraded to version 5.5.

 

New Settings and Requirements in 5.5. Models

Settings (.dtool) Files Used at Model Creation Only

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.

Upgrading Models in Folders With a Different Name

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.

Compatibility Settings for Host Integrator 4.5 and 5.0

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 compatibility

WaitForUpdate 3270 compatibility

See 5.0 recordset termination for additional compatibility information.

Error Entity Compatibility

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.

To determine if changing this setting will affect your model:

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.

Multi-column recordset compatibility

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.

To determine if changing this setting will affect your model:

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.

Pattern width compatibility

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

Example

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.

To determine if changing this setting will affect your model:

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.

Protected attribute compatibility

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.

To determine if changing this setting will affect your model:

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.

Recordset update compatibility

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.

To determine if changing this setting will affect your model:
  1. Open the model, then select Tables from the Model menu.
  2. Select each procedure defined with each table and review the Type selection for the procedure. Options are SELECT, INSERT, UPDATE, and DELETE.
  3. If any of the procedures is an UPDATE procedure, click the Procedure Editor and determine if the procedure accesses a recordset. Select each entity in the procedure and check if there is a Recordset tab at the bottom of the procedure editor. If no Recordset tab is present, only the Data Exchange and Error tabs are displayed. Make a note of the recordset and exit the Procedure Editor.
  4. In the Design Tool, locate the entity that contains the recordset you just identified. At the bottom of the Recordset tab, click the Operations button.
  5. In the lower right corner of the Recordset Operations dialog box, check to see if either of the following options are enabled for Host supports direct record update:

    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.

Read Recordset Compatibility

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.

To determine if changing this setting will affect your model:

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.

Relative To Pattern compatibility

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.

To determine if changing this setting will affect your model:

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.

WaitForUpdate compatibility

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:

  1. Click View Settings on the Settings menu. Open the Compatibility category and change the Verastream 4.5 WaitForUpdate Compatibility setting from Yes to No.

  2. Confirm that the model operates as you expect. If it does not, check for any operations in the model that use the Host Events command WaitforUpdate or any WaitForMultipleEvents commands that include Host Update. The new behavior for these commands may cause a timeout in your model that did not occur before. Examine the operation using Host Integrator tools to identify where the entity is being updated at the time that the command is issued. Make any necessary modifications to the model so that the command functions as you expect.

Verastream 5.5 Wait for Update 3270 Compatibility

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:

  1. Click View Settings on the Settings menu. Open the Compatibility category and change the Verastream 5.5 WaitForUpdate 3270 Compatibility setting from Yes to No.
  2. Change the Verastream 4.5 WaitForUpdate Compatibility from Yes to No. This setting addressed an issue for all terminal types; it must be disabled in order to have the 3270-specific 5.5 setting take effect.
  3. Confirm that the model operates as you expect. If it does not, check for any operations in the model that use the Wait for Update command. The new behavior for this command may cause timeout failures. The new behavior enforces a more specific definition of the host update position, as the previous behavior could allow an update outside of the specified region to satisfy the host update requirement. Be sure to check the model behavior in the Design Tool and on a Host Integrator Server.
  4. Make any necessary modifications to the model so that the command functions as you expect. You may need to adjust the Wait for Update position or size, or you may want to use an alternative such as Wait for New Host Screen.

Recordset Termination: Excluding Records on the Last Screen

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.

Adding a Model to Administrative WebStation Model Configuration

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

Host Emulator 5250 Master Models

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.