Problem determination aids

The following traces and logs can help you find and resolve problems:

1. Server trace and message facility collects information about the Redirector and configuration services.
2. Messages, which list the Z and I Emulator for Web error messages.
3. Client trace and message facility collects information about host sessions.
4. Java Console (Netscape) or Java Log (Internet Explorer) collects information about Java events.
5. Printer Definition Table Compiler log collects information when you create a PDT.
6. Operator Information Area (OIA) in the session window displays session status and messages.
7. Printer Status window of a printer session displays printer status and messages.
8. Z and I Emulator for Web Service Manager messages provide information regarding the Service Manager.
9. Transport trace captures the Telnet TCP/IP Emulator data flow between the client and Telnet server.
10. IPMonitor is a Java utility that collects trace information containing the session data flowing between a client and a host.
11. Information Bundler gathers diagnostic information from a Z and I Emulator for Web server installation.
12. Service Manager trace collects information about the Service Manager.
13. Tracing the client download gathers diagnostic information about client downloads.

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.

The client trace and message facility is available only on clients that include the problem determination functions. These clients include:

• Problem Determination client (defaultdebug.html)
• Database client (database.html)
• New user client cached with problem determination (NewUserCachedDebug.html)

From the Actions menu in a host session window, you can choose to view the log messages, which opens the Message Console, or to open the Trace Facility window. You can also do the latter by clicking the Trace button on the toolbar. For Database On-Demand, you can set up tracing by clicking Options > Trace > Start Trace Facility.

The information in the Message Console is saved in the same file as the trace information, but you can also copy it to the clipboard and save it in a text file. You may be asked to do this by service personnel.

When you start the Trace Facility, you have to make several choices about which function or component you will trace and about the trace level, which determines the amount of data that will be collected. You can also decide whether to save the data to the Java Console or Log, and to the server or to the local disk. In general, an HCL service person will tell you what the settings should be.

As an administrator, you will either have to tell a user how to start a problem determination client and what choices to make, or load the client yourself and try to reproduce the problem.

We recommend you save the file locally on the client, in case you need to send the file to a system administrator or HCL support. Also, if you save the file locally, you can choose the directory in which to save the file.

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

For more information about using the message and trace facilities, refer to:

• Viewing a User's Trace
• Log and Trace Messages Format
• Setting Trace Levels
• Changing the trace settings (client)

The Java Console or Java Log collects information about Java events, but you can also choose to have Z and I Emulator for Web messages and trace data saved here. You can turn on the Java Console for both Netscape and Internet Explorer. You can also view the Microsoft Javalog.txt in the Java directory (winnt\java) on Windows.

The Printer Definition Table Compiler log (pdtc.log) collects progress and error information each time you create a PDT. The error information is intended to help you make corrections to the PDF that you have customized.

The Operator Information Area (OIA) is normally visible at the bottom of a session window, although it can be turned off when a session is configured. The OIA contains several items of information that indicate the status of the session and of its connection. Printer status window

The Printer Status window of a printer session is the equivalent of the session window of a display session. It provides a graphical display of the connections between the host system or server, the session and the printer, and displays various error messages. It is fully described in the online help. There is more specific information about resolving printer session problems in the Troubleshooting appendix of the Host Printing Reference.

On a client, you might see the message:

System problem.  Contact your system administrator.  Error= -41. 

On a server, you might see:

LOG0001: Z and I Emulator for Web cannot be used.... 

These messages indicate one or more of the following:

• The Service Manager is on the other side of a firewall and the browser cannot connect to it. This might be because the port that the Service Manager uses (8999) is not open on the firewall.
• A network problem has prevented connection to the Service Manager.
• The Service Manager is not started or is not operational.

The Transport Trace captures the Telnet TCP/IP Emulator data flow between the client and Telnet server. Use the problem determination clients to capture the data flow. For example, you can use defaultdebug.html. You can access the problem determination clients from dashboard.html.

To use the Transport Trace, take the following steps:

1. Start the host session you want to trace, and log on to the host system.
2. Select Assist from the session menu.
3. Select Problem Determination.
4. Select Trace Facility.
5. Click Host Access Class Library in the Function window to highlight it.
6. Click Transport in the Component window to highlight it.
7. Click Level 1 in the Trace Level window to highlight it.
8. Click Settings.
   • Set the file to be saved on the local machine.
   • Click OK.
9. Click Start.
10. End the session. You must return to your Z and I Emulator for Web start page, for example, default.html.
11. Start the session again.
12. Follow the steps to recreate the problem.
13. Click Stop.
14. Click Save. The Save window displays.
15. Select location to save the trace file to, and name the trace file.

IPMonitor is a Java utility you can use to collect trace information containing the session data flowing between a client and a host. IPMonitor is an intermediary between a client and a host. The client connects to IPMonitor, while IPMonitor connects to the host. IPMonitor then records session data flowing between the client and the host. You can start IPMonitor as a Java application or as a Java applet.

You start and configure IPMonitor differently, whether IPMonitor is running as an application or an applet, and which version and release of Z and I Emulator for Web you are running.

• IPMonitor
• Configuring the IPMonitor HTML parameter
• IPMonitor v1.0 for Java
• Using the IPMonitor v1.0 for Java application
• Starting the IPMonitor v1.0 for Java application
• IPMonitor v1.0 for Java, automatic mode
• IPMonitor v1.0 for Java, normal mode
• Starting the IPMonitor v1.0 for Java, normal mode applet from the Run Applet session menu option

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:

• Registry keys (Windows NT, Windows XP, and Windows 2000 systems only)
• Private files
• Security files
• Published HTML files
• Properties files
• JavaScript files
• NSM properties files
• Deployment Wizard files
• Printer Definition files
• DirUtil files
• User-defined font files
• DWunzip files
• IPMonitor trace files
• Custom groups of files that you configure in the configuration 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
• Information Bundler command line options
• Information Bundler GUI
• Adding a custom extension to the Information Bundler

To run the Information Bundler, do the following:

• On Windows NT, Windows 2000, and Windows XP platforms, do one of the following:
  • Select Start > Programs > HCL Z and I Emulator for Web > Administration > Information Bundler
  • Run the following script:
    install_dir\lib\samples\InfoBundler\InfBnd.cmd
• On the AIX platform, run the following script at the command line:

  install_dir/lib/samples/InfBndCommandFiles/InfBnd-AIX

• On the Solaris and Linux platforms, run the following script at the command line:

  install_dir/lib/samples/InfBndCommandFiles/InfBnd-UNIX

• On the Novell Netware platform, run the following script at the command line:

  install_dir/lib/samples/InfBndCommandFiles/InfBnd-Novell.ncf

• On the OS/2 platform, run the following script at the command line:

  install_dir/lib/samples/InfBndCommandFiles/InfBnd-OS2.cmd

• On the i5/OS and OS/400 platforms, run the following script at the command line:

  install_dir/lib/samples/InfBndCommandFiles/InfBnd-OS400.sh

• On the z/OS platform, run the following script at the command line:

  install_dir/lib/samples/InfBndCommandFiles/InfBnd-S390

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.

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.

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.

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.

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.

To gather trace information about client downloads, update the HTML file that downloads the Z and I Emulator for Web client by editing the HTML with the Deployment Wizard. Check Debug Client and add an additional parameter of DebugCode with a value of 65535.

HCL will need a detailed Web server trace showing the files being downloaded and any error message logs produced by this Web server. For an HTTP webserver, the trace is called a VV trace (very verbose), or LOGLEVEL of debug.