Technical Notes

Tools for Troubleshooting Verastream Host Integrator
Technical Note 10018
Last Reviewed 11-Sep-2008
Applies To
Verastream Host Integrator version 6.0 or higher
Summary

This technical note describes the tools available in Verastream Host Integrator that can be used to troubleshoot your model and runtime issues.

This document is presented in the following sections:

For further details on each troubleshooting tool, see the online help.

Design Tool Troubleshooting Tools

To validate and troubleshoot Verastream models, use the following Design Tool features and tools. Before using these tools, open your model in the Design Tool.

Model Validator

The Model Validation tool evaluates your host application model for errors by validating variables, entities, and tables.

Note: The Validator must report no problems with your model before you will be able to deploy the model from the Host Integrator Server.

To validate a model:

1. Click Debug > Validator.
2. Select the model elements you want to evaluate: Variables, Tables, or Entities.
3. Click Validate. When the validation concludes, a validation report will appear under Validation results.

Signature Analyzer

All entities within your model must have a unique signature. Use this feature to compare the patterns (definitions and properties) and validate the signatures of any two entities in your host application model. Each entity must have a unique signature.

To access the Signature Analyzer, click Debug > Signature Analyzer.

Note: To use this feature, you must either be connected or in offline mode.

In the left portion of the Signature Analyzer dialog box, select the two entities to compare from the Entity and Compare To drop-down lists. (Miniature versions of the entities help you visualize the entities you are comparing.) At the top center of the dialog box, there are two icons representing the primary entity and the entity you are comparing it to.

• If the two entities match, both icons are green. Modify the signature of one of the entities.
• If the entity you are comparing to the primary does not match, it appears in yellow. No modifications are necessary.

To verify validation patterns, conditions, or cursor positioning wait options that are defined as part of an entities signature, use the features on the Validation tab.

Navigator

The Navigator dialog box displays a graphical representation of the entities and operations in your model. Use the Navigator to review the structure of your host application. The Navigator can also test traversal operations in your model to ensure that there is a valid traversal operation that can reach every entity in your model. You can use the Navigator either while you are connected to the host or running in offline mode.

To access the Navigator, click Debug > Navigator.

Navigation from the home entity is displayed by default. To verify navigation from another entity, select the entity from the drop-down list.

The following symbols are used in the Navigator:

Command Debug

This dialog box is used to debug operations created in the Design Tool (such as a move cursor, login, or logout script). To use this feature, you must be connected to the host.

To test and debug a command list:

1. Click Debug > Debug Command List.
2. Select the operation or script to test from the Name drop-down list and click Run to run the entire operation or script. The Design Tool runs through each command listed and then reports the operation's success or failure in the Status box.

• To stop execution of the command list as it is running, click Stop.
• To step through the operation or script, click Step instead of Run. Click Skip to pass over an operation.
• To select a new operation or script, click Refresh, and then make your selection from the Name drop-down list.

Test and Debug Procedures

Use this feature to test and debug table procedure definitions before deploying your model.

Note: To test a table's procedures, you must either be connected to the host and have access to the application the model is based on, or you must load the model in the Host Emulator and connect to the Host Emulator.

To test a procedure, follow these steps:

1. With your model loaded in the Design Tool, connect to the host (or, load the model in the Host Emulator, and then connect to the Host Emulator).
2. Click Debug > Procedure Test.
3. In the Table drop-down box, select the table containing the procedure you want to test.
4. In the Procedure drop-down box, select the procedure you want to test.

5. In the Value column, enter test data for the parameter.

6. Click Execute.

7. Click Clear to reset the values and perform another test or click Close to close the Procedure Test dialog box.

If you experience problems with a procedure used to satisfy an SQL query or you want to fully investigate the behavior of a procedure, you can debug it in the Debug Procedure dialog box.

To debug a procedure:

1. Follow steps 1 through 5 above.
2. Click Debug. This opens the Debug Procedure dialog box. This utility allows you to Run, step through, and set break points in the procedure. The features differ as follows:

• Click Run to run the procedure.
• Click Step Into to start stepping though the procedure.
• Click Step to step forward through the procedure logic one line at a time.

• Click Step Out to end the step through and return to the previous level.
• Click Set Break to set a break point in a procedure that pauses the operation at a chosen point. This aids in debugging procedure logic.

Recordset Test

The Recordset Test feature allows you to test recordsets before the model file is deployed to the Host Integrator Server and accessible to the AppConn Java or COM connectors. All of the recordset actions simulate the capabilities of AppConn recordset methods provided with the connectors. This dialog box allows you to test these methods with the host application model before using the connectors to create a client application.

Note the following:

• To test a table's recordsets, you must either be connected to the host and have access to the application the model is based on, or you must load the model in the Host Emulator and connect to the Host Emulator.
• This feature is only available if the current model contains recordsets.

To test a recordset:

