Debugging Event Handlers

There are a variety of options available to test and debug event handlers.

See also the event handler API documentation for more information.

Validating and Testing Event Objects

The Validator, available on the Debug menu, confirms that libraries associated with event handlers are up to date. It is good practice to confirm that the event handler is returning the results you expect.

Stream Output

You can view the output your Java or .NET event handler code sends to the System.out (stdout) and System.error (stderr) standard streams. The output also includes the trap exception stack dump for unhandled exceptions, which can be useful if your event handler code is calling other third-party packages or assemblies.

Design Tool

Output is displayed in Debug > Event Handler Console and is written to the console even when the console is hidden. You can open the console after unexpected behavior occurs. To display the console when the Design Tool is run, open Settings > Event Handlers > Debugging and select Show when Design Tool starts.

Session Server

To provide maximum performance of the runtime session server, by default, the standard output and standard error stream information is discarded. However, you can redirect this information to a text file.

By default, the file, handlers.out is generated in the Micro Focus/Verastream/HostIntegrator/etc/output directory. However, you can set a different name with the vhi.script.output.filename property (Java) or OutputFilename setting (.NET).

No management is provided for any of the output generated by these properties. Any output recorded is simply appended to whatever content already exists in the output file.

See Guidelines for Developing Event Handlers for detailed information on event handlers in general and specifically on limiting the use of output streams to ensure performance efficiency.

Remote Debugging

Remote debugging enables you to use your IDE to set breakpoints in your event handler source code, step through code execution, and inspect variable values.

Load your event handler source code into the editor and set a breakpoint. Trigger the event and the breakpoint will be hit. Now you can step through the code and inspect the values of your variables.

For this Do this...
Java
  1. Verify that the debug port is enabled on the Java virtual machine that hosts the script manager. In the Design Tool, it is already enabled. For the Session Server, you must enable script manager debugging in the Administrative Console (server properties > General > Events) and restart the server.
  2. Note which port number is used. In Design Tool, see the Debug port assigned on the Settings > Event Handlers > Debugging tab. For the Session Server, see the Assigned event handler debug port in server properties. If the requested port is in use (such as when running multiple instances of Design Tool), an increment is used.
  3. Connect your Java IDE to this debug port
.NET To debug a .NET script in the session server or Design Tool, attach the Microsoft Visual Studio debugger to the script server. The name of the .NET script server process is clrscriptserver.exe. In Visual Studio, you can attach to this process using Debug > Attach to process.

In a development environment, you typically have two instances of clrscriptserver.exe, one for the session server and one for the Design Tool. The script server for the session server runs as user SYSTEM. To select it, make sure you check the Show processes from all users check box. The script server for the Design Tool is running as the same user as the Design Tool.

Event Handler Timeouts

When timeouts are enabled (the default), if you leave execution suspended at a breakpoint for too long, you may trigger a timeout condition.

Disabling event handler timeouts

You can disable event handler timeouts in both the Session Server and the Design Tool. When event handler timeouts are disabled, all timers used to calculate timeouts (for a single session) are suspended whenever that session has fired an event to the script manager. Once the script manager returns a response to the Design Tool or Session Server, the suspended timers will resume.

Testing event handler timeouts

Use these steps to test event handler timeouts, when they have been left enabled in Design Tool.

  1. Place a breakpoint in the event handler code activated by an event.

  2. Set the event handler timeout and client timeouts to a value larger than the time expected for the event handler activity.

  3. Cause the event to fire and stop execution at the breakpoint.

  4. Click Cancel while the event is in progress to force a timeout exception to be sent to the event handler.

    When an event takes more than a half second to complete, a progress window with a Cancel button displays. This is the same dialog box used for tracking the progress of procedures and operations. In some cases, this dialog box may already be open when the event handling condition occurs.

  5. Begin single-stepping through the event handler code to determine how the event handler reacts to the timeout.
Note: You may encounter a problem attempting to reset the script manager after a breakpoint is encountered. After you click Events > Reload Handlers, you may see the following error: "[VHI 4302] Error connecting to the script manager. It is likely that the script manager's TCP Listening port (9654) is in use by a third-party application." To resolve this issue, resume execution at the breakpoint in the debugger before you reload handlers.
Related Topics
Bullet Technical Note 10102: Capturing Traces in Host Integrator
Bullet Connection events test
Bullet Event handler best practices