CICS Explorer troubleshooting
If a problem occurs with the CICS Explorer, you might be able to resolve it yourself. If you cannot resolve the problem yourself, you must gather the necessary information or documentation before contacting your IBM Support Center.
In this chapter, we describe some of the most common errors that are experienced with the CICS Explorer. Also, we explain where the CICS Explorer stores diagnostic data and how this data can be displayed or collected prior to calling IBM Support.
13.1 Common Explorer connection problems
Table 13-1 lists some of the known connection problems. Although this is not a comprehensive list, these are some of the more common problems.
Table 13-1 Common connection problems
CNX Messages
Description
Section
CNX0104E
Connection failed with exception NOTAVAILABLE, CPSMAPI
5.1.1
CNX0104E
Connection failed with exception The markup in the document preceding the root element must be well-formed
5.1.2
CNX0104E
Connection failed with exception The element type “HR” must be terminated by the matching end tags </HR>
5.1.3
CNX0106E
Connect failed with error Forbidden
5.1.4
13.1.1 Connection not available, CPSMAPI
The CICS Explorer is attempting to connect using the System Management Single Server (SMSS) connection. The Explorer fails with the message in Figure 13-1 on page 265.
Figure 13-1 CNX0104E Connection failed with exception NOTAVAILABLE, CPSMAPI
With this error there are a few things you must verify:
•Is the SMSS active in the CICS region? If you view the JESMSGLG, you will want to see the following messages:
 – EYUX0001I applid SMSS initialization program starting
 – EYUXL0003I applid CPSM Version 410 SMSS startup in progress
 – EYUXL0022I applid SMSS Phase I initialization complete
 – EYUXL0007I applid SMSS Phase II initialization complete
 – EYUNL0099I applid SMSS SMSS LRT initialization complete
