Features Introduced in Verastream Host Integrator 7.1

  • Document ID:7021577
  • Creation Date:13-May-2011
  • Modified Date:11-Mar-2018
    • Micro Focus Products:
      Verastream Host Integrator (VHI)

Environment

Verastream Host Integrator version 7.1

Situation

This technical note describes product enhancements and fixes for Verastream Host Integrator (VHI) version 7.1.221, which released May 2011. If you are using a previous version, we recommend that you review this information before upgrading.

Note the following:

  • For information about features in Verastream Host Integrator 7.5 released in December 2012, see KB 7021251.
  • For information about features in Verastream Host Integrator 7.1 Service Pack 1 released in October 2011, see KB 7021585.

Resolution

This release includes the following features:

  • Web Services Explorer is a web service client you can use to test the automatic web services, thereby eliminating the need to use a third-party client such as SoapUI. Web Services Explorer web application functionality is provided by the Management Server component. To access Web Services Explorer, use any of the following methods:
    • Click the "Test" button displayed by Design Tool after successfully deploying a model
    • Click the "Test" link displayed in the list of WSDLs for deployed models at http://<session server>:9680/vhi-ws
    • In a web browser, open the following URL:
http://<management server>:8095/wsexplorer/wsexplorer.jsp?com.attachmate.eclipse.wst.ws.explorer=0&mode=standalone&wsdl=http://<session server>:9680/vhi-ws/model/<model name>?wsdl

For more information on using Web Services Explorer, see http://docs2.attachmate.com/verastream/vhi/7.1/en/topic/com.attachmate.vhi.help/html/reference/web_service_test.xhtml.

  • Reflection Security Proxy support for host connections, which provides a secure SSL/TLS encrypted tunnel (particularly for hosts that do not provide SSL/TLS Telnet) and additional authentication, authorization, and auditing features. Note: This feature requires Attachmate Reflection for the Web version 10.2.505 or higher, available separately. For more information, see KB 7021544.
  • Improved support for User Account Control (UAC) on newer Windows platforms: In the Development Kit, it is no longer necessary to run Web Builder, Design Tool, Administrative Console, or Help applications with elevated administrator privileges, thus enhancing system security.

In compliance with these new Windows standards, Development Kit document folder locations have changed. These applications use the <Documents> folder, which is platform- and user-dependent, typically C:\Users\<user name>\Documents (on Windows 7) or C:\Documents and Settings\<user name>\My Documents (on Windows XP).

    • Design Tool models: By default, in a new installation, models are saved to <Documents>\Attachmate\Verastream\HostIntegrator\models. If you save models to a different folder, that location becomes the new default.

In previous versions, models were saved to C:\Program Files (x86)\Attachmate\Verastream\HostIntegrator\models (version 7.0) or C:\Program Files\VHI\models (version 6.6 and earlier). In version 6.6 and earlier, if Design Tool was run as a non-administrator, saved models would get "lost" (in %USERPROFILE%\App Data\Local\Virtual Store\Program Files) due to operating system data redirection.

    • Sample and "master" models: Sample models are now located in %VHI_ROOT%\examples\ModelSamples, where %VHI_ROOT% is typically C:\Program Files (x86)\Attachmate\Verastream\HostIntegrator. Host Emulator "master" models are moved to %VHI_ROOT%\hostemulator\models. In previous versions, these were all stored in the same models folder (C:\Program Files\VHI\models or C:\Program Files (x86)\Attachmate\Verastream\HostIntegrator\models).
    • Web Builder project files: By default, in a new installation, Web Builder project files (both .NET and Java) are generated in <Documents>\Attachmate\Verastream\HostIntegrator\projects. This location can be changed in Web Builder (Options > Web Builder Settings > Common). When Web Builder version 7.1 is first run, existing projects are migrated. In previous versions, projects were typically saved to C:\Program Files (x86)\Attachmate\Verastream\HostIntegrator\projects (version 7.0) or C:\Program Files\VHI\projects (version 6.6 and earlier)..

