Technical Notes

Compatibility Settings in Verastream Host Integrator
Technical Note 40023
Last Reviewed 21-Jul-2006
Applies To
Verastream Host Integrator version 5.5 through 6.0
Summary

When upgrading from Verastream Host Integrator from version 4.5, 5.0, or 5.5, you can choose to preserve a model's earlier behavior or change the model to newer standards. Use the compatibility settings described in this technical note to preserve or change the functionality.

Preserving Original Behavior—the Default

When you open a model in the Design Tool, this message appears: "This model was created with a prior version of the Verastream Host Integrator." The compatibility settings described below are set to enable your models to retain the same behavior as they had in an earlier version of Host Integrator.

Changing Compatibility Settings

After reviewing the information below, it is recommended that you disable these settings (set them to No) to take full advantage of new 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 the necessary modifications.

You can re-enable a compatibility setting at any time. Simply select your preferred setting, save the model, and the server will read and interpret the current compatibility setting.

To view the compatibility settings, click Settings > View Settings and expand the Compatibility category. Change the compatibility setting to No and test the behavior before you save the model.

The following settings are described in this document:

The View Settings dialog displays the compatibility settings sorted by version.

Note: The version indicates the last product version with the original behavior; the compatibility setting is introduced in a subsequent version (service pack or product release).

Erase to End of Attribute Compatibility (version 5.5)

This compatibility setting preserves the behavior of the Erase to end of attribute behavior that was present in Verastream 5.5 and earlier versions. This compatibility setting will, by default, be enabled for all models created in an earlier version that are loaded into the Design Tool for editing, or into the session server for execution.

When this compatibility setting is enabled, attributes enabled for Erase to end of attribute on the Properties Tab of the model's Attributes settings will have spaces written appended to the new attribute value to erase any value already displayed. The number of space characters appended is equal to the number of characters in the model's definition of the attribute, minus the number of characters in the new value.

When this compatibility setting is disabled, the Erase to end of attribute operation is different for IBM 3270 and 5250 terminals than for other emulation types. For the IBM terminal types, the new attribute value will be written to the attribute, and then the Erase to end of field command will be sent if the attribute's location coincides with a terminal field. If the location does not coincide with a terminal field, Host Integrator will use spaces.

Error Entity Compatibility (version 5.0)

Prior to version 5.5, Host Integrator did not recognize entities during the course of the execution of a single operation. An error entity was not recognized until an operation was complete, and a wait condition (WaitForCursorAtAttr command) was not satisfied if the attribute was defined on an entity other than the starting entity for the operation.

Version 5.5 and higher, however, can recognize error entities during the course of an operation, and this change applies to any model with either of the following:

• An operation with an error entity
• A wait condition "wait for cursor at attribute" (WaitForCursorAtAttr) for which the entity named in the condition is not the starting entity for the operation

To determine if you should change this setting:

1. In the Design Tool, open the model. Click Settings > View Settings and expand the Compatibility category. Select VHI 5.0 Error Entity Compatibility and change the setting to No.
2. For each entity, click the Destinations button on the Operation tab to determine if an error entity is defined.

3. For each entity, review the Operation tab to check for the presence of a WaitForCursorAtAttr command. Click the Edit button to display information about the commands that make up each operation.

4. If the 5.5-and-higher behavior is acceptable, save the model. If not, change the setting back to Yes, and then save the model.

Host Data Processing Compatibility (version 5.5)

In versions of Host Integrator 5.5 and earlier, operation events and attribute/field wait for echo were completed only when the condition is met and all data in the host write has been processed. This is problematic for VT hosts that rely on datastream analysis or consistency of host write partitioning.

When this compatibility switch is enabled, this behavior is maintained.

When this switch is disabled, a sequence of WaitForCommString commands can now be used reliably in a command lists. Similarly, attribute post-write operations can begin with WaitForCommString when the attribute is configured to wait for echo.

This change has no effect on the more common situation where evaluation occurs when there is no host data left to process. This does not impact commands resulting from script API invoked as part of a command list. If a script user wants a command sequence to behave like an internal command list, the command list callback API can be used.

Multi-Column Recordset Compatibility (version 5.0)

This setting controls the way that record and field locations are calculated in multi-column recordsets.

In versions 5.0 and earlier, the width of the first column was used to determine the positions of fields in all columns, regardless of whether the other column widths were the same as the first column. And, in multi-column recordsets, the location of records and fields within records used only the column width of the first field defined in the record to determine subsequent field and record locations.

In version 5.5 and higher, the determination of field positions uses the width of each column as recorded in the model, not just the width of the first column.

To determine if you should change this setting:

1. In the Design Tool, open the model and click Debug > Validator. If you have multi-column recordsets that are affected by this condition, this message appears:

