Fault Analyzer plug-in for WebSphere Developer for System z V7.0 user manual

 

Features

Basic configuration requirements

FA perspective

FA artefacts view

FA views or fault history file view

Working with FA report browser

Working with FA dump storage browser

Host installation

Features

Basic configuration requirements

Verifying FA plug-in installation

The following steps should be followed to verify the installation of FA plug-in.

  1. Select Help.
  2. Select About IBM WebSphere Developer for System z.
  3. Select Plug-in Details.
  4. Click on plug-in ID header field so that the list of plug-ins is sorted by their IDs.
  5. Look for com.ibm.etools.fa.FAClientPlugin.
  6. Verify the version (should be 0.9.0).

Establishing RSE connection

The most of actions contributed by the FA plug-in assume a connection to a z/OS host is established before actions are invoked. The following steps should be followed to establish a connection to a z/OS host.

  1. Open z/OS project perspective.
  2. Double click on z/OS… under new connections.
  3. Specify the host name and follow the wizard to establish a connection (Some information required by the wizard are installation dependent, eg. Port number. Please refer to your system programmer for the details of host installation).
  4. Once new connection wizard is completed successfully, a new item should be added in the remote systems view which represents the connection.
  5. Expand the newly created system icon in the view to verify the connection can be established correctly with the host. Eg. Expand MVS Files to browse a list of data sets.
  6. Once a connection profile is established, actions contributed by the FA plug-in should be ready to function.

 

NOTE: FA plug-in actions only require a connection profile to exist in order to function correctly. Some actions are functional without being connected to the host as long as cached data is available locally. Cached data is used first and only asks for the actual connection to be established only when the required data is not available locally. For example, the content of a report is cached once you browse a report associated with a fault entry. The report can be browsed offline second time.


FA perspective

Figure 1 illustrates a typical configuration of FA perspective. The FA plug-in contributes two views (FA artefacts view [1] and FA views or fault history files [2]), and two browsers (FA report browser and FA dump storage browser [3]).

 

Figure 1: Overview of FA perspective

 

 

Views contributed by the FA plug-in can be displayed in any other perspective. Follow the following steps:

  1. Select Windows.
  2. Select Show Views and select others.
  3. Under IBM Fault Analyzer category, you should see view contributions by the FA plug-in.
  4. Select view to display then press ok.

FA artefacts view

FA artefacts view allows you to manage a set of views and fault history files which you are currently working with potentially from multiple systems. Items in this view are organised hierarchically as follows:

 

System name: This is the top element in the view which represents a system which you are interested in working with. The name is taken from the selected RSE connection profile. System names are expandable, which contain history files and views.

 

History files: A list of history files which you are working with. Multiple history files can be added to the view under this category. History files are expandable which contain history file entries.

 

Views: A set of views you are currently working with. The definition of these views must be setup in the PDS(E) data set on the host. The FA plug-in provides an action which retrieves the definition and populates the FA artefacts views. Vies are expandable which contain view names.

 

View name: A view describes a set of fault history files and fault entries in these files are displayed concurrently. A view name corresponds to a member in a PDS(E) data set and its description is derived from the first comment line in the member if one exists. View names are expandable which contain history file entries. When a view name is double clicked, FA views or fault history files views is populated using  all fault entries contained in all history files included in the view definition.

 

History file: A history file corresponds to a PDS(E) data set which contains faults that have been analysed by Fault Analyzer. When a history file is doubled clicked in the view, FA views or fault history files view is populated using all fault entries contained in the selected history file.

 

Actions in FA artefacts view

All actions in this view are available from the context menu. Depending on the selection made in the view, a different set of actions will be made accessible (see Figure 2).

 

Add new history file

This action allows you to add a history file from a particular host to the view. The name of a data set which corresponds to the history file of interest must be specified explicitly via dialog.

 

Input field name

Description

RSE Connection Name

Name of the RSE connection profile which corresponds to a z/OS host where the history file is located.

History File Name

Name of the history file (data set name) to be added to the view.

 

Figure 2: Invoking actions in FA artefacts view

 

Retrieve last accessed history files

This action retrieves a list of recently accessed history files on the host based on the information stored in your ISPF profile. A list of recently used history files as well as views are stored and retrieved on the host. However, only the list of recently used history files is retrieved by the plug-in.

 

Input field name

Description

RSE Connection Name

Name of the RSE connection profile which corresponds to a z/OS host where history files exist.

ISPF Profile Name

Name of a data set which contains your ISPF profile. The use of ‘USERID()’ at the beginning of entry will be replaced with your user ID as you authenticate with the host. For example, ‘USERID().ISPF.ISPPROF’ for a user name ‘USRXYZ’ will be ‘USRXYZ.ISPF.ISPPROF’.

