Technical Notes

Using Verastream Model Debug Messages
Technical Note 10065
Last Reviewed 14-Mar-2008
Applies To
Verastream Host Integrator version 6.0 or higher
Summary

The Model Debug Messages feature records activity of your Verastream model interacting with the host application, providing the detail that is sometimes necessary to diagnose and repair a malfunctioning model. This feature is particularly helpful for model designers working with VT (UNIX or OpenVMS) or HP hosts, where synchronization and related timeout issues are more common. This technical note describes how to use the model debug messages feature.

This technical note is organized into the following sections:

Recording Model Debug Messages

There are two ways to record model debug messages:

Design Tool: Model debug messages recording is always enabled for models you open in Design Tool.

Session Server: The Session Server can be configured to record model debug messages at runtime. (See Technical Note 10066 for details.) This feature is designed to minimize performance impact on the server. The recorded .vmr files can be later opened in Design Tool for analysis.

Opening Model Debug Messages

To open the Model Debug Messages dialog box in Design Tool, click Debug > Model Debug Messages. Alternatively, you can press Ctrl+Alt+M to open the Model Debug Messages dialog box.

To open a model debug messages .vmr file previously saved in Design Tool or recorded by a Session Server, do one of the following:

• In the Model Debug Messages dialog box, click the Open button.
• In Windows Explorer (on a system with Development Kit install), double-click the .vmr file.

Note the following:

• The Session Server writes .vmr files to subdirectories in <vhi>/etc/reports (or other configured Model Debug Messages Directory as described in Technical Note 10066). Since older .vmr files are automatically removed from the server (by default, after 7 days), it is suggested that you copy the files (or increase or disable the cleanup thresholds) if ongoing analysis may be necessary.
• To find your appropriate model debug messages file, the Session Server .vmr file name contains the model name and server Session ID. If the server is configured to record errors only, the .vmr file name also contains the failed Request ID. These ID numbers correspond to values that can be obtained in client code using connector GetSessionId() and GetLastRequestId() method calls.
• The .vmr file names that contain start, idle, and stop correspond to session pool activity before the first client request, between client requests, and during session logoff (respectively). For example, AccountLookup.502.idle.vmr contains any keepalive operations that are executed following client disconnection (from session ID 502) and before the next client connection. A new Session ID value is used each time a client connects, even if a session pool host session is re-used.
• The .vmr file should be opened with the same (or next) product version that recorded the file. You can use Design Tool to open a .vmr file that was recorded with the same or previous version. However, Design Tool is not designed to read a .vmr file that was recorded with a higher version.
• You can have up to five model debug message recordings open at the same time (which open as separate tabs in the Model Debug Messages dialog box). This enables you to compare model behavior under different circumstances or after you have made changes to the model.
• If you prefer to work with text files (instead of using the graphical Model Debug Messages dialog box as described below), you can convert .vmr files to text using the undocumented vmr.exe utility located in the VHI bin folder.

Using Model Debug Messages

The Model Debug Messages dialog box displays a message list on the left, and message details on the right.

Message List

See Figure 1 below for a sample model debug message list. Use the following toolbar buttons to manipulate the messages list:

Display all messages.

Display only datastream messages.

This option displays only messages that relate to the terminal exchanging data with the host, such as transmit, receive, and data processing messages. This option also displays entity arrival and departure, operation start and end, and errors associated with the datastream messages.

Display relative time for descendants (toggle option).

By default, descendant messages associated with an action such as navigating to another entity are displayed with the time of the descendant message. Click this option to show time that elapsed relative to the action's start. This option helps identify abnormal delays associated with specific messages.

Find a message.

Click this option and type in a string to locate a specific message. You can also use the Find Message dialog box to find other occurrences of the messages, or to find messages of the same type as the selected message.

Find next error.

Click this button to locate the messages that are tagged as errors in the model debug messages list.

Clear all messages. (Actions that are in progress will not be cleared.)

Use this option when you are debugging a development version of a model and want to see the model's behavior after making some changes. You can save the previous collection of model debug messages before you use this option.

If you have opened an additional model debug message .vmr file, click this button to close the file. (The Current Model tab cannot be closed.)

Message Details

The right panel of the Model Debug Messages dialog box shows the details of the message selected on the left. Depending on what type of message is selected, the right panel will show one or more of the following:

• Ending snapshot: A view of the terminal screen (see Figure 2 below). The grey area of the snapshot represents the area of the screen that changed during the course of action. With character mode hosts, this is helpful for discovering a partial screen update when a full screen of data was expected to be processed. This feedback makes it easy to identify where a synchronization issue needs to be handled.
• Starting and ending snapshots: When a navigation message is selected, both the "before" and "after" terminal screens are displayed.
• Message: When an error or operation message is selected, the message text is repeated in the lower-right panel. This text can be selected and copied to the clipboard by using the right-click menu or Ctrl+C keystroke.
• Procedure data: When a procedure message is selected, the procedure filter parameters and procedure output are displayed. You can use the Copy button to copy the filter parameters or procedure results to the clipboard.
• Datastream: When a datastream message is selected, the data sent to or received from the host is displayed in the lower-right panel. See also the Datastream Panel section below.
• Client Requests: When a client request message is selected, the details of the request and the response are displayed.
• Event Handlers: When a fire event message or event callback message is selected, the input and output of the event or callback is displayed.

Datastream Panel

When a datastream message is selected, the datastream panel provides the following functionality:

• You can view the raw data sent to and received from the host. Nonprintable characters, such as control functions, appear in blue text.

• When debugging a VT model, use the Suggest Escape Sequence button to have the model debug messages utility suggest a unique trailing escape sequence (if present) that can be used to help synchronize the model.

• Use the Next Match button to move to the next occurrence of the entered string.

• Use the Previous Match button to move to the previous occurrence of the entered string.

Locating and Solving a Synchronization Problem

If your model does not reach an expected entity or cursor location, review the model debug messages. The example below shows a sequence on a VT host for a PageDown operation.

The final message, indicating unexpected bytes received from the host, is a strong indicator of a synchronization problem with the host. By reviewing the messages preceding this message, you can narrow down the source of the problem.

The highlighted message, "Operation AddressBook.PageDown arrived at AddressBook (primary)" has the associated ending snapshot on the lower-right panel:

With a PageDown operation, a full screen of data should have been processed, but the action and the associated snapshot shows only a subset of the host screen (with a gray background) was actually received.

To ensure that all of the expected data is processed before proceeding, you can add a WaitForCommString command to the operation. Use the Suggest Escape Sequence button as described in Datastream Panel section above.

Note: There may be cases where a synchronization issue does not produce a message that unexpected bytes were received from the host, especially when running on the server. It is a good idea to look for partial operation snapshots similar to the one above whenever the model does not reach an expected entity or cursor location.

Related Technical Notes

10018	Tools for Troubleshooting Verastream Host Integrator
10020	What is Character Mode?
10023	Character Mode Models -- Modeling Tips
10066	Configuring Recording of Model Debug Messages on the Verastream Server
40999	Verastream Host Integrator Technical Notes