2. Click Settings > View Settings and expand the Compatibility category. Change the VHI 5.0 Multi-column Recordset Compatibility setting to No.
3. Run a recordset test. The new behavior may cause the model to read different data because the fields appear to be in different positions, and the above warning message displays in either case. Modify the model's width and column settings to eliminate this message.
4. If the 5.5-and-higher behavior is acceptable, save the model. If not, change the setting back to Yes, and then save the model.

Multi-Line Attribute Compatibility (version 5.5)

This setting applies to applications using multi-line rectangular attributes on block mode terminals. For versions earlier than Host Integrator 6.0, the line wrapping behavior did not operate as expected and could cause write validation to fail while attempting to write data to protected fields outside the bounds of the attribute.

For models created in earlier versions, this setting is true and multi-line writes will continue to operate as before. Earlier models with this behavior could overcome the wrapping problem by setting the attribute as scrollable (as long as there were no intervening unprotected fields).

In version 6.0, the default setting for Multi-line attribute compatibility is false, and data is written to multiple lines when the field has multi-line character attributes. Change this compatibility setting from true to false to take advantage of the improved multi-line wrapping behavior for rectangular attributes on block mode terminals.

Pattern Evaluation Compatibility (version 5.5)

Starting with version 6.0, when you create an entity signature pattern with the Search for pattern relative to cursor option enabled, the following will occur:

• The initial cursor position setting will be reset when Verastream leaves an entity. This ensures that initial cursor position settings are not unintentionally reused from one entity to another.
• If the initial cursor position setting is not set, Verastream Host Integrator will use the current cursor location to evaluate entity signature patterns.

For models created with versions 5.5 and earlier, this behavior is disabled. Verastream resets the initial cursor position only after a new entity has been recognized. This sometimes results in initial cursor positions being inadvertently reused.

Pattern Width Compatibility (version 5.0)

Prior to version 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 applies only 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.

For example, when the rectangular region to search contains the following text:

The following pattern is recognized as a match:

Note: This match is recognized even though the Design Tool does not display the matched text correctly.

To determine if you should change this setting:

1. Navigate through your model and confirm that all entities are recognized correctly. Any pattern that is not recognized will cause entity recognition to fail.
2. For patterns not used in entity signatures, inspect each applicable rectangular pattern.
3. Change the pattern so that wrapping is not assumed to be acceptable as part of the pattern match.
4. To test the 5.5-and-higher behavior, click Settings > View Settings and expand the Compatibility category. Change the VHI 5.0 Pattern Width Compatibility setting to No.
5. If the 5.5-and-higher behavior is acceptable, save the model. If not, change the setting back to Yes to preserve the original behavior and then save the model.

Procedure Recordset Update Compatibility (version 5.0)

Versions of Host Integrator prior to 5.5 did not execute the "before update" or "after update" operations. In version 5.5 and higher, these operations are executed if they exist. When you change the compatibility setting for recordset update, your model will behave differently if all of the following conditions are true:

• A table procedure updates a recordset.
• The recordset has the "Host supports direct record update" option enabled.
• The recordset has an "Execute operation before update" or "Execute operation after update" assigned.

To determine if you should change this setting:

1. In the Design Tool, open the model and click Model > Tables.
2. For each procedure, open the Procedure Editor and determine if the procedure accesses a recordset.
3. 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.
4. Look in the lower-right corner of the Recordset Operations dialog box to see whether either of the following options is enabled for "Host supports direct record update":

5. If either of the above options is enabled, either leave the compatibility setting on (set to Yes) or clear the check boxes for both of these options.
6. To test the 5.5-and-higher behavior:
   1. Clear both of the "Execute operation" options identified in step 4.
   2. Click Settings > View Settings and expand the Compatibility category. Change the VHI 5.0 Procedure Recordset Update compatibility setting to No.
   3. Click Debug > Procedure Test and test each procedure that uses a modified recordset.
7. If the 5.5-and-higher behavior is acceptable, save the model. If not, change the setting back to Yes, return the "Execute operation" options back to the original state, and then save the model.

Protected Attribute Compatibility (version 5.0)

The Design Tool in Host Integrator version 5.0 permitted marking a field or attribute as writable even when the corresponding field on the host application is read-only. Version 5.0 ignored errors caused by attempting to write data to a recordset field or entity attribute that contains any protected (read-only) character cells.

Host Integrator 5.5 and higher 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 determine if you should change this setting:

1. In the Design Tool, open the model and click Settings > View Settings. Expand the Compatibility category and change the setting for VHI 5.0 Protected Attribute Compatibility to No.
2. 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.
3. If the 5.5-and-higher behavior is acceptable, save the model. If not, change the setting back to Yes, and then save the model.

Read Recordset Compatibility (version 5.0)

Prior to version 5.5, Host Integrator used a recordset caching mechanism to retain recordset data that was no longer visible. If scrolling could not make a record visible, then this mechanism would return records from the cache.

Even though the client application expected to be able to access records randomly, records could be returned from a cache if the recordset had not defined a "Page Up" command. In this scenario, a client application could read old data (from a cache) rather than from the host application itself.