1. With your model loaded in the Design Tool, connect to the host (or, load the model in the Host Emulator, and then connect to the Host Emulator).
2. Navigate to the entity containing the recordset.
3. Click Debug > Recordset Test.
4. Select the recordset and action from the drop-down boxes.
5. Click Execute to execute the selected action.
6. Repeat steps 4 and 5 for each recordset and action you want to test.

SQL Test

Use the Test SQL dialog box to test SQL queries on the tables you created for your host application model. This allows you to debug your table and procedure definitions prior to deploying your model. Before you can run an SQL test on a host application model, you must first create tables derived from the model that contain the data that you want to query.

Note: To perform test an SQL query on your model tables, you must either be connected to the host and have access to the application the model is based on, or you must load the model in the Host Emulator and connect to it.

To test an SQL query,

1. Click Debug > SQL Test.
2. Enter a supported SQL-92 statement in the SQL statement box of the Test SQL dialog box.
3. Click Resolve, and the Design Tool returns the results.

Attributes Test

Use this feature to test the Host Integrator's ability to read data and to store and write attribute data to the terminal screen before deploying your model to a Host Integrator Server. The execution of an attribute write test from within the Design Tool simulates the capabilities of the SetAttributes method provided with the AppConn APIs. This simulation is accomplished in the Design Tool by using UpdateAttribute and UpdateAttributes commands in conjunction with attribute input commands in operations. By simulating these calls, you can accurately test these methods with the host application model before using the connectors to create a client application.

To access this feature, click Debug > Attributes Test, and then click the Read tab or the Write tab.

This test tool can also be accessed from the text button on the Attributes tab:

Note: To use this feature, you must be connected to the host.

Model Debug Messages

This tool is available in version 6.0 or higher. For more information, see Technical Note 10065.

Connection Events Test

Use the Connection Events Test utility to test sequences of events that require a reset of the terminal session: connecting to the host and establishing a client connection. You can perform tests in both dedicated model and pooled session environments.

To confirm that the life cycle event handlers and model event handlers you have added to your model are performing as you expect, click Debug > Connection Events Test.

Note the following:

• In order to use the Connection Events Test, the model must be connected to the host, but login is not required.
• The Connection Events Test menu option is only available if the model includes a life cycle event handler.
• If the event handler requires a user name and password, enter these details into the Credentials fields.

To simulate the sequence of one client application disconnecting and another client connecting to this model using the ConnectToModel API, under Dedicated session, click New Client.

Session to simulate destroying and creating a pooled session, then connecting to the session using the ConnectToSession API, under Pooled sessions, click New Session.

To simulate the sequence of one client application disconnecting and another client reconnecting to this model using the ConnectToSession API, under Pooled sessions, click New Client.

Event Handler Console

The Event Handler Console displays the output that event handlers have sent to the System.out and System.err streams. Also, any unhandled exception that is not an ApptrieveException or EventTimeoutException causes a stack dump to be written here.

You can use the remote debugging features in your Java development environment to set breakpoints, step through code, and view runtime status.

Host Integrator writes to the console even when it is hidden, so you can open it for information after some unexpected behavior occurs.

To access the Event Handler Console in Design Tool, click Debug > Event Handler Console. For more information, see http://docs.attachmate.com/verastream/vhi/6.5/help/designtool/h_dlg_event_handler_settings_debugging.html.

See also the runtime server equivalent Event Handler Output below.

Server Troubleshooting Tools

Use the following tools to troubleshoot your Verastream models on the runtime server.

Session Monitor

The Session Monitor is a standalone Java application that allows an administrator to view real-time screens of host sessions that are running on a given Host Integrator Server. Session Monitor provides the following:

• Secure access using AADS
• Display of all host screens (3270/5250/HP/VT)
• Ability to record and play back screens

The Session Monitor is similar to the View Session feature currently available through the Administrative WebStation, but it is intended to be faster and more useful as a real-time debugging tool.

The Session Monitor tool (if selected during installation) can be accessed from the Host Integrator program shortcuts installed on the Start menu.

Model Debug Messages

This option is available beginning in version 6.0. The .vmr files generated by Session Server can be opened in Design Tool for analysis. For more information on configuring the server to record model debug messages, see Technical Note 10066.

Server and AADS Logs

Host Integrator can log server errors and issue warnings and informational messages as it runs. For more information on configuring logging and viewing logs, see Technical Note 40032.

Event Handler Output

Equivalent to the Design Tool Event Handler Console, the runtime Session Server writes output to the <VHI>\etc\output\traps.out file (by default). Note: To avoid runtime performance impacts with event handler System.out and System.err streams, see http://docs.attachmate.com/verastream/vhi/6.5/help/designtool/event_handler_design.html#output.

Related Technical Notes

10019	Obtaining Host Integrator Traces and Configuration Files for Technical Support
10065	Using Verastream Model Debug Messages
10066	Configuring Recording of Model Debug Messages on the Verastream Server
40032	Verastream Host Integrator Server Logging
40999	Verastream Host Integrator Technical Notes