For more information about project files, see http://docs2.attachmate.com/verastream/vhi/7.1/en/topic/com.attachmate.vhi.webbuilder.help/html/reference/wb_folder_files.xhtml.

    • Web Builder settings: Web Builder settings are stored on a per-user basis in %LOCALAPPDATA%\Attachmate\Verastream\HostIntegrator\webbuilder by default. In previous versions, the settings were global for all users.
    • Verastream Web Server applications: When a Java web application generated by Web Builder (.war file) is deployed to the Verastream Web Server (Apache Tomcat) on Windows, the resulting .jar file is copied to <Documents>\Attachmate\Verastream\HostIntegrator\tomcat\webapps\<ProjectName>\WEB-INF\lib. In previous versions, this location was <VHI install folder>\tomcat\webapps\<ProjectName>\WEB-INF\lib.

Note:Program Files is still used for all runtime components and configuration files (session server, management server, deployed models, etc.), which is the same as previous releases.

  • New iisdeploy.exe utility: When using Web Builder to deploy a generated .NET web application to the local Windows IIS web server, administrative rights are required to run the new VHI IIS Deployment Tool (iisdeploy.exe). In the User Account Control dialog, click Continue.
  • The deployment descriptor deploy_desc.xml file supports setting new optional pool parameters within the <pool-configuration> node. (In version 7.0, these pool properties were typically configured in Administrative Console only after the model was deployed, and needed to be configured again after the model was re-deployed.)

The following new optional parameters are supported (in addition to parameters supported in previous versions, such as <max-sessions> for maximum concurrent sessions):

    • <min-free-sessions>: Same as min-sessions. Specifies the minimum idle host sessions to maintain at all times, to improve performance when clients connect.
    • <max-free-sessions>: Specifies the maximum idle host sessions, to reduce impact on the host.
    • <initial-free-sessions>: Specifies the number of host sessions to preload and connect (as idle) when the pool is started.
    • <max-pending-sessions>: Specifies the maximum number of pending sessions simultaneously connecting to the host, to reduce impact on the host. This value is also configurable on a per-server basis in Administrative Console.
    • <idle-session-check-time>: Specifies how often the session server should ensure pool idle sessions are navigated to the pool startup entity (to avoid delays when clients connect to the pool). If not specified, the default interval is 120 seconds. Shorter intervals may cause performance problems. This value does not display in Administrative Console.
    • <idle-session-check>: If not specified, the default is true, and idle-session-check-time is applied. Setting to false disables the feature and reverts to version 6.x behavior for pool idle sessions. This value does not display in Administrative Console.
    • <connect-delay>: Specifies connection throttle delay interval (in seconds) between host session connection activity.
    • <max-retries>: Value from 0 to 10 that specifies the maximum backoff interval time between host session connection attempts. Failed connection attempts are automatically re-attempted continuously, with the time between attempts automatically increasing exponentially to 2^N seconds. The default value 10 represents maximum backoff time of 2^10 seconds, or approximately 17 minutes. This value is also configurable on a per-server basis in Administrative Console.
    • <pool-started>: If not specified, default is true. Setting to false will deploy the pool in a stopped state. The pool can be started manually in Administrative Console, or started automatically at scheduled days and times (configured in Administrative Console).

Note: In deploy_desc.xml, model debug messages recording is set on a per-model basis only. However, in Administrative Console, recording can be set on a per-pool basis.

  • Administrative Console connections through a firewall can be enabled by configuring management server RMI ports to listen at specific non-ephemeral port numbers. For more information, see "Configuring Port Numbers" in KB 7021229.

Additional Product Updates

This release includes the following updates introduced since version 7.0.967.