Version 5.5 and higher requires a defined page-up and page-down operation to reliably support random access to records. This change applies to any model or client application with both of the following characteristics:

• A client application calls setCurrentRecordSetIndex for a record on a prior page.
• The recordset has no operation (such as Page Up) defined that can make the prior page visible.

To determine if you should change this setting:

1. In the Design Tool, open the model. Click Settings > View Settings and expand the Compatibility category. Change the setting for VHI 5.0 Read Recordset Compatibility to No.

2. Click the Recordset tab for each entity to review recordset scrolling commands. Click the Operations button on the Recordset tab to display the operations defined to control the recordset.
3. If no Page Up operation is selected, define one. Otherwise, Host Integrator will return the error: "No PageUp operation has been defined."
4. If the 5.5-and-higher behavior is acceptable, save the model. If not, change the setting back to Yes, and then save the model.

Relative to Pattern Compatibility (version 5.0)

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 caused changes to the positions of objects (such as attributes and recordsets) located relative to such patterns.

To determine if you should change this setting:

1. Open the model in the Design Tool. 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.

2. To test the 5.5-and-higher behavior: Click Settings > View Settings and expand the Compatibility category. Change the VHI 5.0 Relative to Pattern Compatibility setting to No.

3. Confirm that the positions for attributes and recordsets are calculated as you expect.
4. If the 5.5-and-higher behavior is acceptable, save the model. If not, change the setting back to Yes, and then save the model.

Variable Length Record Compatibility (version 5.5)

In Host Integrator 5.5, a recordset configured with variable-length records would ignore the end of record configuration options located in the Record Size section of the Recordset Layout tab in cases where one or more of the fields in the record was located past the end of the variable length record. As of version 6.0, Host Integrator by default honors the end of record configuration options. Fields that are located past the end of the variable-length should be returned with empty values. An improperly configured recordset that previous caused no problems may fail when the 6.0 default is applied. To determine if you can upgrade to the new behavior in a model created under an earlier version, check for recordsets with variable length records (Record Size set to Variable on the Layout tab of Recordset configuration), and then examine each of the individual fields to determine whether their location is consistent with the delimiter options selected on the Layout tab.

WaitForUpdate Compatibility (version 4.5)

Host Integrator 5.5 and higher includes a modification to the command WaitForUpdate and to the equivalent Host Update option in the WaitForMultipleEvents command.

To determine if you should change this setting:

1. Click Settings > View Settings and expand the Compatibility category. Change the VHI 4.5 WaitForUpdate Compatibility setting to No.
2. Confirm that the model operates as you expect. If it does not, check for operations in the model that use the Host Events command WaitForUpdate or WaitForMultipleEvents commands that include Host Update.

3. Examine the operation using Host Integrator tools, such as the Datastream Window, to identify where the entity is being updated at the time the command is issued. Make modifications to the model so that the command functions as you expect.
4. If the 5.5-and-higher behavior is acceptable, save the model. If not, change the setting back to Yes, and then save the model.

WaitForUpdate 3270 Compatibility (version 5.5)

This setting applies to models for IBM 3270 sessions that meet both of the following conditions:

• The model was created using version 5.5.418 or earlier
• The model uses the command WaitForUpdate in operations.

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 new models you create 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 WaitForUpdate position or size, or you may want to use an alternative such as WaitForNewHostScreen.

WaitForUpdate HP Compatibility (version 5.5)

This setting applies to models for HP sessions that meet both of the following conditions:

• The model was created using version 5.5 or earlier
• The model uses the command WaitForUpdate in operations.

When you load an existing model into the Design Tool, the setting Verastream 5.5 Wait for Update HP Compatibility will be set to Yes.

Keeping this setting enabled ensures that the model will continue to use the original behavior. However, any new models you create 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 HP 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 HP-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 WaitForUpdate 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 WaitForUpdate position or size, or you may want to use an alternative such as Wait for New Host Screen.

WaitForUpdate 5250 Compatibility (version 5.5)

This setting applies to models for IBM 5250 sessions that meet both of the following conditions:

• The model was created using version 5.5 or earlier
• The model uses the command WaitForUpdate in operations.

When you load an existing model into the Design Tool, the setting Verastream 5.5 Wait for Update 5250 Compatibility will be set to Yes.

Keeping this setting enabled ensures that the model will continue to use the original behavior. However, any new models you create 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 5250 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 5250-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 WaitForUpdate 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 WaitForUpdate position or size, or you may want to use an alternative such as WaitForNewHostScreen.

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, re-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 or later model. There is no compatibility setting for this behavior.

Related Technical Notes

40021	Upgrading Host Integrator 5.0 to 5.5 in a Windows-Based Environment
40022	Upgrading to Host Integrator 5.5 in a Linux/UNIX Environment
40030	Upgrading to Host Integrator 6.5 in a Linux/UNIX Environment
40031	Upgrading to Host Integrator 6.5 in a Windows Environment
40999	Verastream Host Integrator Technical Notes