Technical Notes

Tools for Troubleshooting Verastream Host Integrator
Technical Note 10018
Last Reviewed 23-Feb-2007
Applies To
Verastream Host Integrator version 5.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.

Write Attributes Test

Use this feature to test the Host Integrator's ability 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 > Write Attributes Test.

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.

Datastream Window

Note: This tool is available in version 5.5 and earlier, for VT and HP emulation only. Beginning in version 6.0, use Model Debug Messages instead.

This window displays the real-time data sent and received from a character mode host. As the terminal processes characters, you can copy and paste text from this window into the WaitForCommString command dialog box or the Host Communication String event dialog box to configure operations that include raw host communications. This window may also show some system events interspersed with the datastream for functions like entity validation, navigation of operations, and user-defined events.

Without this window, it is difficult to determine what effect a single key has on the character host. What appears to be a simple cursor move can often be three packets of 50 or more characters. Lack of knowledge about these internal communications can often lead to missed synchronization points. In addition, this feature will expose the order data that comes from the host, making it easier to choose which data to use for synchronization.

To access this feature, open a model that uses VT or HP emulation, connect to the host, and then click Debug > Datastream Window.

Model Logs

Host Integrator can log model errors and issue warnings and informational messages about recent Design Tool actions.

To configure the Host Integrator logging feature, click Debug > Event Log > Logging Options.

To view the log file, click Debug > Event Log > View Logs. Select the log file (.applog), and then click View Log.

Server Troubleshooting Tools

Use the following server troubleshooting tools to troubleshoot your Verastream models.

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.

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