Also, make sure the TCPIPServices and URIMAP are created and installed. You can check MSGUSR in the CICS SMSS region to confirm this.
•Additionally, make sure SEYUAUTH or SEYULOAD are included in your start-up JCL. If it is not, the Explorer will fail with the same CNX0104E error message in Figure 13-1 on page 265. Ensure that SEYULOAD is in DFHRPL, and not in the STEPLIB.
13.1.2 Connection must be well-formed
The CNX0104E message, Figure 13-2, can have multiple reason why it is generated.
Figure 13-2 CNX0104E Connection failed with exception... element must be well-formed
The error might be because the CICS Explorer is trying to connect to a CICS region with a TCP/IPService port of 9037. The failure occurs because the URIMAP, with path /CICSSystemManagement/*, installed does not reference the TCP/IPService of port 9037. Figure 13-3 shows that there is a mismatch in the TCP/IPSerivce name (EXPLORER and XPLORER).
Figure 13-3 Mismatch in the TCP/IPService name
Another potential reason for this error to occur is because of the CICS-Supplied Group DFHWU not being installed. This supplied group contains the resource definitions for CICS Management Client Interface (CMCI), and therefore, it is essential for it to be installed. Figure 13-4 shows DFHWU is installed in the region.
Figure 13-4 Installed Supplied Group DFHWU
13.1.3 Connection missing <HR> tag
When the message in Figure 13-5 on page 268 is displayed, the connection type is set for CMCI, but the specified port number that is being used applies to the CICSPlex SM Data Interface. Ensure that you are using the correct port number for the connection type you are trying to establish.
Figure 13-5 CNX0104E Connection failed with exception... </HR>
Figure 13-6 shows the correct port number for each of the two interfaces.
Figure 13-6 Port numbers the connection types use
13.1.4 Connection error forbidden
A connection is attempting to be made with the CMCI to a single CICS region; however, this region is contained within a CICSPlex environment. The error in Figure 13-7 on page 269 is displayed.
Figure 13-7 CNX0106E Connect failed with error Forbidden
Because there are multiple regions within a CICSPlex environment a single connection cannot be made to this CICS region. For this connection to be successful, you must remove this single CICS region from the CICSPlex environment.
If none of the errors or messages pertain to your problem, or you cannot correct your problem, the next step is for you to contact IBM Support to further investigate the issue. The remaining sections of this chapter explain where the diagnostic data is located and what information/data to collect prior to contacting IBM Support.
13.2 Workspace and logs
The CICS Explorer uses a folder, known as the workspace, to save all of its settings between user sessions and to store a log of its activity, including any errors that might occur.
On Microsoft Windows operating systems, the default CICS Explorer workspace is located at:
C:Documents and Settings<username> .cicsexplorer
On Linux operating systems, the default CICS Explorer workspace is located at:
/home/<username>/.cicsexplorer
If you are not using the default settings but are starting the CICS Explorer with the -data command line (or shortcut on Microsoft Windows operating systems) option to use an alternate workspace location, you probably already know what workspace folder you are using.
The workspace folder contains, among other data, two logs:
•The Eclipse log is where errors, which are internal to the Eclipse platform that the CICS Explorer uses, can be recorded. It is contained in the file:
<workspace>/.metadata/.log
•The IBM CICS Explorer’s own set of tracing files:
<workspace>/.metadata/.cicsexplorer.trace.NN.log
 
IBM CICS Explorer’s tracing files: There might be up to 10 files like this one with NN=0 for the most recent to NN=9 for the oldest one and up to 1 MB in size each.
13.2.1 Capturing trace data
When the CICS Explorer is running it is constantly recording trace information in its trace buffers. If there is an unexpected failure, the CICS Explorer automatically writes the trace information out to the error log to help identify the cause of the failure. You can force the current information in the trace buffers to be written to disk using the Explorer → Trace → Flush menu option.
The tracing information is written to disk in the set of tracing files <workspace>/.metadata/.cicsexplorer.trace.NN.log.
Because the tracing facility is built using the standard Java logging API, the same tracing information can also be sent to a custom Handler, which you can achieve by launching the CICS Explorer with a command line (or shortcut on On Microsoft Windows operating systems), such as:
cicsexplorer -vmargs -Djava.util.logging.config.file=myfile
In the example, myfile, is the name of a Java Properties file that is written according to the Java logging API.
The myfile configuration can, for instance, specify additional FileHandlers with different formatting or filtering than the default tracing; however, this is likely to have a detrimental performance effect if buffering is not adequate.
13.2.2 Tracing options
The default tracing granularity is adequate, but it can be further enhanced:
1. Create a text file, and in the same directory where the CICS Explorer executable file resides, name it .options.
2. Inside the text file, add the lines that IBM service requests, as shown in Example 13-1.
Example 13-1 Options text file
#Example .options file for CICS Explorer
#
com.ibm.cics.core.ui/general=true
com.ibm.cics.core.ui/selection=false
com.ibm.cics.core.ui/draganddrop=false
com.ibm.cics.core.ui/resources=false
com.ibm.cics.core.ui/connection=false
com.ibm.cics.core.ui/adapters=false
com.ibm.cics.core.ui/preferences=false
com.ibm.cics.core.ui/decorators=false
com.ibm.cics.core.ui/properties=false
#
com.ibm.cics.core.model/general=true
com.ibm.cics.core.model/selection=false
com.ibm.cics.core.model/resources=false
com.ibm.cics.core.model/adapters=false
#
com.ibm.cics.core.ui.editors/markWithColors=false
com.ibm.cics.core.ui.editors/controls=false
com.ibm.cics.core.ui.editors/bindings=false
com.ibm.cics.core.ui.editors/propertysheet=false
com.ibm.cics.core.ui.editors/actions=false
#
com.ibm.cics.model/attributes=false
#
com.ibm.cics.sm.comm/general=true
com.ibm.cics.sm.comm/record=false
#
com.ibm.cics.sm.comm.cpsm/general=true
 
3. To use the .options file, start the CICSExplorer with the command line option -debug.
On Microsoft Windows operating systems, instead of using a command prompt window, you can append the -debug option to a shortcut created for the CICS Explorer executable.
Another alternative to specifying a command line option, on all the platforms, is to edit the cicsexplorer.ini file.
 
File backup: Saving a cicseplorer.ini file that contains syntax errors or is missing essential options, can cause CICS Explorer to fail to start. Create a back up of the file before you edit it.
13.2.3 The Error Log View
The Error Log View displays information messages, warnings, and errors that the CICS Explorer logs. The underlying log file is where errors that are internal to the Eclipse platform that the CICS Explorer uses, can be recorded. It is contained in the file:
<workspace>/.metadata/.log
The Error Log View is accessed from the Window → Show View → Error Log menu option.
The Error Log View is provided for information only. Figure 13-8 shows information messages and error messages. The error messages are simulated for this example because typically the log does not contain errors. If the view contains errors, contact your IBM Service representative for advice.
Figure 13-8 Error Log View
The CICS Explorer help contains a detailed description of the sorting, filtering, and export capabilities of the Error Log View.
13.2.4 Viewing the error log in an external application
You can view the Eclipse log in an external application, such as a text editor or a browser.
1. From the menu bar, click Help → About IBM CICS Explorer. The About IBM CICS Explorer window is displayed, as shown in Figure 13-9.
Figure 13-9 About IBM CICS Explorer
2. Click Configuration Details. The Configuration Details view is displayed, as shown in Figure 13-10 on page 274.
Figure 13-10 Configuration Details window
3. Click View Error Log. You are presented with a list of programs that can be used to open and display the log.
4. Select a text editor or browser from the list, and then click OK.
The Configuration Details is a comprehensive set of information about your CICS Explorer installation that can be of great help to IBM Service when an error report is submitted.
13.3 Preparing error data for IBM service
If you have a problem with the CICS Explorer, you might be asked to send the error logs and other information to the IBM service representative. The CICS Explorer collects all necessary error information in a single-compressed file that is ready for sending.
To prepare error data for IBM service:
1. From the workspace menu bar, click Explorer → Trace → Collect Service Data.
2. In the Save Service data as file dialog, select the location where you want to save the compressed file, and click Save.
The service data is saved as a compressed file. The filename is in the format CICSExplorerServiceData-20090701-080311.zip, where the numbers indicate the date and time of the collected data.
The zip file contains all of the diagnostic information that we described so far:
•Eclipse log
•CICS Explorer traces
•Configuration details
It also contains the CICS Explorer configuration settings, such as your defined connections and the set of columns to display in the resource views. It does NOT contain your saved passwords, which are stored encrypted on disk.
Remember to record the actions that you were performing at the time the failure occurred, which assists the IBM service representative if the problem requires further analysis.
13.3.1 Collecting error data when the CICS Explorer is not usable
If you cannot use the CICS Explorer user interface to collect service data, for example, because of a start up failure or because the user interface is unresponsive, you can at least create an archive file (for example in zip format on Microsoft Windows and in tar format on Linux) of all the traces, logs, and settings. This archive file does not include the comprehensive Configuration details that are available through the user interface.
Simply use an archiving utility to collect the directory content of your workspace location.
You might want to remove the file where the passwords are stored because although they are encrypted, they can be recovered:
<workspace>/.metadata/.plugins/com.ibm.cics.eclipse.common/com.ibm.cics.core.ui.secure_storage
If the user interface is up but hanging and unresponsive, creating a Java Thread Dump might be useful.
Creating a Java Thread Dump on Linux:
1. Obtain the process ID of the CICS Explorer using any system tool, for example, from a shell (command line) enter:
$ ps -ef | grep cicsexplorer
2. From a shell, invoke kill -QUIT <process_id>, and a file named javacore.YYYYMMDD.<other>.txt is created in the CICS Explorer directory.
3. Add the file to the archive that contains the workspace data.
Creating a Java Thread Dump on Windows:
1. The CICS Explorer must have been started with the -consolelog parameter, which in addition to the graphical UI window, also opens a shell (command line) window only for output.
2. If a dump was not taken, enter the key combination CTRL-BREAK from that command line window to request a dump.
3. From the console log window, you will see a message that includes the location and name of the dump that you send to IBM, for example:
JVMDUMP010I Java dump written to C:...CICS Explorerjavacore.20090610.092732.6908.0001.txt
4. Add the file to the archive that contains the workspace data.
13.3.2 Searching for IBM MustGather information
The IBM support website contains additional documentation for preparing data for service. You can search the IBM website for CICS Explorer MustGather.
13.4 Plug-in specific issues
In this section, we describe special cases that affect the plug-ins.
13.4.1 Performance Analyzer
In this section, we discuss the Performance Analyzer.
CSV file corruption
It is critical that the csv file that is used in the PA plug-in was created by the PA runtime and was not modified in any way. Unfortunately, this includes a situation when a csv file is viewed using Excel. Excel restructures the time field in a manner that makes it relatively unusable by the PA plug-in. If when the application is closed Excel offers to save updates even though none were knowingly made, the file is corrupted and must be downloaded from the server again.
13.4.2 CSV file size and CICS Explorer runtime memory
The CSV file is held in java memory and is therefore restricted by factors that are external to the Explorer, including system memory. If you are using csv files, this might cause OutOfMemory Exceptions when an inadequate Java heap size is allocated. There is no hard rule to what needs to be allocated and many users find that the default maximum heap size is perfectly sufficient. However, it might be necessary in some circumstances to increase the value:
1. In a Windows or Linux command line, change the directory to the directory where the cicsexplorer.exe (cicsexplorer on Linux) file is located.
2. Start the CICS Explorer by typing the following command:
cicsexplorer -vmargs -Xmx512m
3. Alternatively, you can modify the cicsexplorer.ini file in the CICS _Explorer subdirectory to add the following information:
 – -vmargs
 – -Xms128m
 – -Xmx512m
4. Start the CICS Explorer as normal.
..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset