Client Troubleshooting Checklist

  • Did the Web Start client fail to download?
  1. Check the Download and client troubleshooting checklist.
  2. Check the Web Start client troubleshooting checklist.
  • Were you prompted with an unexpected message regarding a plug-in?

If you are running Netscape 7.x browsers and the IBM Win32 1.4.0 JRE, you will be prompted to download a plug-in when you attempt to connect. To avoid this, upgrade your to V1.4.1.

  • Did the client receive an unexpected Z and I Emulator for Web login prompt?

When using the HTML-based or Combined models, the Z and I Emulator for Web client defaults to prompting for a Z and I Emulator for Web user ID and password if the Deployment Wizard files are not received from the Web server, or if they are not received in the expected format.

  1. Check that all the HTML files and all the /ZIEWebData/*.* files are loaded to the server. The HTML files must be in the publish directory, and the /ZIEWebData/ directory must be located under the Z and I Emulator for Web publish directory.
  2. Make sure the /ZIEWebData and your HTML file names are spelled correctly and have the correct upper and lower case characters in the name.
  3. For zSeries (S/390 or zOS), check the following:
    1. Check that all the HTML files have .ascii appended to the name. (*.html.ascii)
    2. Check that all the TXT files in the /ZIEWebData/ yourhtmlname directory have .ascii appended to them.
    3. Check that the files in the ZIEWebData/ yourhtmlname/*.* subdirectory have read, write, and execute permissions (also known as 755).
    4. Check that the files were uploaded as binary files to the Web server.
    5. Check for any Web server directives that might cause the request from the Z and I Emulator for Web client to be redirected or to download incorrectly.
  • Did the Z and I Emulator for Web Java applets fail with a java.net.NoRouteToHostException: No route to host: connect error?

When Microsoft IPv6 Developer Edition is installed on Windows XP, all Z and I Emulator for Web Java applets fail with a java.net.NoRouteToHostException: No route to host: connect error. This happens even if the protocol is disabled.

To fix this problem, try one of the following:

  • Are you not able to enter your Z and I Emulator for Web user ID or password on client login screen?

If you cannot enter user IDs and passwords on the login panel of the Z and I Emulator for Web client, try either using the IBM JRE plug-in, (or a new version of the plug-in), or clicking out of the field and onto the desktop and then back into the field.

  • Did your cursor disappear from the user ID field on the FTP login window?

When logging on to FTP sessions, the cursor may not appear in the user ID field and you may not be able to tab to it using the keyboard. If this happens, try upgrading to a later JRE.

  • Did the client download slowly?
  1. Check to see if other network traffic is also slow.
  2. Make sure other pages are not also downloading slowly. Try to download a non-Z and I Emulator for Web HTML file to see if the problem is a Web server problem. If it is a Web server problem, refer to your Web server documentation for more information.
  3. Check to see if port 8999 is active, if you are using the Service Manager to manage user configurations. The client may be trying to connect back to the Service Manager, using processor resources and therefore slowing any downloads. If the port is not active, activate it. Refer to the server's operating system documentation for more information regarding ports. Review this port information.
  4. If this is a dial-up connection, you can use the Z and I Emulator for Web Deployment Wizard to create a smaller client with only the features your users need to use.
  5. Check the Web server logs for errors.
  • Did you receive an online revocation server error?

You may see a security warning with the following error message when installing the Z and I Emulator for Web client using Internet Explorer:


An error occurred while accessing the online revocation server. 

This error message occurs when the Certificate Revocation option in Internet Explorer is selected. You will be unable to connect to the server to verify that the certificate has not been revoked. To prevent this message, disable the option by selecting Internet Options > Advanced > Security and unchecking "Check for Publisher's Certificate Revocation".

  • Is the Z and I Emulator for Web desktop appearing very slowly?

When there are 20 or more defined sessions, sometimes the Z and I Emulator for Web desktop may appear very slowly. The problem might be caused by the the amount of time it takes to process the large number of defined sessions. To prevent the delay using the HTML-based model, try the following steps:

  1. Divide the commonly-used sessions into smaller, separate groups, with one group per HTML file according to the users' requirements. This reduces loading time. If most of the sessions are randomly needed, move to the next step.
  2. Group the primary sessions together in one HTML file, adding one or two additional sessions that do not have the target host system defined (in properties). This allows individual users to define the target systems by using the Properties dialog box. Using this method, Z and I Emulator for Web remembers the session, but a user can change the session at any time.
  • Are you not able to type your password when launching the Z and I Emulator for Web desktop?

If you are not able to type your password when launching the Z and I Emulator for Web desktop from a Mozilla-based Netscape browser, try upgrading your JRE to a later version.

  • Are you waiting a long time for the client to download on OS/2?

When using the client on OS/2 with Netscape Communicator V4.61, you must wait for the download complete prompt before restarting the browser. It may take a few minutes for you to receive the prompt, however, this allows the client to finish any updates completely.

  • Do your sessions fail to appear when you launch the Z and I Emulator for Web desktop?

If you are using Windows Terminal Server and/or have a low display resolution, a NullPointerException may be thrown by the class file WVolatileImage, which can be seen in the Java Console. When this happens, users are not presented with their configured sessions. You can avoid this by setting a higher display resolution or by using the IBM 1.4 plug-in. If the HTML page has been created for the configuration server-based model, you can avoid this by adding the parameter <PARAM NAME=Bookmarking VALUE=false>.

  • Did you receive an error using the User Profile Manager on Netscape browsers with the Locally installed client?

If you receive the following error when using the User Profile Manager on Netscape browsers while loading the Locally installed client from the Start menu,


Cannot find the file C:\zieforweb\ZIEWeb_en.html (or one of its components). Make sure the path and
file name are correct and that all required libraries are available.

click OK and the Locally installed client will load in the browser.

  • Does repeatedly logging on and off Z and I Emulator for Web clients using Netscape cause the Z and I Emulator for Web clients to function improperly?

Logging on and off any of the Z and I Emulator for Web clients repeatedly without restarting the Netscape browser first can cause the browser to remove files from cache that are needed in order for the clients to function properly. The browser removes files in order to reduce the cache. Restart your browser after logging off and before logging on to any Z and I Emulator for Web clients while using Netscape to prevent problems with the clients.

  • Are you running multiple emulator sessions when using Netscape and Windows 98?

You can start a maximum of 10 to 12 Z and I Emulator for Web sessions in this environment.

  • Are you having trouble saving session configuration changes?

When using a Z and I Emulator for Web session, you can save session configuration changes, such as screen size and colors, in the following two ways:

  • close the session using the 'X' button in the top right corner or by selecting File > Save and Exit
  • right click on the session's green screen and select Save
  • Did you receive a LOG0001 message?
  1. A LOG0001 could be caused by a problem at the client machine. Check for Java errors or exceptions in the Java Console, TCP/IP errors in the network reaching the Service Manager machine, or caused by a mix of Z and I Emulator for Web clients. Use lcremove.html to remove the client.
  2. A LOG0001 could also be caused a problem at the Z and I Emulator for Web Service Manager machine. Check for a system abend, looping task, hung tasks, Java abends, check for error messages in NCoDServices.RAS.TXT.
  3. If there are no messages and the client appears to connect, check to see if all the Web server, Z and I Emulator for Web, and Telnet ports are active (especially port 8999). Review this port information.
  • Did the SSH FTP or VT session fail to start?

If your SSH FTP or VT session fails to start and you receive a java.lang.IllegalStateException: zip file closed , try upgrading your JRE. You may also try disabling the caching function of the Java plug-in's Control Panel.

  • Did you have problems while the IME keypad overlapped a session window (DBCS)?

If the IME keypad overlaps a Z and I Emulator for Web session window, you may get incorrect results when you click the mouse in the keypad.

  • Did resizing your Netscape 4.x browser on a Linux client cause you to log off admin?

With Netscape 4.x on a Linux client, you may not be able to resize the Administration window when you are configuring Z and I Emulator for Web. If you resize the Administration window, you may either be logged off the Z and I Emulator for Web server, or you will see the following message in the browser:


Your browser does not have JavaScript support or the support is not enabled.

Try upgrading your browser.

  • Are there exceptions in the Java Console after you reload the screen using Netscape Version 6?

When you reload a session by refreshing the browser screen or using Action > Refresh in Netscape 6, you will find the following exceptions in the Java Console. You can ignore the exceptions.


Exception occurred during event dispatching:

java.lang.NullPointerException: null pData

    at sun.awt.windows.WInputMethod.handleNativeIMEEvent(Native Method)
    at sun.awt.windows.WInputMethod.dispatchEvent(Unknown Source)
    at sun.awt.im.InputContext.dispatchEvent(Unknown Source)
    at sun.awt.im.InputMethodContext.dispatchEvent(Unknown Source)
    at java.awt.Component.dispatchEventImpl(Unknown Source)
    at java.awt.Container.dispatchEventImpl(Unknown Source)
    at java.awt.Component.dispatchEvent(Unknown Source)
    at java.awt.EventQueue.dispatchEvent(Unknown Source)
    at java.awt.EventDispatchThread.pumpOneEvent(Unknown Source)
    at java.awt.EventDispatchThread.pumpEvents(Unknown Source)
    at java.awt.EventDispatchThread.run(Unknown Source) 
  • Did Z and I Emulator for Web stop working after installing WebSphere Studio Application Developer - Integrated Edition?

During the installation of WebSphere Studio Application Developer - Integrated Edition (WSAD-IE) (formerly VisualAge(R) for Java), WSAD-IE sets the global environment's CLASSPATH to include the Z and I Emulator for Web J2EE connector. This connector has a version of the Z and I Emulator for Web code that is common to the Z and I Emulator for Web clients. In Netscape 4.x and Internet Explorer 5.x, the browser always loads Java classes from the system CLASSPATH before the network. This means that when WSAD-IE is installed, the browser loads some classes from the connector before loading the correct version of the class from the network.

During WSAD-IE installation, the Windows CLASSPATH is updated to include the following directories:


x:\IBM Connectors\class
x:\eab\runtime30 

These directories contain .jar files with classes that conflict with Z and I Emulator for Web classes. Most users do not need these directories in the classpath because they are used only for Java applications that use WSAD-IE's Z and I Emulator for Web connectors.

If Z and I Emulator for Web does not work after you install WSAD-IE, try the following workarounds:

  • Remove the WSAD-IE entries from the Windows CLASSPATH if you are not developing applications with the Z and I Emulator for Web connectors.
  • Change the browser to Netscape if the problem is occurring under Internet Explorer.
  • Use a batch file to set the CLASSPATH for a specific DOS window to eliminate IBM Connector classes, and then launch Internet Explorer (iexplore.exe) or Netscape (netscape.exe) from that DOS window to access Z and I Emulator for Web.
  • Did you encounter a gray screen when clicking the Users/Groups task on the cached administration client?

Using the administration client with Start Session enabled, you may encounter a grey screen when clicking on the Users/Groups task. If this occurs, try upgrading your Java 2 plug-in to the latest service level.

  • Did you check to see if the port is open?

Use Telnet or Netstat to determine if a port is accessible. Do the following:

  1. Type Netstat -a at a command line to see if the ports are active. If not, refer to your operating system documentation for information regarding activating ports.
  2. Check for messages in Z and I Emulator for Web message and trace log NCoDServices.RAS.txt, located in the \private directory.
  3. Check to see if a port on the Service Manager or through the firewall is active. Refer to your operating system documentation for instructions regarding how to run Telnet on other operating systems. For example, under Windows NT, use Telnet on the Windows client workstation try the following steps:
    1. Click Start > Run.
    2. Type telnet and click OK.
    3. Click Connect > Remote system on the Telnet window menu bar.
    4. Type the host name you want to connect to in the Host Name field on the Connect window.
    5. Type 8999 (or other ports based on the problem) in the Port field on the Connect window.
    6. Accept the default TermType.
    7. Click Connect.
    8. If you receive no messages, the port is open. If you receive Connect failed with 'Host name', then the port is not active. Remember to disconnect after you test each port by selecting Connect > Disconnect from the Telnet window menu.
  • Did you take a trace in case you need to contact the HCL Z and I Emulator for Web Support Team?

If you need to call the HCL Z and I Emulator for Web Support team, you can provide them a trace to help determine the cause of your problem. To learn more, click here.