Troubleshooting Guide

Table of contents

Z and I Emulator for Web tracing checklist

Z and I Emulator for Web offers the following types of tracing options:

Basic traces
Advanced traces
Service Manager
Redirector
Information Bundler

Basic Traces

Basic traces gather information about problems when the client does not download as expected. They also capture the Z and I Emulator for Web configuration information.

Take the following steps to enable Basic tracing:

  1. Open the Z and I Emulator for Web Deployment Wizard to create a new or edit an existing HTML file.
  2. Click through the windows until you reach the Additional Options window.
  3. Click the Advanced Options button.
  4. Click Problem Determination in the left tree view.
  5. Select Basic. Optionally check the 'Include problem determination components' box. The 'Include problem determination components' box will already be checked by default if you are editing an existing HTML file that was created with problem determination configured.
  6. Click OK.
  7. Finish creating your HTML file.

When a problem occurs, open the browser's Java Console and copy the contents to a text file (*.txt). Make sure you obtain all the Java Console entries. The Java Console might be multiple windows in length. For more information, refer to Displaying the Java Console.

Advanced Traces

Advanced traces capture the telnet traffic between Z and I Emulator for Web and the host telnet server. Z and I Emulator for Web offers the following types of Advanced tracing:

Transport
IPMON
Service Manager
Redirector

Transport

You can enable Transport tracing by adding the TraceOptions parameter to the APPLET tag in your HTML file. The easiest way to add this parameter is using the Deployment Wizard. However, you may also add this parameter manually by directly editing the HTML code. Refer to Manually configuring Advanced debugging for more information.

Take the following steps to enable Transport tracing using the Deployment Wizard:

  1. Open the Z and I Emulator for Web Deployment Wizard to create a new or edit an existing HTML file.
  2. Click through the windows until you reach the Additional Options window.
  3. Click the Advanced Options button.
  4. Click Problem Determination in the left tree view.
  5. Select Advanced.
  6. Enter the name of the log file in the 'Log file name' field. The Deployment Wizard provides the default file name trace.txt, but you can change it if you wish. For Unix-based client platforms, include the absolute path to where you want to save the file. For Windows client platforms, if you do not specify an absolute path, the log file will be saved to the client desktop.
  7. Select 'Enable transport trace'.
  8. Click OK.
  9. Finish creating your HTML file.

When a problem occurs and you have enabled Transport tracing, take the following steps:

  1. Start the Z and I Emulator for Web client. Once the desktop appears, the Z and I Emulator for Web Automatic Component Trace window appears noting that tracing has started.
    Note: You might have to move other windows around to find this window.
  2. Click the session icon, if the session does not auto-start.
  3. Switch to the emulator window and recreate the problem. Do not close the trace window.
  4. When the problem occurs again, select the Z and I Emulator for Web Automatic Component Trace window. The window might now be hidden behind other windows. Select the 'END' trace option and click OK.
  5. Open the browser's Java Console and copy the contents to a text file (*.txt). Make sure you obtain all the Java Console entries. The Java Console might be multiple windows in length. For more information, refer to Displaying the Java Console.

IPMON

For an overview of IPMON, see IPMON in this Troubleshooting Guide.

Take the following steps to enable IPMON tracing:

  1. Open the Z and I Emulator for Web Deployment Wizard to create a new or edit an existing HTML file.
  2. Click through the windows until you reach the Additional Options window.
  3. Click the Advanced Options button.
  4. Click Problem Determination in the left tree view.
  5. Select Advanced.
  6. Enter the name of the log file in the 'Log file name' field. The Deployment Wizard provides the default file name trace.txt, but you can change it if you wish. For Unix-based client platforms, include the absolute path to where you want to save the file. For Windows client platforms, if you do not specify an absolute path, the log file will be saved to the client desktop.
  7. Select 'Enable IPMonitor trace'. If you are using the HTML-based model, the 'Session name' field is prefilled with the name of the current sessions that you are configuring. If you are using the Configuration server-based or Combined models, you must manually enter the name of the session that you want to trace.
  8. Click OK.
  9. Finish creating your HTML file.

