This section describes the different tools for debugging Host Access Class Library (HACL) applets and applications and how to use them.
HACL incorporates a trace mechanism that will fire trace events to any trace facility that implements the proper interface. A HACL user can route the trace events to their own trace facility, or they can use the trace facility provided by Host Access (see RASTrace) which provides a user-friendly, windowed interface to enable, disable, and format the trace events. This trace facility is found in hatrace.jar.
A HACL user that wishes to use their own trace facility must provide a class that implements the ECLTraceListener interface. This interface contains one method that receives an ECLTraceEvent as a parameter. The trace listener is passed to the static ECLTrace class. There are two methods used to add a trace listener to the ECLTrace class. When a trace listener is added, it will immediately receive trace events with a type of ECLTraceEvent.REGISTER from each of the HACL components that allow tracing.
Trace levels for the various HACL components are controlled by the SetTraceLevel() method of the ECLTrace class. The component name and desired trace level are parameters for this method. The default trace level for each component is 0 which means that tracing is disabled until enabled by calling SetTraceLevel(). Enabling tracing on a component enables tracing for that component in all sessions.
The trace facility supports different trace levels from 1 to 3. Each trace level is cumulative with the previous trace level, with 1 producing the least trace information and 3 producing the most. Trace level 1 generates trace information for method entry and exit, including method parameters and return values. Trace level 2 generates all the trace level 1 information plus some additional information. Trace level 3 generates all the trace level 2 information plus a LOT of additional information, right down to the bytes going through our transport layer to and from the host.
The following sample shows how to construct an ECLSession and enable tracing for the ECLPS and DataStream components using the default Host Access trace facility. For another example, see the Trace sample found in the toolkit\hacl\samples\TraceDemo.
import com.ibm.eNetwork.HOD.trace.RASTrace;
import com.ibm.eNetwork.ECL.trace.ECLTrace;
import com.ibm.eNetwork.ECL.*;
try {
// Use the default HACL trace facility
RASTrace myTraceListener = new RASTrace();
myTraceListener.setVisible(true); // Display the trace GUI
myTraceListener.setEnabled(true); // Start logging trace events
// Receive trace events from all sessions
ECLTrace.RegisterTraceEvent(myTraceListener);
// Enable PS and DataStream for minimum tracing
ECLTrace.SetTraceLevel(ECLTrace.SESSION_TRACE_PS, ECLTrace.TRACE_MINIMUM);
ECLTrace.SetTraceLevel(ECLTrace.SESSION_TRACE_DS, ECLTrace.TRACE_MINIMUM);
Properties p = new Properties();
p.put(ECLSession.SESSION_HOST, new String("myHost"));
ECLSession s = new ECLSession(p);
}
catch (PropertyVetoException pve) {}
catch (ECLErr e) {}
ECLTrace provides the following constants for the traceable components. These constants are used as parameters to the SetTraceLevel() methods.
Constant |
Component Traced |
|---|---|
| SESSION_TRACE_SESSION | ECLSession |
| SESSION_TRACE_PS | ECLPS |
| SESSION_TRACE_FIELDLIST | ECLFieldList |
| SESSION_TRACE_FIELD | ECLField |
| SESSION_TRACE_OIA | ECLOIA |
| SESSION_TRACE_ERR | ECLErr |
| SESSION_TRACE_XFER | ECLXfer |
| SESSION_TRACE_OIA_EVENT | ECLOIAEvent |
| SESSION_TRACE_PS_EVENT | ECLPSEvent |
| SESSION_TRACE_COMM_EVENT | ECLCommEvent |
| SESSION_TRACE_SD | ECLScreenDesc |
| SESSION_TRACE_SCRN_RECO | ECLScreenReco |
| SESSION_TRACE_PRINTER | Printer |
| SESSION_TRACE_DS | Datastream |
| SESSION_TRACE_TRANSPORT | Transport |
| Note: In earlier versions of HACL, the trace GUI would be
displayed whenever the trace level was set on a component. In this version, the default
trace GUI will not be displayed unless you have set Visible(true) on your RASTrace object. In addition, in earlier versions, tracing of HACL components was controlled by passing a string in with the ECLSession.SESSION_TRACE property key to enable tracing of selected components. For example,
This method will still work to set the TraceLevel for each component but the new way of using the SetTraceLevel() method on ECLTrace is the preferred way and this older method is deprecated. |
HACL incorporates a presentation space debugger which can be activated programmatically by providing special parameters to the ECLSession constructor or using the ECLSession.ShowPSDebugger() method. The presentation space debugger provides a windowed interface which can be used to peek at the various planes which comprise the complete presentation space. It has the ability to show the text, field, color, extended field, DBCS, and grid planes.
The presentation space debugger does not allow interaction with the presentation space.
The following sample shows how to construct ECLSession and activate the presentation space debugger.
Properties p = new Properties();
p.put(ECLSession.SESSION_HOST, new String("myHost"));
p.put(ECLSession.SESSION_PS_DEBUGGER, "");
ECLSession s = new ECLSession(p);
HACL applets can also be debugged using the Run Applet feature within Host On-Demand. Debugging user applets in this environment has a few advantages over the presentation space debugger. First, the emulator screen is interactive, allowing the applet developer to help the applet navigate problem screens while finding solutions to applet problems. This environment also contains the operator information area (OIA) which contains valuable information such as the cursor position and status information about the connection with and the state of the host.
The tradeoff in using the Run Applet feature rather than the presentation space debugger is performance. Applets may run more slowly because of the additional overhead of a full function emulator.
To run applets through Host On-Demand, the applet must implement ECLAppletInterface or CustomInterface.
These interfaces provide the methods for passing the active session to the applet.
[ Top of Page | Previous Page | Next Page | Table of Contents]