Performance, Stability, and Web Service Compatibility Improvements

  • You can configure the method timeout used by the web service SOAP stack to increase it from the default 30 seconds, which is useful if you have a table procedure that returns a large amount of host data. In versions 7.0.961 through 7.0.980, this method timeout was not configurable. For more information, see KB 7021534.
  • In the web service SOAP stack configuration, you can disable WS-Standards options (WS-Resource, WS-Security, and WS-Addressing) for increased compatibility with web services clients. For more information, see KB 7021336.
  • If you use stateful web services (multiple SOAP client calls using the same host session), you can modify the suspend timeout (when un-resumed sessions are terminated by the session server). In version 7.0, the SOAP stack 60-minute suspend timeout could not be modified.
  • The VHI web service readily interoperates with .NET applications (created with Microsoft Visual Studio) that are configured to use the web service at secure SSL port 9681. The VHI web service provides a WS-Security header in response to a Microsoft WCF request.
  • Added cross-domain access for enhanced web application support. The web service SOAP stack provides crossdomain.xml in the root directory, which improves support for web applications such as Microsoft Silverlight and Adobe Flex. This functionality was not provided in version 7.0.971 or earlier. Note: The default configuration permits VHI web service access from any system. To restrict cross-site access, extract, modify, and re-pack the crossdomain.xml file within the vhi-ws-plugin.jar file.
  • The web service WSDL can be successfully used by Microsoft InfoPath 2010. For more information, see KB 7021579.
  • The web service can be successfully used by TIBCO-BW. With versions 7.0.961 through 7.0.967, an Invalid Encoding error could occur due to ambiguities in the RFC specification.
  • If a session in a pool is idle at the home entity, and the host system causes the home entity to no longer be recognized, the session server behavior is corrected. In versions 7.0.961 through 7.0.971, a VHI 3184 "operation nesting" error would occur when the session server attempted to regain the home entity.
  • Multiple SSL/TLS-encrypted sessions successfully connect to the host simultaneously. In versions 7.0.961, 7.0.967, and 6.6.218 and earlier, encrypted host sessions connecting simultaneously (such as idle sessions connecting when a pool starts) could result in the session server ungracefully terminating after logging error message ID 3067 "Property sheet processing error: Exception caught handling xml command method."
  • In TN3270E Telnet Extended host sessions with SSL/TLS encryption, an "X SYSTEM" or "X PROG750" error no longer occurs in the session when the telnet sequence ID number reaches FF (such as after 256 screens). These errors could occur in version 7.0.982 and earlier.
  • Multiple concurrent SOAP requests now result in multiple concurrent sessions in the session server. In versions 7.0.961 through 7.0.971, the web service handled requests serially.
  • If a model includes event handler scripting, multi-threading capabilities have been restored (same as version 6.6). A thread is now added to the thread pool when a connection is made to the event handler script server and removed when a connection is destroyed. In versions 7.0.961 through 7.0.971, the script engine did not support multi-threading.
  • Resolved intermittent errors occurred with version 7.0 when performing multi-threaded load testing of web services with the session server embedded SOAP stack. These issues were fixed by updating JAX-WS version 2.1.1 to version 2.2.1. Example snippets of the version 7.0 faults are as follows:
ParseError at [row,col]:[18,3] Message: The element type "soapenv:Body" must be terminated by the matching end-tag "</soapenv:Body>".
System.Web.Services.Protocols.SoapException: The stream reader has reached the end of the document, or there are no more items to return ...
System.Web.Services.Protocols.SoapException: ParseError at [row,col]:[1,208] Message: Element type "null" must be followed by either attribute specifications, ">" or "/>". ...
System.Web.Services.Protocols.SoapException: java.lang.NullPointerException at System.Web.Services.Protocols.SoapHttpClientProtocol.ReadResponse(SoapClientMessage message, WebResponse response, Stream responseStream, Boolean asyncCall) ...
  • The Java VM default memory variable is changed to -Xmx768m. In versions 7.0.961 through 7.0.971, the default was -Xmx1024m. If there is insufficient memory available when Design Tool or Session Server starts, an error "[VHI 4300] The scripting manager failed to initialize" occurs, as described in Known Issues in KB 7021549.
  • When closing the Design Tool application after encountering the error "[VHI 4300] The scripting manager failed to initialize," there is no longer a Windows exception error ("Design Tool has encountered a problem and needs to close").
  • When deploying a model, if a management server is unreachable, other management server(s) are tried (in a management server failover cluster environment, as described in KB 7021563). In the previous release, only one management server was tried when deploying a model.

