Review the toolkit information in the Host On-Demand Information Center. The toolkit books are located under Host Access Toolkit in the left navigation frame. The Information Center also offers a search function that allows you to search the entire Information Center. The search function is especially useful when looking for information about a specific API.
Review the common problems listed in the Host Access Beans for Java Reference, located in the Information Center.
Review information about the different tools for debugging Host Access Beans applets and applications in the Host Access Beans for Java Reference, located in the Information Center. Available information includes how to incorporate the Host On-Demand trace functions (Trace Facility) and how to use the Presentation Space Debugger.
Did a customer-supplied applet fail to run with a Java 2-enabled browser? If a user runs a customized applet with a Host On-Demand emulator session (such as 3270 Display) launched from a Java 2 Host On-Demand client, and if this applet requires any Java 2 permissions, then you must take one of the following steps to meet the security requirements of Java 2; otherwise the applet will silently fail:
If you are reviewing thread usage, check that your customized code has executed the needed API to release threads. For example, if you use ECLSession, run startCommunication(), and then do a session.dispose(), all the threads will not be released until stopCommunictions() has executed.
All Abstract Windows Toolkit (AWT) threads are automatically spawned by Java as part of the AWT framework for managing GUI elements (for example, dispatching Java GUI events). The thread is controlled by Java runtime and no interfaces are available to start or stop the thread from an application program such as Host On-Demand or a HACL-based custom application.
Although your development effort may be targeting a specific version of the Host On-Demand Toolkit, you may want to maintain previous versions of the Toolkit library to use when troubleshooting. For example, if you are developing with version 9.0 of the Toolkit, and version 9.1 is available, see if the problem is present in both versions of the Toolkit libraries. You may also decide to compare previous releases, such as versions 7.0 and 8.0.
Comparing the behavior between different versions of JVMs is an important step when troubleshooting problems with the Host On-Demand Toolkit. If you notice a difference in behaviors with certain versions of JVMs, you are one step closer to discovering the source of your problem.
Sun Microsystems provides a bug reporting and bug parade service to registered users at no cost. It offers a searchable knowledgebase that allows you to find known bugs and possible fixes.
If you have a Windows environmental variable named CLASSPATH declared on your workstation, review the Sun Microsystems Java API documentation for how that environmental variable interacts with the javac.exe and java.exe classpath search order. The CLASSPATH may be referencing different JVM libraries that are incompatible with your intended JVM and custom libraries.
Other product installations using Java may have installed Java libraries that are named the same to support their application. Your application may be using these inappropriate libraries inadvertantly.
A quick test is to remove the CLASSPATH declaration temporarily. If this changes the behavior, this may be the cause of your problem.
Sometimes, custom code works fine when using Internet Explorer and Netscape with their native JVMs (jdk1.1), but does not work when the same applet code runs in a browser with a Java 2 plug-in. For example, with a Java 2 plug-in, the Java Console may report an unexpected ClassDefNotFoundException or NullPointerException error. In other cases, the Internet Explorer Java Console may report a security access violation.
If you are writing an applet to run in a browser, your custom code must set up the prerequisites needed to access resources outside of the protective sandbox (see the Java documentation).
The HOD Toolkit libraries make security-based method calls at
various points. The calls made internal to the the Toolkit APIs use IBM
digitally signed archives with the needed permissions granted.
Your custom code may also need to implement security provisioning,
This is a general Java requirement and is not specific to the Host On-Demand Toolkit.
Please study the appropriate Java documentation.
The following example can help you determine whether the Java 2 problem is related to the Security Manager. Create a file ${user-home-dir}/.java.policy with this content:
// JBuilder extensions for use with running/debugging Applets.
// Use for testing purposes only.
grant {
permission java.security.AllPermission;
permission java.net.SocketPermission "*","accept, connect, listen, resolve";
};
If your code suddenly works as it does with a jdk1.1 JVM, you will need to design your permissions differently.
Similarly, if you are using Internet Explorer and the Microsoft JVM, create a JAR archive for your custom code and specify the path to it in the following Registry entry:
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Java VM\TrustedClasspath
Note that specifying a path to an unsigned CAB file has no effect.
If the security violations disappear, place your custom code in a digitally signed CAB archive. If you have already done this, then you may need to assert or grant runtime security action permissions or privileges at certain critical points.
Remember that a Java class launched by java.exe using the main(...) entry point may not have a security manager in place unless you specify one; however, an applet class will always be monitored by the browser's resident security manager.
Use only the API methods and fields that are published in the Toolkit JavaDocs. Using unpublished APIs may result in unexpected consequences. Further, avoid using any published APIs that are labelled deprecated.
Deadlocks and race conditions are common in many programming languages, including Java. Symptoms include the following:
Check to see if adding a Thread.sleep(...) or System.out.println(...) affects the symptoms. Also, check to see if the symptom depends on how much processing you are doing in event handlers. Event handlers should be brief, so allow another thread to process your intensive work.
The success of client or driver code often depends on the timing of the network and host environment. If your code suddenly fails to run, the problem may be that some element in your environment has changed. Some changes that could affect timing include the following:
The Host On-Demand Toolkit has two powerful mechanisms to help you avoid failures due to implicit timing dependencies:
These two mechanisms are used in different situations, but each serve the same purpose. They are designed to help you meet the conditions required to maintain an interactive flow between your client and host when changes occur within your network and host configuration.
Infinite loops can consume a large amount of mainframe resources, especially when several clients are accessing the same middle-tier routines. Several simultaneous loops can even cause your mainframe to crash altogether.
Examine your code for loop flow control structures that might never satisfy the exit condition(s). Also check to see if you have provided for loop counting with escape code. Keep in mind that you can diagnose certain problems more easily on a client workstation than on a production mainframe.
Be aware that using HACL screenreco calls to satisfy a loop exit condition is not a good practice, for example, if you have a single HACL screenreco condition to satisfy loop termination and the host system continues to present an unanticipated variant screen.
The Toolkit provides listener classes that can alert your middle-tier code when a connection to a back-end host has been dropped spontaneously. Without this altering signal, your middle-tier code may flow through inappropriate paths.
Many dropped connections that are not explicitly cleaned up may slowly consume the entire thread pool.
Check to make sure that your GUI is designed to handle potentially harmful user actions. For example, some users may continue to click the same button over and over again when they are unsure if their original request is being processed. Write your middle-tier code to block redundant actions caused by successive user clicks and design your GUI to inform users of the status of their requests.
Design your code with fall back or roll back contingency flow paths in the event of errors. Your middle-tier code should be able to detect errors, for example, by means of tracing. Always check to be sure that what you expect to see on the screen is what actually displays.
HACL is the invisible 'green screen' API. Middle-tier code written with
HACL may receive a BELL, ALERT, or BEEP control code from a
back-end host. This is usually translated to the Java method
java.awt.Toolkit.beep(). This method is not a meaningful local hardware
call on a host machine and can be responsible for stopping screen updates. This
is a generic problem that is not specific to the Toolkit HACL
libraries.
One solution is to set a ECLSession constructor parameter pair: SESSION_QUIETMODE, SESSION_ON ("true"). Also, there is a RAWT (Remote AWT) helper library available for situations where the Java code will perform many GUI-centric Java calls. This library may be useful when you need to know that a iSeries ALERT has occurred.
If your code executes and reaches the end of the main(...) clause, but the contol does not pass back to the system after the JVM cleans up and exits, upgrade to Host On-Demand V8.0.1 to avoid this problem.
The Toolkit BEANS are 'aware of' and operate through the HACL APIs. However, the HACL APIs are stand-alone APIs and are 'unaware of' the BEANS API layer. This means that actions taken at the BEANS layer are extended to the HACL layer, and actions taken at the HACL layer are never directed back to the BEANS layer. The feedback loop occurs via a host response.
(Terminal/Session).getECLSession() is the backdoor to the HACL APIs underlying those BEANS. If you have written a BEANS-based applet/application, limit your use of the getECLSession() port to those actions that are not provided for in one of the BEANS APIs.
Run Applet can implement either ECLAppletInterface or CustomInterface. CustomInterface is the more powerful access port.
In order to synchronize properly, the applet call must meet certain preconditions or it will run past the host program. For example, the host connection must be active and the anticipated green screen content must have arrived from the host. Check to make sure these conditions are being met.
Although Host On-Demand emulator sessions are based on the BEANS and HACL APIs in the Toolkit, certain elements stand alone and are not included in the Toolkit, for example, the Host On-Demand desktop and the Service Manager. Additionally, IBM provides many non-Toolkit APIs designed to provide the value-add technology that produces the integrated Host On-Demand desktop emulator.
If you have not already, become familiar with the Programmable Host On-Demand API. The Programmable Host On-Demand API is a set of Java APIs that allows developers to integrate various pieces of the Host On-Demand client code, such as terminals, menus, and toolbars, into their own custom Java applications and applets. The API gives the developer complete control over the Host On-Demand desktop (what the user sees) without starting with the Host Access Java Beans found in the Toolkit. The underlying Host On-Demand code handles all the "wiring" of the various components, including saving user preferences, such as macros, keyboard remappings, and color remappings, to the local file system for future use. The developer must only determine the layout of the Host On-Demand desktop. For more information about the Programmable Host On-Demand API, see the Programmable Host On-Demand book in the Host On-Demand Information Center.
If you compile your Toolkit code with Java 2, but then the code fails to run with the native JVM in your browser, note the following. Since Host On-Demand V7, the Toolkit archive libraries come in two flavors: jdk1.1 and Java 2. The jdk1.1 libraries were compiled with ibmdjk1.1.8, and the Java 2 libraries were compiled with the most recently supported IBM version of Java 2.
The Toolkit BEANS classes that present a GUI have been subclassed so that it is java.awt-based for the jdk1.1 flavor and javax.swing-based for the Java 2 flavor. If you compile your custom application using the jdk1.1 flavor libraries, then that application will function in either a JVM 1.1 or JVM Java 2 runtime environment. If you compile your custom application using the Java 2 flavor libraries, then it is compatible to run within at least a Java 2 1.3 JVM runtime environment. If you attempt to run with a JVM 1.1 runtime environment, even with the swingall.jar library in the classpath, you will experience unrecoverable exceptions.
Although you can compile your code using jdk1.1 while running in a Java 2 JVM, you may experience certain side effects that are associated with mixing heavyweight and lightweight components. These effects are most pronounced when a Java 2-flavor Terminal beans is embedded in a java.awt.Frame that is repetitively constructed and disposed of. Support is very limited in this situation.
Code developed with Personal Communications APIs should be able to recompile using the Toolkit supplied libraries. However, you may need to code some additional session configuration parameters since there is no equivalent to the WS configuration file.
Note that the Personal Communications APIs are equivalent to and frozen at Host On-Demand V4 APIs, which is jdk1.1. The current Toolkit has many extensions and additions, some of which were not available for Host On-Demand V4. Since then, IBM has made important modifications to the behavior of the HACL screenreco classes, and recoding and changing the design are required. The base features of the Macro BEAN remain, but Toolkit Macro has doubled and tripled the number of available operational APIs.