Temporary DSN

This is the name of temporary data set which will be used to copy your ISPF profile while retrieving the recently accessed history files information. The person who is invoking the action must have authority to write to the data set. If the data set exists on the host, it will be deleted without any warning.

Exec name

REXX exec is used to retrieve your ISPF profile. The location of exec ‘IDIISPST’ must be specified.

FA Application ID

Application ID of Fault Analyzer installation on the host.

 

Retrieve view information

This action retrieves information about view definitions which are stored in a data set on the host. Based on the definition found in the specified data set, the view is populated with the retrieved information.

 

 

Input field name

Description

RSE Connection Name

Name of the RSE connection profile which corresponds to a z/OS host where a data set with view definition exists. 

View Data Set Name

Name of the data set which contains the definition of views.

 

 

Delete from view

This action deletes the selected item from the view. It deletes the selected item from the view, but it does not delete the cached information about the selected item.

 

Populate/refresh history file

This action refreshes the cached information about the selected history file, and populates FA views or fault history file view using the latest information about the selected history file.

 

Configure history file monitor

A history file monitor can be configured to monitor the changes made to a history file on the host. The monitor can be configured for a history file via history file monitor configuration dialog, which is opened via Configure history file monitor action. In the dialog, you can specify the interval (in seconds) which represents how often the contents of the selected history file should be checked against what’s been cached locally. Whenever changes are detected, the user is notified.

 

NOTE: We do not recommend to setting the interval to a small value (eg. 10 seconds) to avoid the unnecessary traffic between the client and the host. This is particularly true when working with a history file which contains a large number of fault entries. If you would like to refresh the contents of a particular history file on the spot, you can use Populate/refresh history file action, which refreshes the selected history file contents immediately. 

 


FA views or fault history file view

FA views or fault history file view allows you to work with fault entries such as browsing the reports and storage dump display (Figure 3). The view provides a quick overview of fault entries included in the selected history file or view.

 

 

Figure 3: FA views or fault history file view

 

The column headings of the view are configurable depending on your preference. You can define a set of column configuration settings and switch between them. Figure 4 shows the column configuration dialog provided by the plug-in. Using the dialog, a different set of column headings can be added/removed and ordered to suit your preference. Table 1 lists all the headings available and their descriptions.

Figure 4: Column configuration

 

Table 1: Column headings description

Column heading

Description

Fault_ID

The ID assigned to the fault.

Abend

The initial (if more than one) abend code. For a fault entry created using IDISNAP, the abend code is shown as SNAP.

Appl_ID

The CICS application ID.

Class

The job class in which the job was executing.

Date

The date when the fault occurred in LOCALE-option dependent format.

Dup_Count

The number of duplicate faults detected.

Dup_Date

The date when the most recent duplicate fault occurred in LOCALE-option dependent format. If no duplicates have occurred, then this is set to the initial abend date (see Date).

Dup_Time

The time when the most recent duplicate fault occurred in LOCALE-option dependent format. If no duplicates have occurred, then this is set to the initial abend time (see Time).

EXEC_Pgm

The abending job step program name from the JCL EXEC PGM= parameter.

History_File_DSN

The history file data set name containing the displayed fault entry.

I_Abend

The abend code for which Fault Analyzer was invoked. For a fault entry created using IDISNAP, the abend code is shown as SNAP.

IMS_Pgm

The IMS application program name for faults involving IMS.

Job/Tran

For a CICS transaction abend, this is the CICS transaction ID. Otherwise, it is the name of the job that abended. This column combines information from the Jobname and Tran_ID columns.

Job_ID

The JES job ID of the abending job.

Job_Type

The abending job type as one of the following:

Batch Batch job

CICS CICS transaction

DumpReg Dump registration

STC Started task

TSO TSO user

Jobname

The name of the abending job.

Lock

The fault entry lock flag.

Minidump

Indication of minidump availability as follows:

Yes Minidump is available

No Minidump is not available

Module

The point-of-failure module name.

For dump registration fault entries, this is the name of the module identified in the SVC dump header SDWA as the load module involved in the error. Following initial reanalysis and fault entry refresh, this is updated to become the point-of-failure module name, which might be different.

MD_Pages

The number of minidump pages saved for the fault.

MVS_Dump

Indication of MVS dump availability as follows:

Yes MVS dump is available

No MVS dump is not available

MVS_Dump_DSN

The name of any associated MVS dump data set written at the same time as when the fault occurred.

Netname