When a problem occurs and you have enabled IPMonitor tracing, take the following steps:

  1. Start the Z and I Emulator for Web client.
  2. Once the Z and I Emulator for Web desktop appears, right click the session icon and select Start Session with IPMONITOR.
  3. The IPMonitor V1.0 for Java, automatic mode window appears noting the trace has started.
    Note: You might have to move other windows around to find this window.
  4. Switch to the emulator window and recreate the problem. Do not close the trace window.
  5. When the problem occurs again, select the IPMonitor V1.0 for Java, automatic mode window. The window might now be hidden behind other windows. Click Stop and then click Save and Exit. Confirm the location where the trace file is saved and the file name.
  6. Open the browser's Java Console and copy the contents to a text file (*.txt). Make sure you obtain all the Java Console entries. The Java Console might be multiple windows in length. For more information, refer to Displaying the Java Console.

Service Manager

The Service Manager trace facility is available through the Services page of the Administration window.  Use this facility to gather troubleshooting information about the Service Manager. From the Services page, click Service Manager Trace to start and stop tracing and set the trace level.  See Z and I Emulator for Web services for more information.

Redirector

The server trace and message facility is always installed and is available through the Services page of the Administration window. From Services, you can start and stop Redirector tracing and view the server's Trace/Message Console, which lets you see the trace and message information on the screen. The information is also saved in NCoDServices.RAS.txt in the private directory. You can look at this file with any ASCII text editor. See Z and I Emulator for Web services for more information.

For more detailed information about tracing on the server, see Tracing on the server.

Information Bundler

Use the Information Bundler to collect diagnostic information from a Z and I Emulator for Web server. The Information Bundler stores copies of the following in a ZIP file:

User-defined font files will not be present on the Z and I Emulator for Web server unless created by the user.

The ZIP file can then be sent to your HCL Support Center to assist in diagnosing problems.

You can run the Information Bundler through a graphical user interface (GUI) on all supported platforms except Novell, i5/OS, OS/400, and z/OS, or through the command line.

Running the Information Bundler

To run the Information Bundler, do the following:

In these commands, install_dir is the installation directory for the Z and I Emulator for Web software.

To see a list of the command line options, invoke the Information Bundler without any parameters or with the -? parameter. For more information, see Information Bundler command line options.

Information Bundler GUI

The Information Bundler GUI is available on all supported platforms except Novell, i5/OS, OS/400, and z/OS. To access the GUI, invoke the Information Bundler with the -gui parameter.

The Z and I Emulator for Web Information Bundler window opens.

  1. Specify the desired Z and I Emulator for Web publish directory, if it is not the default publish directory.
  2. Specify the alternate Z and I Emulator for Web publish directory for Deployment Wizard files. This field should be set to the same path as the Directory field in the Deployment Wizard Summary panel. The default path is the Z and I Emulator for Web publish directory.
  3. Select the types of information to be gathered. If you are gathering IPMonitor trace information, specify the name of the trace file. To do this, select the IPMonitor Trace Files button, which opens a separate dialog. Then, browse to a particular .TLG file or search a directory for .TLG files.
  4. Specify the output file.

    The default output file is install_dir\private\ziepd.zip.

    Any existing output file will be overwritten. You will not be prompted first.

    If you select to rename the output file, the Information Bundler will not automatically add a .zip extension to the file.

  5. Click OK. The selected files are added to the ZIP output file.

Information Bundler command line options

The Information Bundler can be accessed through the command line on all supported Z and I Emulator for Web platforms.

To see the command line options, run the Information Bundler from the command line with the -? parameter or without any parameters.

For information on running the Information Bundler on all Z and I Emulator for Web platforms, see Running the Information Bundler.

In order to specify all the command line parameters that you want to specify, you may need to edit the line of the command script that invokes the Information Bundler. Originally, this line specifies a limited number of symbolic parameters (such as, %1 %2, and so on, or $1 $2, and so on) instead of actual parameters.

On platforms that support the GUI, if you want to run the Information Bundler with command line options rather than with the GUI, edit the line of the command script that invokes the Information Bundler to remove the -gui parameter. Otherwise, the -gui parameter will override the command line options.

Adding a custom extension to the Information Bundler

You can add custom extensions to the default Information Bundler configuration file, infbnd.properties. You can also specify a different configuration file. The configuration file indicates what types of information can be selected to include in the ZIP file. You can also add new types of information and specify which files will be gathered when that new type is selected.

To specify a different configuration file, use the -cfg parameter, followed by the name of the configuration file that you would like to use. A path name that is not absolute will be searched for, starting in the Z and I Emulator for Web installation directory. For more information on command line options, see Information Bundler command line options.

To add a custom extension to the default configuration file, follow these steps:

  1. Make a backup copy of the infbnd.properties file, which is located in the Z and I Emulator for Web publish directory.
  2. Choose one of the 32 extension information categories (Extension01 - Extension32), and add the category to the InfoCategoryList. The following example shows the default InfoCategoryList with Extension01 added to the end: InfoCategoryList: \ HODRegKeys ; \ PrivateDir ; \ SecurityFiles ; \ HTMLFiles1 ; \ PropFiles1 ; \ JavaScriptFiles ; \ NSMPropFiles ; \ DepWizFiles ; \ PrtDefFiles ; \ DirUtilFilesWin32 ; \ DirUtilFilesNonWin32 ; \ UdfFiles ; \ Extension01
    In the above example, be sure to place a '\' character at the end of the line after UdfFiles.
  3. Modify the sample Extension01 InfoCategory at the end of the infbnd.properties file.
  4. Modify the sample WorkItem elements for Extension01 at the end of the infbnd.properties file.
  5. Copy the updated configuration file to the Z and I Emulator for Web publish directory.
  6. Run the Information Bundler with the updated configuration file.
  7. Run the Information Bundler from the console rather than using an icon in order to see if there is an error in the new configuration file. If there is an error, the Information Bundler will write a general error message to the console and will write a description of the specific error into the log file. The log file is named infbnd.log and is located in the install directory.

The following are definitions of the elements used in the configuration file:

InfoCategoryList and InfoCategory names
The InfoCategoryList is the top-level element of the configuration file. This element consists of the term InfoCategoryList, followed by a list of InfoCategory names. Examples of InfoCategory names are: HODRegKeys, PrivateDir, and SecurityFiles. Each InfoCategory name refers to a group of similarly named data elements (constituting an InfoCategory) contained in the configuration file. An InfoCategory includes: an InfoType, a DisplayName, a CmdLineOption, a Platform element, a ZipDir, and one or more WorkItems.
InfoType
This element identifies the type of information to be collected. Valid types are FileSet and RegKeySet. The name of this element is formed as follows: InfoCategory name + _InfoType.
DisplayName
This element identifies the message key used by Z and I Emulator for Web for the message to be displayed to the user in the Information Bundler Java GUI panel (for example, KEY_IB_EXTENSION_01 causes Extension01 to be displayed). These messages are defined as follows: KEY_IB_EXTENSION_xx, where xx is the extension number (01-32). The name of this element is formed as follows: InfoCategory name + _DisplayName.
CmdLineOption
This element specifies the text string to be used as a command line option to identify an information category. Examples of this are: sec, for SecurityFiles; ext01, for Extension01. On the command line, the command line parameter must be preceded by a '-' (for example, '-ext01'). The name of this element is formed as follows: InfoCategory name + _CmdLineOption.
Platform
This element specifies the platform types on which the information category is valid. Valid platform types are: AIX (including Linux and Solaris), Win32, i5/OS, OS/400, and MVS. For example, the HODRegKeys category is valid only for the Win32 platform type. When the utility is run, a category that is not valid for the current platform is skipped. The name of this element is formed as follows: InfoCategory name + _Platform.
ZipDir
This optional element specifies a text string to be used as a top-level ZIP entry directory for an Information Category (for example, test would cause all ZIP entry paths for the information category to begin with .\test\). The name of this element is formed as follows: InfoCategory name + _ZipDir. For no ZIP entry directory name, specify none.
WorkItemList and WorkItem references
This element specifies a list of one or more sets of information to be collected. The name of this element is formed as follows: InfoCategory name + _WorkItemList (for example, Extension01_WorkItemList). The list must contain one or more WorkItem references. A WorkItem reference has the form: WorkItem_ + numeral (for example, WorkItem_1, WorkItem_2).
WorkItem
This element describes a set of information to be collected. The name of this element is formed as follows: InfoCategory name + _ + WorkItem reference (for example, Extension01_WorkItem_1). When the InfoType is FileSet, the WorkItem contains the following subelements: DirType, DirName, SubdirSearchDepth, Include, and Exclude. When the InfoType is RegKeySet, the WorkItem contains RegKey subelements.
PlatformWI
This subelement can occur within a WorkItem element when the InfoType of the InfoCategory is FileSet. This subelement is optional. For the WorkItem in which it occurs, this subelement narrows the scope of the Platform command which otherwise controls the InfoCategory. For example, the SecurityFiles InfoCategory has SecurityFiles_Platform set to 'win32; aix; mvs; os400', indicating that this InfoCategory applies to all four platform types. However, Security_Files_WorkItem_1 has a PlatformWI subelement set to 'win32, aix, mvs', indicating that this particular work item applies only to the three specified platform types.
DirType
This subelement occurs within a WorkItem element when the InfoType of the InfoCategory is FileSet. This subelement describes the relation of the directory to be searched to the system's file structure. Valid types are:
RelativeToInstall
The utility will search in the Z and I Emulator for Web install directory for the subdirectory specified in the DirName subelement.
RelativeToPublish
The utility will search in the Z and I Emulator for Web publish directory for the subdirectory specified in the DirName subelement.
RelativeToDir
The utility will search in the subdirectory specified in the DirName subelement.
Absolute
The utility will ignore the DirName element and search for the file using the file path specified in the Include subelement.
DirName
This subelement occurs within a WorkItem element when the InfoType is FileSet, and when the DirType is RelativeToInstall, RelativeToPublish, or RelativeToDir. This element specifies the path of the subdirectory to be searched. The value may be any valid path including .. For RelativeToInstall and RelativeToPublish, the DirName should be a relative directory path. For RelativeToDirectory, the DirName should be an absolute directory path.
SubdirSearchDepth
This subelement occurs within a WorkItem element when the InfoType is FileSet. This element specifies how many subdirectories deep the search for Include files should continue from the beginning directory. Valid values are: 0, 1, 2, 3, etc.. . To search all subdirectories, specify all. The maximum allowed search depth is determined by the amount of memory available in the JVM.
Include
This subelement occurs within a WorkItem element when the InfoType is FileSet. This subelement specifies a list of one or more files to be collected. The file name after the last file separator may contain the wild card characters '?' (which matches any one character, except '.') and '*' (which matches 0 or more characters, except '.'). When the utility runs, it will attempt to collect all files matching the pattern.
Exclude
This subelement occurs within a WorkItem element when the InfoType is FileSet. This subelement specifies a list of one or more files to be excluded. The file name after the last file separator may contain the wild card characters '?' (which matches any one character, except '.') and '*' (which matches 0 or more characters, except '.'). When the utility runs, it will reject files matching the pattern.
RegKey
This subelement occurs within a WorkItem element when the InfoType is RegKeySet. This subelement defines a Microsoft Windows registry subkey to be read.

Top of page Table of contents