Compatibility Settings for Host Integrator Upgrades

These compatibility settings apply to upgrades from Verastream Host Integrator 4.5, 5.0, 5.5, and higher.

NOTE: For complete upgrade instructions, see the Installation Guide. The guide is available from the Start menu on Windows systems and under Docs\Help.

When you open a model from a previous version in the Design Tool, you'll see a message noting that "This model was created with a prior version of Verastream Host Integrator." The compatibility settings described below enable your models to maintain the same behavior as they had in earlier versions of Host Integrator.

After you review this information, you can take advantage of the most recent version's functionality by disabling these compatibility settings. In most cases, there will be no change in the behavior of your model. If you do notice a change, use the guidelines included in the setting descriptions below to make whatever modifications are necessary. You can re-enable a compatibility setting at any time.

To view compatibility settings, select View Settings from the Settings menu in the Design Tool, then open the Compatibility category. 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 (Verastream 5.5)

Error entity compatibility (Verastream 5.0)

Host data processing compatibility (Verastream 5.5)

Multi-column recordset compatibility (Verastream 5.0)

Multi-line attribute compatibility (Verastream 5.5)

Pattern evaluation compatibility (Verastream 5.5)

Pattern width compatibility (Verastream 5.0)

Procedure recordset update compatibility (Verastream 5.0)

Protected attribute compatibility (Verastream 5.0)

Read recordset compatibility (Verastream 5.0)

Relative to pattern compatibility (Verastream 5.0)

Variable length record compatibility (Verastream 5.5)

WaitForUpdate compatibility (Verastream 4.5)

WaitForUpdate 3270 compatibility (Verastream 5.5)

WaitForUpdate HP compatibility (Verastream 5.5)

WaitForUpdate 5250 compatibility (Verastream 5.5)

Keyboard lock compatibility (Verastream 6.5)

See 5.0 recordset termination for additional compatibility information.

Erase to End of Attribute Compatibility (Verastream 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 (Verastream 5.0)

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:

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

Host data processing compatibility (Verastream 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 (Verastream 5.0)

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 and later, 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.

Multi-line attribute compatibility (Verastream 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 and later, 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 (Verastream 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 (Verastream 5.0)

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 (Verastream 5.0)

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 behavior in version 5.5 and later 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.

Procedure Recordset update compatibility (Verastream 5.0)

Versions of the Host Integrator prior to version 5.5 did not execute the "before update" or "after update" operations. In version 5.5 and later, 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:

The model contains an "Update" procedure
The 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 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:

Open the model, then select Tables from the Model menu.
Select each procedure defined with each table and review the Type selection for the procedure. Options are SELECT, INSERT, UPDATE, and DELETE.
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.
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.
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:
- Execute operation before update
- Execute operation after 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 (Verastream 5.0)

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:

A client application calls setCurrentRecordSetIndex for a record on a prior page
The recordset has no operation defined which can make the prior page visible
The client application uses nextRecord or getCurrentRecord to read the records that are no longer visible

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 (Verastream 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 and later 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.

VariableLengthRecord compatibility (Verastream 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 and later, 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 and later 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 (Verastream 4.5)

VHI version 5.0 and later 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 version 4.5 and earlier, 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:

Click View Settings on the Settings menu. Open the Compatibility category and change the Verastream 4.5 WaitForUpdate Compatibility setting from Yes to No.
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.

Wait for Update 3270 Compatibility (Verastream 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 models you create afterwards will have this option set to No and use the new behavior.

If you wish to upgrade your model, do the following:

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.
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 and later setting take effect.
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.
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.

Wait for Update HP Compatibility (Verastream 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 models you create afterwards will have this option set to No and use the new behavior.

If you wish to upgrade your model, do the following:

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.
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 and later setting take effect.
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.
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.

Wait for Update 5250 Compatibility (Verastream 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 models you create afterwards will have this option set to No and use the new behavior.

If you wish to upgrade your model, do the following:

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.
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 and later setting take effect.
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.
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.

Keyboard Lock Compatibility (Verastream 6.5)

This setting applies to models created under Verastream 6.0 and 6.5

When you load an existing model into the Design Tool, the setting Verastream 6.5 Keyboard Lock 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 afterwards will have this option set to No and use the new behavior.

If you wish to upgrade your model, do the following:

Click View Settings on the Settings menu. Open the Compatibility category and change the Verastream 6.5 Keyboard Lock Compatibility setting from Yes to No.
Confirm that the model operates as you expect. The new behavior ensures that the keyboard is unlocked before scanning the screen or executing any commands following a TransmitTerminalKey, as the 6.0 and 6.5 behavior could result in recognition attempts, reading or writing areas of the screen, or attempting another TransmitTerminalKey while the keyboard is still locked, resulting in errors or data corruption. Be sure to check the model behavior in the Design Tool and on a Host Integrator Server.
Make any necessary modifications to the model so that the command functions as you expect. Note that the automatic initial keyboard unlocked status is a necessary but not always sufficient condition to continue processing. Additional WaitForKeyboardEnabled commands might be required after TransmitTerminalKey if the host sends the next screen in multiple records.

Note: The Keyboard Lock Compatibility setting will have no effect if Pattern Evaluation Compatibility (Verastream 5.5) is set to Yes.

Recordset Termination: Excluding Records on the Last Screen

In version 5.0 and earlier, 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 and later, 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 and later model. There is no compatibility setting for this behavior.