CICS transaction netname.

Offset

The hexadecimal offset into the failing program where the point of failure occurred.

Program

The point-of-failure program name.

Stepname

The job step name of the abending job.

Sys/Job

For a CICS transaction abend, this is the CICS job name. Otherwise, it is the ID of the system on which the job abended. This column combines information from the System and Jobname columns.

System

The system ID on which the abend occurred.

Task

The failing CICS transaction task number. This column is only applicable to CICS faults.

Term_ID

CICS transaction terminal ID.

Time

The time when the fault occurred in LOCALE-option dependent format.

Tran_ID

The failing CICS transaction ID. This column is only applicable to CICS

User_ID

The user ID associated with the abending job/transaction.

User_Title

User-maintained title information.

Username

User-maintained name information.

 

Actions FA views or fault history file view

All actions in this view are available from the context menu.

 

Browse report

This action retrieves the report associated with the selected fault entry and displays the report. Before retrieving the report from the host, the action checks to see if cached data is available. If the report is cached, then it uses the local copy. See Working with FA report browser for further details.

 

Browse mini-dump

This action retrieves the mini-dump pages associated with the selected fault entry and displays pages stored as part of the fault entry. Before retrieving the mini-dump pages from the host, the action checks to see if cached data is available. If the pages are cached, then it uses the local cached data. See Working with FA dump storage browser for further details.

 

Delete cached data

This action deletes the cached data associated with the selected fault entry, which includes abend analysis report and mini-dump pages.

 


Working with FA report browser

FA Report Browser (Figure 5) is a multi-tabbed browser which displays the report associated with the selected fault entry. The browser is typically invoked by running the browse report action in the FA views or fault history file view.

 

Different sections of a report are organized using tabs and sections. The tabs categorize the report into main report, system wide information and miscellaneous information. The contents of a different tab are accessible via the tabs at the bottom of the report. Each tab contains sections to display different aspects of the report, some of which are collapsible to aid the ease of navigation within the report.

 

Figure 5: FA report browser features

NOTE: FA plug-in contributes the FA report browser to files with an extension of “.far”. To ensure the FA report browser is invoked, check the file association settings in the preference page.

  1. Select Window, Preferences to bring up the preference page.
  2. Expand General, Editors, and select File Association.
  3. Find *.far in the file types view and select the entry.
  4. Ensure FA Report Browser is selected as default in the associated editors view.

Working with FA dump storage browser

FA Dump Browser (Figure 6) is a multi-tabbed browser, which allows you to browse the mini-dump pages stored in the selected fault entry in a history file. This browser is typically opened via Open mini-dump action against a fault entry in the summary view. It provides a similar functionality to dump storage display in the ISPF environment (show command).

 

Figure 6: FA dump browser

 

Pressing CTRL+F brings up a search dialog (Figure 7) which allows you to search for a pattern in the mini-dump pages. You can either search using hexadecimal value or String value (converted to EBCDIC equivalent to search). As a pattern is found, the starting location of the pattern is highlighted in the browser. You can search through multiple occurrence of the pattern in the mini-dump pages by pressing the Find button repeatedly.

 

Figure 7: Search dialog

A user is able to add user notes to the dump display at the preferred address just like the user note list during the interactive analysis in the storage display in the ISPF environment. A new user note can be added by selecting User Note from the context menu in the browser. When mini-dump pages are copied from the host, user notes associated with the fault entry are copied down and the entries are created in the user note display. However, new user notes are not saved back to the fault entry on the host.

 

Figure 8: User notes feature in FA Dump Browser

 

NOTE: FA plug-in contributes the FA dump browser to files with an extension of “.md”. To ensure the FA dump browser is invoked, check the file association settings in the preference page.

  1. Select Window, Preferences to bring up the preference page.
  2. Expand General, Editors, and select File Association.
  3. Find *.md in the file types view and select the entry.
  4. Ensure FA Dump Browser is selected as default in the associated editors view.

 


Host installation

This document assumes the host installation of WDz components is complete and verified. Please refer to WebSphere Developer for zSeries Host Configuration Guide (SC31-6930-00) for further information.

 

Configurations on z/OS

IBM Fault Analyzer for z/OS plug-in for WDz V7 requires IBM Fault Analyzer for z/OS V7.1.0 (program number 5655-R46, FMID HAC4710) with PTF UK23264 applied on the host.

 

Three REXX execs are provided as part of the host PTF (IDICSXDS, IDICGPR1, IDICGPR2) in IDISIDIEXEC data set (by default). In IDICSXDS, SYSEXECDSN variable must be changed to the data set name containing these execs.