Security Enhancements

  • Support has been added for OpenLDAP and ApacheDS directory servers for authentication and authorization. This functionality was not supported in versions 7.0.961 through 7.0.971.
  • When using local OS groups for authentication as described in KB 7021567, and a domain user is in a local Windows group, authorization is successful. Such authorization was not successful in versions 7.0.961 through 7.0.971.
  • Fixed a cross-site scripting issue in Java web applications generated by Web Builder. Specifically, if a crafted URL attempts to pass <script> in the query string action= value, it is not executed when displaying an "I don't know how to perform” error.
  • In Design Tool, in the Session Setup and New Model dialog boxes, to enable SSL/TLS encryption for 3270 or 5250 host connections, check the "Use SSL/TLS" check box. In previous versions, "Telnet SSL" or "Telnet Extended SSL" was selected in the Transport Type list.
  • When session server is installed on any platform, a "securehost" subfolder is created for storing an optional private key and certificate for client authentication. In version 7.0, this subfolder needed to be manually created. For more information about securing host connections, see KB 7021544.
  • For enhanced security, installed .jar files are digitally signed.

Logging, Debugging, and Tracing Improvements

  • In Administrative Console, if you select "Terminate the Session from the Host" on a session in a Suspended state, the Model Debug Messages .vmr file is generated (when such recording is enabled). In version 7.0, the .vmr file was not generated when terminating suspended sessions.
  • If a session pool has some idle or active sessions connected to the host, and the model debug messages (VMR) recording option is changed (in the pool properties in Administrative Console), the change takes effect immediately. In versions 7.0.961 through 7.0.980, the change did not take effect for the existing idle sessions.
  • In the Administrative Console log viewer, international characters (such as in user names) are properly displayed. For more information about session server logging, see KB 7021303.
  • In the event of an unhandled exception in Design Tool or Session Server on Windows, a Windows mini-dump error report is automatically created. For more information on locating mini-dump files, see KB 7021355.
  • The log4j log files are now limited to 5 MB in size, with an additional 5 MB backup. In version 7.0, the log4j file size was unlimited, which could consume all available disk space. For more information about log4j, see KB 7021562.
  • Tracing is fixed for the Java event handler script engine. This type of tracing was not possible in versions 7.0.961 through 7.0.971. To enable log4j tracing, see KB 7021562.
  • If a client attempts to connect via domain to a session pool or model that does not exist on any server in the load distribution domain, the logged server error (message ID 2641) now includes the client IP address and VHI user name. In version 7.0.986 and earlier, these columns were blank.
  • When the session server is configured to Log All Messages, session pool names in the logged message text (such as message ID# 7) consistently match the session pool name in the logged Model/Session column. In versions 7.0.961 through 7.0.980, the logged values could be mismatched.

Design Tool and Event Handler Scripting Updates

  • If you open a model from a location where you do not have write permissions, Design Tool displays the following prompt:
[VHI 4820] The model <model name> cannot be opened from its current read-only folder. Do you want to copy this model to a different location and open it from there?

The default destination folder is <Documents>\Attachmate\Verastream\HostIntegrator\models, or you can select a different destination.

  • If you have a model using .NET event handler scripting code, and the model is not saved in a .NET trusted location (such as a network file server UNC path), the event handler script classes successfully load. Assemblies are automatically copied to a trusted location (%LOCALAPPDATA%\Attachmate\Verastream\HostIntegrator\TmpScripts\<model name>). In version 7.0, when event handlers could not be attached, the file names displayed in red font in the Attach Event Handlers dialog box.
  • In .NET event handler script code, you can successfully call vsEvent.Logger.LogInfoMessage("text"); to log a message. In version 7.0, this call resulted in an error such as the following:
[VHI 4309] An unhandled System.Runtime.Serialization.SerializationException exception occurred in the . . . event handler. Type WRQ.Verastream.HostIntegrator.EventContext in Assembly 'clrscriptserver, Version=7.0.961, Culture=neutral, PublicKeyToken=null' is not marked as serializable.

Other Updates

  • If you are licensed to use Development Kit in a performance/load testing environment, you can simply increase the maximum number of concurrent sessions in Administrative Console (from default 5 up to 5000). You can no longer install Windows Server Kit on top of Development Kit (or vice versa). For more information, see KB 7021583. Note: Regardless of session server capabilities, your concurrent session limit is governed by your product licensing.Do not configure more concurrent sessions than authorized by your license.
  • The scripts used to manually start, stop, and restart VHI services (installed .bat files) automatically change to the appropriate directory before executing, and change back when finished. Note: You must still run these scripts as an administrator. For information about manually starting and stopping VHI services, see KB 7021352.
  • Administrative Console can connect to the management server at "localhost" on Windows 7 or in other IPv6-enabled environments. In the previous release, such connection attempts could result in the following error:
Problem connecting to the management server on 'localhost:33000'
Reason: For input string: "0:0:0:0:0:0:1:33000"
Details: java.lang.NumberFormatException . . .
  • Administrative Console consistently displays pool names and associated sessions. In versions 7.0.961 through 7.0.982, after undeploying and/or re-deploying certain model/pool configurations, pool names did not display in Administrative Console until the management server was restarted.
  • Java Virtual Machines (JVMs) have externalized configuration files for changing the Classpath, Library Path, and additional command line parameters. These configuration files are located in the VHI etc subdirectory:
    • sessrvr.conf: Session Server (event handler script server and embedded web services SOAP stack)
    • destool.conf: Design Tool (event handler script server) and deployment tools (activatemodel, etc.)
    • logmgr.conf: Log Manager (session server logging)
    • webserver.conf: Web Server for Web Builder-generated Java web applications
    • vhi.conf: Default Java location for all of the above components

Note the following:

    • These files are intended for modification under direction of Technical Support only.
    • These files may revert to defaults when upgrading to a future release, service pack, or hotfix.
    • If the system environment variables vhi_embedded_xmx, vhi_embedded_classpath, or vhi_embedded_libpath were set for a previous release or as described in KB 7021334, they still take precedence.
  • If you have multiple systems running different VHI versions, and you attempt to deploy a model to a server running a newer version, there is now a more graceful exception that explains that the product version may be incompatible. Deployment attempts with the activatemodel command from versions 7.0.980 and earlier may result in a NullPointerException, such as the following:
Exception in thread "main" java.lang.NullPointerException
at com.wrq.vhi.mgmt.session.MgmtSession.getModels(MgmtSession.java:388)
at com.wrq.vhi.mgmt.ActivateModel.run(ActivateModel.java:99)
at com.wrq.vhi.mgmt.ActivateModel.main(ActivateModel.java:242)
  • Improved installer on Solaris and Linux platforms to support easier upgrades to future releases. (However, upgrading to this version 7.1 release on Linux/Solaris still requires manual steps, as described in KB 7021582 or 10094.)
  • On Windows, the installer title bar caption displays the full product version.

Obtaining Your Product Upgrade

Customers with a current maintenance plan are eligible to download Verastream Host Integrator 7.1 from the Attachmate Download Library at https://download.attachmate.com/Upgrades/.

For more information on using the Download Library, see KB 7021965.

For more information about installing the upgrade, refer to the appropriate Technical Note:

Additional Information

Legacy KB ID

This article was originally published as Attachmate Technical Note 10115.